Validate element
See also: Validate element and call profile
Behaviour – Abstract
The behaviour Validate element triggers the validation of a specific element (including any other elements it may contain) or the entire form and returns the element data back to the actions.
If (as in the image above) no element is linked, the form, including all contained elements, is validated, so that, for example, the triggers Form is valid or Form is invalid may respond.
If, on the other hand, an element is linked (see Behaviours for details) this element is validated. If the link refers to an element that contains other elements (for example, an Element containers), these elements are also validated.
Regardless of whether the validation affects an entire form, a substructure, or an individual element, the applicable check criteria for each element depend on the following circumstances, (see slso Form elements):
An element that is considered active and qualifies as a required field must be 'filled' with a value (not equal to $null) to be valid. Whether or not it is visible at the time of validation has no influence on this.
If individual validity rules are configured for an element by Validators, (e.g. to check a regular expression), these are only checked if the element is active and visible at the time of validation.
Inactive elements and their child elements are always considered valid without checking any criteria.
Only if each element to be checked meets all applicable check criteria, the Actions on 'true' will be executed.
If at least one applicable criterion of an element to be checked is failed, the Actions on 'false' are executed instead.
Regardless of the result of the validation, the behaviour in both cases transfers the same data to the actions to be executed. Data provided depends on the distinction between the following cases:
Without option Return parent data, the data related to the starting point of the validation is returned.
If no element is linked, the entire form data is returned.
If an element with a data field is linked, its data and the data from all directly and indirectly contained elements are returned.
If an element without a data field is linked, its parent element hierarchy (possibly up to form level) is examined in ascending order until an element with a data field is found and its data returned.
If the option Return parent data is set, the following different rule applies for the second case in the above list, while the others remain unchanged:
If an element with a data field is linked, the data object immediately above it in the data hierarchy is returned, which includes the data of the linked element and any elements it contains.
The Return parent data option can thus facilitate working with complex structures, since the same behaviour can limit the validation to a specific subset of a data object, while still providing an extended scope of information for the actions. The use of the option is demonstrated in a separate example (below).
The optional parameter Validation result variable specifies the name of a form variable, in which during the validation, validation hints from all elements checked as 'invalid' are collected as a list. If several applicable check criteria are failed for the same element, only the hint with the highest priority will be considered. Hints assigned by Set hint are ignored, even if they effectively overwrite the validation hint in the form.
The specified variable is cleared before validation, so that its value is empty ($null) after successful validation.
If the validation fails, the variable in the context of the form provides the collected validation hints even after the execution of the current behaviour has finished. They can be processed further immediately or later using the calculation function var (Read form variable) (see the second example below).
Where relevant, the individual notes are localized taking into account the current locale (as far as applicable, Localization, Company specific localization or translations within the form may apply).
Examples
Example involving 'Return parent data'
An entry form contains a plural free-enumeration attribute (see Free enum type), which is used to specify one or more ‘Available aircraft’ in the data of a business object. The free enumeration type used refers to a user-defined dynamic enumeration, which allows the selection of just one aircraft type for each instance of the plural attribute by dropdown field enumValue. In addition, for each ‘Available aircraft’ a specific identifier, the ‘registration’, shall be entered in the text field ‘Text Value’(textValue) which the data structure of a free enumeration attribute features as an optional field.
The following table compares how this data structure appears in the XML export for the relevant business object (left) and in the data of a detail form (right):
Example:
|
XML export (extract) |
Console output of behaviour data (extract) |
|
The following extract from an XML export shows the first two entries for the plural free-enumeration attribute. ...<attributes> ... <shp:ShipmentFreeEnum ... > <value enumValue="ACFT#A380" freeEnumType="ACFT" index="0"> <textValue>DACKL</textValue> </value> </shp:ShipmentFreeEnum> <shp:ShipmentFreeEnum ... > <value enumValue="ACFT#JU52" freeEnumType="ACFT" index="1"> <textValue>DAQUI</textValue> </value> </shp:ShipmentFreeEnum> ...</attributes>... |
The following screenshot shows, for the same data, the output of the action Log to console in an Validate element behaviour, that was executed for this purpose for each individual entry of the plural attribute. For this purpose, the repeated element (Column layout) of the Repeatable element was linked to the attribute that refers to the data field value in the form.
The output present here bears no reference to data field value (see value element in XML on the left). However, all properties of the individual attribute instance appear clearly identifiable as data belonging to the same level:
This is less obvious in the XML structure on the left. Although the data all belongs to the same value element, it appears at different levels (as an XML attribute or text in a child element). To understand how the Deliver parent data option works, the data hierarchy is crucial, which can be directly traced in the console output. Activating the Deliver parent level option for the behaviour used above results in the following output for the same attribute instances:
Here the data field value (which contains all the object data listed above) appears by name and together with other details for the ShipmentFreeEnum layer lavel have been omitted in the XML structure (‘...’). |
In the detail form, the Text field for the registration is defined as a mandatory field and a Validators (‘Regular expression’ type) is added, which should check the formal validation criteria for text entered as a ‘registration’. Among other things, a registration that begins with the letter D must consist of exactly five capital letters. The separator (minus ‘-’), which the ICAO standard specifies according to the nationality (‘D’ for Germany), is explicitly omitted here.
For the display of Available aircraft, the ‘Grid’ display type was selected in the form, which concisely displays numerous entries. Since indications of ‘validation problems’ are only visible for the currently selected list entry in this display, a check of all list entries is offered via the Check registration button, which, if necessary, draws attention to inadmissible data via the Show alert action. In the screenshot, two of the specified registrations are invalid:
The message text provides information that can be used to locate incorrect entries in the list. Next to the Aircraft type (enumValue field), which can occur several times in the list, the unique specification of the list row appears (automatically filled field index with start value 0).
Configuration:
The crucial Behaviour type 'Validate element' is configured directly for the validating element (‘registration’), but without defining a Triggering event.
Nevertheless, an explicit link to this element must still be set up for the behaviour, otherwise the entire form will be validated.
The option Return parent data is ticked so that the action Show alert (see Actions on ‘false’) receives the data of the whole list entry and not only the value of the validated element. Without this option, only the entered registration, i.e. the literal from the textValue element (see XML data structure above) would be returned.
Actions on 'true' are not provided here.
If the validation fails, that is, if the value for a registration is invalid, the action Show alert is executed. The Alert message uses information from the parent data of the validated element:
{enumValue} automatically returns the applicable localization entry for the ‘Aircraft type’ selected for an entry.
{index} returns the row number (with start value 0) for the current list entry.
The alert Type ‘Warning’ is selected, so that several notes may appear below each other on the right-hand side of the screen.
The trigger for the validation of all existing entries is provided by the button, for which a behaviour is configured to respond to the Triggering event ‘Clicked’.
As a Behaviour type, first of all the Validate element is executed for the Repeatable element Available aircraft (green arrow/frame).
This validation is successful if all (active) elements contained within it are valid. Then a global success message is displayed by a Show alert action (not expanded on the screen).
Otherwise, a Execute behaviour action calls the behaviour with Behaviour name ‘check’ (described above) of the ‘registration’ element For duplicates also (red arrow). The alerts defined there will then appear for all invalid registrations.
Example involving 'Validation result variable'
In an input form for Shipments, data already entered or provided via an interface should be validated in the context of the form before it is 'submitted' to another system. If the form contains 'invalid' data, the corresponding 'Validation hints' should appear as a list in an alert box and also in a Tree element in the form (embedded portal, see Embed forms (Sub-forms)). As the example below illustrates, an advantage of this summary is that the invalid data can be partially contained in Expandable elements and still end up directly visible.
Runtime example:
After clicking the Check data and submit Button, the Tree element below lists all Validation errors found in the form.
While the validation hints from 'Line items' would be immediately obvious in this situation (with only 2 positions), without the summary in the tree, all Expandable elements for addresses would have to be opened to find any errors there.
The listed Validation errors can be processed specifically and the check can also be repeated iteratively so that corrected errors disappear from the list.
Configuration:
|
|
For the Check data and submit Button ', a behaviour is created that reacts to the trigger Click (not in the screenshot) and uses the Behaviour type Validate element with the following configuration:
|
