Best practices for expressions involving repeating panel
Repeating panels are instances of a panel that are added or removed dynamically, using scripting API or pre-populated data. For detailed information about using repeating panel, see creating forms with repeatable sections.
-
To create a repeating panel, in the panel dialog, open settings, and set value of the max count field to more than 1.
-
The min count value of panel repeat settings can be one or more but cannot be more than max count value.
-
When an expression refers to a field of repeating panel, the field names in the expression are resolved to the closest repeating element.
-
Adaptive forms provide a few special functions to simplify computation for repeatable panels such as sum, count, min, max, filter, and many more. For the complete list of functions, see JavaScript Library API reference for adaptive forms
-
APIs for manipulating instances of repeating panel are:
- To add a panel instance:
panel1.instanceManager.addInstance()
- To get a panel repeat index:
panel1.instanceIndex
- To get the instanceManager of a panel:
_panel1 or panel1.instanceManager
- To remove an instance of a panel:
_panel1.removeInstance(panel1.instanceIndex)
- To add a panel instance:
Expression Types
In adaptive forms, you can write expressions to add behaviors such as dynamic show/hide fields and panels. You can also write expressions to add calculated fields, make fields read-only, validation logic, and many more. Adaptive forms support following expressions:
- Access expressions: to enable/disable a field.
- Calculate expressions: to auto-compute value of a field.
- Click expression: to handle actions on click event of a button.
- Initialization Script: perform an action on initialization of a field.
- Options expression: to dynamically fill a drop-down list.
- Summary expression: to dynamically compute the title of an accordion.
- Validate expressions: to validate a field.
- Value Commit Script: to change the components of a form after the value of a field is changed.
- Visibility expression: to control visibility of a field and panel.
- Step completion expression: to prevent a user from going to next step of a wizard.
Access Expression (Enablement Expression)
You can use the access expression to enable or disable a field. If the expression uses value of a field, whenever the value of the field changes the expression is retriggered.
Applies to: fields
Return Type: The expression returns a Boolean value, representing whether the field is enabled or disabled. true represents that the field is enabled and false represents the field is disabled.
Example: To enable a field only when the value of field1 is set to X, the access expression is: field1.value == "X"
Calculate Expression
The calculate expression is used to auto-compute the value of a field using an expression. Typically, such expression use value property of another fields. For example, field2.value + field3.value
. Whenever value of the field2
or field3
changes, the expression is retriggered and the value is recomputed.
Applies to: fields
Return Type: The expression returns a value that is compatible to the field where the expression result is displayed (for example, decimal).
Example: The calculate expression to show sum of two fields in field1 is:field2.value + field3.value
Click Expression
The click expression handles the actions performed on the click event of a button. Out of the box, GuideBridge provides APIs to perform various functions such as submit, validate that are used along with the click expression. For complete list of the APIs, see GuideBridge APIs.
Applies to: Button fields
Return Type: The click expression does not return any value. If any expression returns a value, the value is ignored.
Example: To populate a text box textbox1 on the click action of a button with value AEM Forms, the click expression of the button is textbox1.value="AEM Forms"
Initialization Script
The initialization script is triggered when an adaptive form is initialized. Depending on scenarios, the initialization script behaves in the following manner:
- When an adaptive form is rendered without a data prefill, the initialization script runs after the form is initialized.
- When an adaptive form is rendered with a data prefill, the script is run after the pre-fill operation completes.
- When server sided revalidation of an adaptive form is triggered, the initialization script is executed.
Applies to: fields and panel
Return Type: The Initialization script expression does not return any value. If any expression returns a value, the value is ignored.
Example: In a data pre-fill scenario, to populate fields with default value 'Adaptive Forms'
when their value is saved as null, the initialization script expression is:if(this.value==null) this.value='Adaptive Forms';
Options Expression
The options expression is used to dynamically fill options of a drop-down list field.
Applies to: drop-down list fields
Return Type: The options expression returns an array of string values. Each value can be a simple string, such as Male, or in a key=value pair format, such as 1=Male
Example: To populate value of a field, based on the value of another field, provide a simple options expression. For example, to populate a field, Number of Kids, based on the Marital Status expressed in another field, the expression is:
marital_status.value == "married" ? ["1=One", "2=two"] : ["0=Zero"]
.
Whenever the value of marital_status field changes, the expression is retriggered. You can also populate the dropdown from a REST service. For detailed information, see Dynamically populating dropdowns.
Summary Expression
The Summary expression dynamically computes the title of a child panel of an accordion layout panel. You can specify the Summary expression in a rule, which uses a form field or a custom logic to evaluate the title. The expression executes when the form initializes. If you are prefilling a form, the expression executes after the data is prefilled or when the value of dependent fields used in the expression change.
The Summary expression is typically used for repeating children of an accordion layout panel to provide meaningful title to each child panel.
Applies to: Panels that are direct children of a panel whose layout is configured as Accordion.
Return Type: The expression returns a String that becomes the title of the accordion.
Example: "Account number : " + textbox1.value