Add element (optional/repeatable element)
Actions – Abstract
The Add element action is used to add a single new element to an Optional elements container or a Repeatable element container.
The Add element action can be used to add a single new element to one of the following container types:
Optional elements container
Repeatable element container
The action is only available as a choice for Action type, if an appropriate target element has been selected. Configuration details are described in sections below for each container type.
Executing the action Add element is equivalent to clicking the 
symbol for the corresponding context and may assume that role completely, e.g. if the symbol is defined as invisible in a form where adding elements should only be driven by behaviours.
Elements can be removed from both types of containers by the related action Remove element (optional/repeatable element).
|
Context: Optional elements |
Context: Repeatable element |
|
|
|
While no specific parameters apply for the context of a Optional elements container, the following options may be applicable for a Repeatable element:
When the option Apply data of the behaviour is set, any input data provided to the action ($input) will be applied to the element added by the action, which otherwise would be initialized with 'empty data'.
The option Select new element is only available if the Repeatable element uses the 'Grid' view type. When the option is set, the element added by the action receives focus in the grid, so its details are indicated and ready for editing, as far as applicable.
Optional elements container
In combination with an Optional elements container, the action must refer to exactly one of the optional elements within the container as a target element.
When the action is executed, the option specified as a target element is added as the last item in the container, unless it is already included.
Configuration example:
The position of a parked aircraft may be specified by indications for Location and/or Area.
A form features one Text field for each property included in a Optional elements container.
Each optional entry field should appear on demand by a dedicated Ribbon button (Portal).
The default symbols
and 
should not appear in the form at runtime.
A behaviour (e.g. Static/true) is assigned for each button that triggers the 'Add element' action in response to a Click event:
Results:
|
View of initial state of form |
After clicking 'Area' button |
After clicking 'Location' button |
|
|
|
|
Repeatable element
In combination with a Repeatable element container, the action adds new elements as instances of the container content, which is called a repeated element.
Where (and sometimes if) new instances are inserted in the container depends on the following factors:
Is the action called by the behaviour of an element within the repeated element, which enables a reference to a specific instance at runtime, or outside?
Is the container element itself or the repeated element linked to the action as a target element?
Is the option For duplicates also checked or unchecked for the action?
Does the container already contain elements or is it empty?
Is the container property Max. entries set to a value > 0 and would this number of entries be exceeded when the action is executed?
The following table defines alternative objectives regarding the position for added elements and respective configurations:
|
Objective |
Configuration |
||
|
Add entry... |
Action called from... |
Target element |
Option 'For duplicates also' |
|
as the first element of the container |
outside the repeated element |
repeated element |
unchecked |
|
as the last element of the container |
insignificant |
container |
insignificant |
|
after a certain element in the container |
within the repeated element |
repeated element |
unchecked |
|
after each element in the container |
insignificant |
insignificant |
checked |
Configuration example:
A Repeatable element 'Aircraft list' is used to manage a list of 'Aircraft' as elements with properties Registration and Aircraft type.
New aircraft should be added by the Add aircraft button.
To facilitate interactive editing of multiple aircraft, a new element should automatically be added to the list when on 'Focus out' for the Aircraft type combobox.
For the Add aircraft button, a behaviour containing the following action is configured:
This behaviour could be addressed by Execute behaviour (action) on Focus out (event) for Aircraft type. Then new elements are always added at the end of the list.
Instead, the action for adding the element can be linked immediately in a behaviour triggered on Focus out (event) for Aircraft type, to ensure that new elements can be added within the list:
►NOTE◄ The target element in this instance of the action points at the 'Column layout' container Aircraft, which is highlighted in the layout screenshot above. With the action initiated by the Aircraft type combobox inside the repeatable element, each new element is added after the current 'Aircraft'.
Results:
|
Initial situation |
After clicking button 'Add aircraft' |
|
|
A new element (aircraft) appears:
Required fields of the new element are populated:
On 'Focus out' for Aircraft type, the next new element pops up below:
|
Option 'Apply data of the behaviour'
The option Apply data of the behaviour is only available for the 'Repeatable element' container. With this option set, the data returned by the behaviour is applied to the added element.
Example:
Values for the fields firstName and lastName entered in one specific container, should be applied to a new element added to a Repeatable element container when a Button (see mouse cursor) is clicked.
Configuration:
For easy orientation, the element labels reflect the data field names in this example.
Clicking the
button triggers the behaviour shown in the screenshot, which validates the data in the 'source' container (element # 6). The Add element (optional/repeatable element) action applies this data to the element added to the target element 'persons' (Repeatable element # 3).