Form

Description

Show a form to the user, either updateable or read-only.

The form can be configured with a dataReference, a form, or both.

  • If just dataReference is passed, the form definition and data is read from the node identified by data reference, and this is updated when the form is submitted.
  • If just form is passed, the form definition and initial data is read from the config. The form is not saved, but the form is written to the "form" attribute so that it can be accessed by the next step in the process.
  • If dataReference and form are both passed, the form definition is read from config and the data is created or overwritten with the form definition when the form is saved. If dataOnly is set, only the data is written to the data area.

The outcome state is set according to the button pressed.

Configuration parameters:

dataReference Identifies the data node that contains the form, and which should be updated when the form is submitted.
dataOnly Set to true to indicate that the data area identified by dataReference contains only the data for the form. The form definition should not be read from the data area, data should be read from the data area (unless data is passed), and data should be written back to the data area.
form
Definition of the form.
data
Data with which to populate the form. This is used to extend the data in the form data definition. This option only makes sense when form is passed, not with dataReference (otherwise the data would always overwrite anything the user entered).
preserveForm
When passing the form definition, preserve the form definition to be accessed later. This is required whenever the form is passed in a runtime variable, e.g. "%{attr:editForm}". This adds a formDefinition field to the form that holds a unique reference to the form that can be used to re-retrieve the form definition in subsequent runs of the form.
content
Additional content to show before the form. This can be useful with readonly, when one user is reviewing content entered by another user.
readonly

Set to true to show the form but disallow editing.

The form itself may also be marked as readonly. If this is the case, then the readonly config option is ignored. You cannot update a readonly form by setting the readonly config option to false.

You can use the readonly option on fields to set fields on or off depending on the readonly value.

prepareScript

Optional script that will be run on the form definition before it is rendered. The script is run using the Eval Service and can only access data within the form. It will be passed the form definition in the data variable, and should return the form definition. The form data is in data.data.

The prepare script only modifies the form as it is rendered. It does not change the saved form. However, changes to data fields will be rendered on the form and the data will therefore be saved.

The prepare script is run after all modifications of the form, but prior to the conversion of FileInfo objects to node references. The field array and data object will always be present. Generated fields such as action will be present. Any file info (for upload fields) will be present.

As a very simple example, the code below sets data for the lastModified field to the current timestamp.

function(){
data.data.lastModified = application.localDateTime();
return data;
}()

The prepareScript can also be passed in the form definition itself. If both are passed, the script on the form definition is applied first and then the one in the config is applied. 

formClass

Additional class, or classes, to be added to the form. If the form has its own formClass properties, these will be appended.

This can be used to hide or show different bits of content in different scenarios.

state
What state to set. Follows the same format as the Set method.
state is always set to "show" when the form should be reshown, so next should always have "show": false or default to false.

Form supports runtime placeholders. User-specific runtime placeholders are evaluated relative to the user interface user, not the owner.

Modifications are made to the form definition:

  • The method is set to "execute".
  • A hidden field for action is added, or the existing one changed.
  • A hidden field for redirect is added, if it is not already present.
  • For upload fields, the file package is set to the form data node. The uploaded files are stored using file info conventions, allowing the form data to be moved around.
  • The form button name is generated based on the action name. This prevents form button name clashes between one action and the next, allowing control to flow directly from one form-based step to another in the process without complication.
  • The value of the pressed button is written to the data "button" property.

If the form property "firstTime" is set to true, then the form will be reshown even if the button has been pressed. The firstTime property will not be saved in the form definition if preserve is true. This can be used where the form, or the firstTime attribute, are created by runtime placeholders, to force a form to be re-entrant even after a submit.

 

Member Type List

Tab/SequenceWeightMember Type
Basic/
0
Basic/
0
Basic/description
0
Basic/tagList
0
Config/
0
Flow rules/flowRules
0

Set Tags

Tag List