Populate element data
See also: Set value, Populate empty element data
The Populate element data action populates the input data provided with $input as element data for a specific Target element or for the whole form.
If no target element is linked, the entire form is considered a Target element.
If a target element is linked, the element data for this element is set.
In contrast to the related '
Set value' action, which only allows you to assign individual field values, the
Populate element data
action is usually used to transfer complex data structures to a specific Target element.
Often an Element containers is linked as a Target element, which contains further Form elements with data field assignment as 'child elements', in which concrete field values from the assigned data should appear. This procedure is useful for transferring data when Embed forms (Sub-forms), for example. However, the Populate element data action can also use the Variable element, as a Target element if data objects are only to be 'deposited' without showing their contents.
Configuration options:
|
Option |
Description |
|
Ignore datafield |
If this option is set, the 'data field' optionally defined for the Target element is ignored when assigning the input data. If this option is not set, the 'data field' optionally defined for a Target element must be named in the input data in order for data to be assigned. |
|
Don't apply default values |
This option is set by default so that elements contained in the Target element are effectively cleared unless a value is assigned from the input data. If this option is not set, all elements contained in the Target element are assigned default values according to the form design, provided no value is assigned from the input data. |
|
Merge into original data |
This option is not set by default, so that a Target element without a data field is decoupled from the parent item with the original data by setting element data (for details see Scenario 2, below). If this option is set, the input data is not directly applied to a Target element without a data field, but is mapped to the higher-level original data (for details, see Scenario 3, below). ►NOTE◄ Setting this option automatically enables the As copy option. |
|
As copy |
This option is not set by default, so when setting the element data, the values are not automatically copied from the input data. If this option is set, values from the input data are automatically assigned as a copy to prevent accesses to data in the Target element from penetrating the original. ►NOTE◄ In connection with the Merge into original data, this option is automatically selected. |
Use cases for the 'Populate element data' action
The 'ranking' of potentially complex data objects in a form represents a great operative potential on the one hand. On the other hand, the successful use of the comparatively harmless action Populate element data against this background requires an appropriate understanding of the interaction of form data and form elements. The configuration options offered must be used 'suitably' depending on the objective and the exact conditions of use (elements involved, form types and data items) so that a configuration works robustly and reliably delivers the desired results. At this point, the combinational diversity of conceivable applications cannot be dealt with exhaustively, taking into account specific problems and contingencies.
In the following, some typical use cases are therefore presented using concrete scenarios to demonstrate the usage of the configuration options and to illustrate the principles of the action.
Scenario 1: A container refers to a data field that is to be updated with the set data.
If the Target element has an intact 'object relationship' (e.g. to the form data) until the action is executed at runtime, the action updates the contents of this data field without affecting this relationship.
A Target element, for which a data field is defined, is assigned detailed data from the input data according to the following rules:
If the Ignore data field option is not set (default), the target element is only assigned data that explicitly refers to this data field in the input data.
If the Ignore data field option is set, then the input data is assigned in total as detailed data of the Target element. Its data field is therefore 'ignored' during the assignment.
In both cases, 'child elements' contained in the Target element only display values from the assigned data if their data field definition matches the assigned data structure.
Example:
In a form, input data is set in a 'Person' container with the data field person, which contains details about a certain person without being summarized under a parent data field person.
The action Populate element data is executed with the container 'Person' as the Target element and the option Ignore data field set. The form elements 'name' and 'sex' are filled in, because the input data provide values for their data fields (name and sex). In addition, the data field person is also assigned the value '4711' in the data field id, to which no form element corresponds. This value remains invisible in the form, but becomes part of the form data in the data field person.
In the following variant, the input data contains entries for the data field person and other data that is not relevant for the Target element 'Person'. The action Populate element data is therefore executed without the option Ignore data field, so that only the data for the data field person is transferred to the form and the form data. The result is therefore identical to the first variant.
Scenario 2: A container without its own data field should use the set data separately from the parent data object.
If the option Merge into original data is not set, setting element data for a container without its own data field results in the connection of the contained 'child elements' with data field to the parent data item (e.g. the form data) being separated.
Specifically, the container is linked to a 'new' data item, which represents the data context for the contained 'child elements' from this point on. However, this data item is not embedded in the parent data item that previously had this role.
From this point on, assignments to the form elements contained in the separated container have no effect with regard to the corresponding fields in the 'original data' of the initial parent-level data item. They only affect the context of the newly introduced data item, but its content is not part of the form data. This separation can no longer be reversed without completely reloading the form data.
Nevertheless, this application scenario is relevant in practice because the data placed in the container can be 'useful' in many ways, even without reference to the form data.
Example:
In a form, a pre-selection of persons referred to as 'Candidates' is to be listed in a Repeatable element, without this list appearing in the form data. The form data should only list interactively selected 'Candidates', which are then transferred by clicking a Button in a second Repeatable element 'Attendees' with the data field attendees.
The following schema refers only to the first step, which is to list the 'Candidates' based on input data, such as a Search (Form designer) behaviour that is triggered after the user has filled in all criteria for the 'Candidate' search. The action Populate element data is linked to the Repeatable element container as the Target element. The option Merge into original data is not set. As a result, the Repeatable element container offers the candidates for selection, but without their data appearing in the form data, for example, if they were passed to a profile for confirmation of an appointment.
► NOTE◄ If there is no possibility that candidate data will appear in the form data, the data field of the Repeatable element container can also be set to 'Skip'. This separates or isolates the contents of the container from the form data from the very beginning. However, the option Ignore data field must then be set, which can be omitted for an empty data field.
Scenario 3: A Target element without its own data field contains elements with data that is to be updated in the parent data item.
If the option Merge into original data is set, the input data is not set directly for the Target element, so that its reference to the parent data item is retained. Instead, the input data is mapped to the 'child elements' contained in the Target element, if appropriate, after they have been cleared or – if the option Don't apply default values is deselected – filled with default values. If the input data contains data fields for which there are no entries for the 'original data', these are added there. However, updating fields for which values already exist is limited to data fields to which 'child elements' of the Target element are related..
Example:
A form contains an 'address' container with the data field address, which combines a variety of address characteristics. The form uses a child container 'Location' without its own data field to group the characteristics 'Street' ( street ), 'Zip code' ( zipcode ), 'City' ( city ) and 'Country' ( country ).
The characteristics grouped as 'Location' can be compared with entries in an address database via a Button in the form. If it provides a 'suitable' entry for the addressee, this can be transferred on request. The data of the 'replacement address' is available as input data ($input) from the behaviour, if the action Populate element data is to be executed. This refers to the 'Location' container as a Target element with the option Merge into original data. Since the option Don't apply default values is also set, the data in the Target element ('Location' container) is first cleared. The corresponding values are then transferred from the input data to the 'Location' container. The 'Street' remains empty, because there is no information from the database for the data field street. The 'Name' is not overwritten, because the Target element does not contain an element with the data field name. The data field source in the input data is not present in the 'original data' of the parent data field address. It is therefore added to it, but remains invisible.
►NOTE◄ If the same method is then used to set input data (with a different value for source) other than element data to the same Target element again, the source data field is not updated because it is not related to an element in the 'Location' container.
