Populate empty element data
Actions – Abstract
Populates a new empty object as element data of the target element. If no target element is specified, the form itself is used.
See also: Populate element data.
The Populate empty element data action creates a new empty object and assigns it to a specified target element as element data.
The target element can optionally be explicitly assigned by a link.
If no target element is linked, the complete form is considered a target element.
This action is typically used to reset element data of an object that is linked via a data field to an Element containers that contains several form elements related to data fields of the object.
The Don't apply default values option decides whether the data fields will be assigned a default value ($init) defined for the Form elements, if any, or 'No value' ($null).
Populating empty element data always deletes all data fields of the data object in question that are not represented by Form elements.
Form elements that are not within the substructure downward from the target element, but still refer to form data changed by the action, are not automatically updated by the Populate empty element data data action. They therefore display values that may differ from the 'data state' until they are 'reloaded' with element data (see third example below for details).
CAUTION
Using the Populate empty element data action in Input forms can lead to 'breaking up' the data structure, which is basically specified there by the entity type in a binding manner. For example, setting 'empty element data' to an input form for Users would ensure that the Form elements contained in the input form no longer refer to the entity type for which the input form was opened. Inputs can then be made but no longer saved.
Examples
Simple use case
A simple portal (see Portals) is used to 'pre-record' key data from which an entity representing a 'Shipment' can be created in a second step of the workflow. To avoid duplicates, however, it should be checked beforehand whether a 'Shipment' already exists for which key values from the portal match.
For the screenshot, the names of the data fields used were entered as labels of the relevant form elements. The JSON structure on the right shows the 'structure export' for the portal, i.e. its form data.
|
Runtime view of the portal |
JSON image of the form data |
|
|
{ |
When the RESET Button below the trackingId text field is clicked, the Form elements to the right of the Button element, which are in a Column layout container with the button element, should be 'reset'.
If available, the default values of the contained Form elements should be assigned to the data fields. Otherwise: 'No value' ($null).
Configuration:
CAUTION
The following configuration only 'nearly' works. It is intended to document a common misconception that can lead to unexpected results. The 'Remeby' section refers to working solutions.
|
A behaviour with the name 'reset' is set up for the Button and configured as shown on the right:
|
|
Runtime example:
|
Process step |
Runtime view of the portal |
JSON image of the form data |
|
The portal has just been opened: The screenshot on the right shows the portal with the default values defined in the layout:
No default value is provided for the other fields (confirmedDate, cne). |
|
{ |
|
The portal was edited:
The form data (see last column) reflects the changes to the form elements inside (blue) and outside (black) the 'Details' container. |
|
{ |
|
The 'RESET' Button was clicked:
Therefore, it looks like the RESET Button via the Populate empty element data action had the desired effect and only reset the 'Details'. However, this is a misconception, as a look at the form data proves! |
|
{ |
|
The form data for elements in the 'Details' container, which was previously displayed in
blue
, now differs from the current values in the container and is therefore displayed in
red
. |
||
|
A changed string was entered in the trackingId Text field:
|
|
{ |
What happened?
Since the Populate empty element data action was applied here to a container that does not have its own data field associated with it, the action destroys the connection of the Form elements to the form data within the container.
Form elements in the 'emptied' container work fine on the surface, but no longer have any influence on the form data.
Form elements outside the 'emptied' container continue to be related to the form data as usual.
Remedy:
A data field (details) can be associated with the 'Details' container. Then the Populate empty element data action refers to this data field because it is associated with the 'Details' element.
The action then deletes all data in the details field, including data in fields that are not represented by Form elements at all in the portal, but were already included in the form data when it was opened.
If Form elements are present in the container, their default value assignments for data fields will be taken into account if the Don't apply default values option is unchecked.
Of course, the data field (details) then also appears as an object ("details":{ ... }) in the structure of the form data and summarizes the associated element data.
Alternatively, the link for the Target element could also be removed. Then the Populate empty element data action applies to the entire form.
The action then creates a completely new 'client object' and assigns it as form data (formData). Thereby all Form elements are linked to this new data object.
If the option Don't apply default values is unchecked, the default values defined for Form elements, if any, will also be set.
The input for the trackingId Text field is of course also lost. In the example, the default text 'XQ' appears instead.
More complex use case
In the use case from the previous example, the portal should fulfill additional requirements:
|
In addition to the 'Details' of the shipment shown above, some specific characteristics for the contents of the shipment should be selectable/unselectable as flags (flags):
In the screenshot on the right, the names of the data fields are again displayed as labels. In the JSON image of the form data (far right), the data of the indicators grouped in a field/object flags are highlighted in blue . The insurance (insurance) flag should be selected by default. All others are unselected. |
|
{ }, }, |
As seen in the screenshot, the portal should be able to be reset gradually:
The RESET Button at the very top is to reset the portal altogether.
The RESET Button to the left of the tab panel element should reset the contents of the tabs for details and flags.
The RESET Button in the flags tab should exclusively reset the flags available in this tab.
Configuration:
As stated in the previous example, the Populate empty element data action should be applied to Element containers if they are related to a data object via a data field whose data is to be 'deleted' and then enriched with default values from the form elements in the container, if necessary.
As shown in the form data above, in addition to the 'Details' field (see previous example), there is a 'Flags' field that combines all indicators as Boolean fields in one object.
Obviously there is no parent field/object that merges 'all data in the Tab panel element'.
|
The 'resetFlags' behaviour on the right is configured for the RESET ▼ Button in the flags tab:
►NOTE◄ The screenshot shows the default values for the Check box elements in the flags tab:
|
|
As long as there is no parent data field for all data in the Tab panel element, the 'resetting' of the two tabs must be solved this way:
|
The 'reset' behaviour on the right is configured for the RESET ► Button to the left of the Tab panel element:
►NOTE◄ The only way to simplify the procedure is to address a higher-level data field. However, this would then also inevitably appear in the data structure of the form data.. Instead of the second call of the Populate empty element data action, the 'resetFlags' behaviour could also be called via an Execute behaviour action. This would ensure that the same logic (e.g. for the option Don't apply default values) reliably applies for resetting the flags in both cases. |
|
Runtime example:
|
|
|
|
{ } |
Clicking the RESET Button in the flags tab will exclusively reset the data in the "flags" field, while the data in the "details" field and the trackingId will be preserved.
Even more complex use case
The use case from the previous example is now to be made even more 'complicated' in order to show another potential conflict in the context of the Populate empty element data action and a mitigation possibility:
|
At the header level of the portal, an additional 'test' indicator is offered, which can be used to signal that the input is test data. The feature can, for example, control whether certain steps in a triggered workflow take place or not. As can be seen in the screenshot on the right, not only the mimic (icon and check box with display type 'toggle box') is based on the configurations in the flags tab. Also the reference to the data field name flags.text in the caption makes clear that the flag should be located together with the others in the field/object "flags", although it is placed in the form header. |
|
{ ►NOTE◄ As the JSON image of the form data above shows, the "test" flag (highlighted in blue above) appears as desired along with the other flags in the "flags" field when selected or 'turned on' as in the image. |
The extension seems to work as desired at first. However, the use of the Populate empty element data action within the flags tab raises critical questions:
Is the "test" flag deleted when the RESET ▼ Button in the flags tab is pressed?
Is the relationship between the form data and the Check box element in the header damaged by the reset?
Is a default value (ON) set for the check box element when the RESET ▼ Button in the flags tab executes the Populate empty element data action with Don't apply default values unchecked?
We clarify this step by step below:
Runtime example:
|
|
← Initial situation:
Clicking the RESET ▼ Button in the flags tab does not change the appearance of the portal in this situation. |
JSON image of the form data after the 'RESET': { ►IMPORTANT◄
|
The resulting 'imbalance' between the display of the "test" Check box and the form data, does not correct itself:
The data field references flags.test and would pull the current value (false/null) from the 'reset' data for the flags field/object if the Check box element 'asks'.
Interactively, the Check box could be turned off. Then the Check box element and the form data would be synchronized again. But this step should certainly not be left to the user.
Remedy:
|
In order to ensure that after a 'RESET' in the flags tab, all Form elements outside the tab also take the changed form data into account, the Reload element data action should be executed directly after the action Populate empty element data:
►IMPORTANT◄ Assigning default values affects all Form elements that refer to data fields for which the form data does not contain a value ($null), and not just those 'emptied' by the previous action, for example. In this respect, there are certainly also scenarios in which it may make sense to treat the Don't apply default values option differently in both actions. |
|
