Adaptive forms rule editor adaptive-forms-rule-editor

Adobe recommends using the modern and extensible data capture Core Componentsfor creating new Adaptive Formsor adding Adaptive Forms to AEM Sites pages. These components represent a significant advancement in Adaptive Forms creation, ensuring impressive user experiences. This article describes older approach to author Adaptive Forms using foundation components.

Overview overview

The rule editor feature in Adobe Experience Manager Forms empowers forms business users and developers to write rules on adaptive form objects. These rules define actions to trigger on form objects based on preset conditions, user inputs, and user actions on the form. It helps further streamline the form filling experience ensuring accuracy and speed.

The rule editor provides an intuitive and simplified user interface to write rules. Rule editor offers a visual editor for all the users. In addition, only for forms power users, rule editor provides a code editor to write rules and scripts.

Rule editor replaces the scripting capabilities in AEM 6.1 Forms and earlier releases. However, your existing scripts are preserved in the new rule editor. For more information about working with existing scripts in the rule editor, see Impact of rule editor on existing scripts.

Users added to the forms-power-users group can create new scripts and edit existing ones. Users in the forms-users group can use the scripts but not create or edit scripts.

Understanding a rule understanding-a-rule

A rule is a combination of actions and conditions. In rule editor, actions include activities such as hide, show, enable, disable, or compute the value of an object in a form. Conditions are Boolean expressions that are evaluated by performing checks and operations on the state, value, or property of a form object. Actions are performed based on the value ( True or False) returned by evaluating a condition.

The rule editor provides a set of predefined rule types, such as When, Show, Hide, Enable, Disable, Set Value Of, and Validate to help you write rules. Each rule type lets you define conditions and actions in a rule. The document further explains each rule type in detail.

A rule typically follows one of the following constructs:

Condition-Action In this construct, a rule first defines a condition followed by an action to trigger. The construct is comparable to if-then statement in programming languages.

In rule editor, the When rule type enforces the condition-action construct.

Action-Condition In this construct, a rule first defines an action to trigger followed by conditions for evaluation. Another variation of this construct is action-condition-alternate action, which also defines an alternate action to trigger if the condition returns False.

The Show, Hide, Enable, Disable, Set Value Of, and Validate rule types in rule editor enforce the action-condition rule construct. By default, the alternate action for Show is Hide and for Enable is Disable, and conversely. You cannot change the default alternate action.

For more information about rule types available in the rule editor, see Available rule types in rule editor.

Guidelines for choosing a rule construct guidelines-for-choosing-a-rule-construct

While you can achieve most of the use cases by using any rule construct, here are some guidelines to choose one construct over another. For more information about the available rules in rule editor, see Available rule types in rule editor.

Available operator types and events in rule editor available-operator-types-and-events-in-rule-editor

The rule editor provides the following logical operators and events using which you can create rules.

Available rule types in rule editor available-rule-types-in-rule-editor

The rule editor provides a set of predefined rule types that you can use to write rules. Let’s look at each rule type in detail. For more information about writing rules in rule editor, see Write rules.

When whenruletype

The When rule type follows the condition-action-alternate action rule construct, or sometimes, just the condition-action construct. In this rule type, you first specify a condition for evaluation followed by an action to trigger if the condition is satisfied ( True). While using the When rule type, you can use multiple AND and OR operators to create nested expressions.

Using the When rule type, you can evaluate a condition on a form object and perform actions on one or more objects.

In plain words, a typical When rule is structured as follows:

When on Object A:

(Condition 1 AND Condition 2 OR Condition 3) is TRUE;

Then, do the following:

Action 2 on Object B;
AND
Action 3 on Object C;

_

When you have a multi-value component, such as radio buttons or list, while creating a rule for that component the options are automatically retrieved and made available to the rule creator. You need not type the option values again.

For example, a list has four options: Red, Blue, Green, and Yellow. While creating the rule, the options (radio buttons) are automatically retrieved and made available to the rule creator as following:

While writing a When rule, you can trigger the Clear Value Of action. Clear Value Of action clears the value of the specified object. Having Clear Value of as an option in the When statement lets you create complex conditions with multiple fields.

Hide Hides the specified object.

Show Shows the specified object.

Enable Enables the specified object.

Disable Disables the specified object.

Invoke service Invokes a service configured in a form data model. When you choose the Invoke Service operation, a field appears. On tapping the field, it displays all services configured in all form data models on your AEM instance. On choosing a form data model service, additional fields appear where you can map form objects with input and output parameters for the specified service. See example rule for invoking form data model services.

In addition to form data model service, you can specify a direct WSDL URL to invoke a web service. However, a form data model service has many benefits and the recommended approach to invoke a service.

For more information about configuring services in form data model, see AEM Forms Data Integration.

Set value of Computes and sets the value of the specified object. You can set the object value to a string, the value of another object, the computed value using mathematical expression or function, the value of a property of an object, or the output value from a configured form data model service. When you choose the web service option, it displays all services configured in all form data models on your AEM instance. On choosing a form data model service, additional fields appear where you can map form objects with input and output parameters for the specified service.

For more information about configuring services in form data model, see AEM Forms Data Integration.

The Set Property rule type lets you set the value of a property of the specified object based on a condition action. You can set property to one of the following:

It enables you to define rules to add check boxes dynamically to the adaptive form. You can use custom function, a form object, or an object property to define a rule.

To define a rule based on a custom function, select Function Output from the drop-down list, and drag-and-drop a custom function from the Functions tab. If the condition action is met, the number of checkboxes defined in the custom function are added to the adaptive form.

To define a rule based on a form object, select Form Object from the drop-down list, and drag-and-drop a form object from the Form Objects tab. If the condition action is met, the number of checkboxes defined in the form object are added to the adaptive form.

A Set Property rule based on an object property lets you add the number of checkboxes in an adaptive form based on another object property that is included in the adaptive form.

The following figure depicts an example of dynamically adding checkboxes based on the number of drop-down lists in the adaptive form:

Clear Value Of Clears the value of the specified object.

Set Focus Sets focus on the specified object.

Save Form Saves the form.

Submit Forms Submits the form.

Reset Form Resets the form.

Validate Form Validates the form.

Add Instance Adds an instance of the specified repeatable panel or table row.

Remove Instance Removes an instance of the specified repeatable panel or table row.

Navigate to Navigates to other Interactive Communications, adaptive forms, other assets such as images or document fragments, or an external URL. For more information, see Add button to the Interactive Communication.

Set Value of set-value-of

The Set Value of rule type lets you set the value of a form object depending on whether the specified condition is satisfied or not. The value can be set to a value of another object, a literal string, a value derived from a mathematical expression or a function, a value of a property of another object, or the output of a form data model service. Similarly, you can check for a condition on a component, string, property, or values derived from a function or mathematical expression.

The Set Value Of rule type is not available for all form objects, such as panels and toolbar buttons. A standard Set Value Of rule has the following structure:

Set value of Object A to:

(string ABC) OR
(object property X of Object C) OR
(value from a function) OR
(value from a mathematical expression) OR
(output value of a data model service or web service);

When (optional):

(Condition 1 AND Condition 2 AND Condition 3) is TRUE;

The following example takes the value in dependentid field as input and sets the value of the Relation field to the output of the Relation argument of the getDependent form data model service.

Example of Set Value rule using form data model service

Show show

Using the Show rule type, you can write a rule to show or hide a form object based on whether a condition is satisfied or not. The Show rule type also triggers the Hide action in case the condition is not satisfied or returns False.

A typical Show rule is structured as follows:

Show Object A;

When:

(Condition 1 OR Condition 2 OR Condition 3) is TRUE;

Else:

Hide Object A;

Hide hide

Similar to the Show rule type, you can use the Hide rule type to show or hide a form object based on whether a condition is satisfied or not. The Hide rule type also triggers the Show action in case the condition is not satisfied or returns False.

A typical Hide rule is structured as follows:

Hide Object A;

When:

(Condition 1 AND Condition 2 AND Condition 3) is TRUE;

Else:

Show Object A;

Enable enable

The Enable rule type lets you enable or disable a form object based on whether a condition is satisfied or not. The Enable rule type also triggers the Disable action in case the condition is not satisfied or returns False.

A typical Enable rule is structured as follows:

Enable Object A;

When:

(Condition 1 AND Condition 2 AND Condition 3) is TRUE;

Else:

Disable Object A;

Disable disable

Similar to the Enable rule type, the Disable rule type lets you enable or disable a form object based on whether a condition is satisfied or not. The Disable rule type also triggers the Enable action in case the condition is not satisfied or returns False.

A typical Disable rule is structured as follows:

Disable Object A;

When:

(Condition 1 OR Condition 2 OR Condition 3) is TRUE;

Else:

Enable Object A;

Validate validate

The Validate rule type validates the value in a field using an expression. For example, you can write an expression to check that the text box for specifying name doesn’t contain special characters or numbers.

A typical Validate rule is structured as follows:

Validate Object A;

Using:

(Expression 1 AND Expression 2 AND Expression 3) is TRUE;

Set Options Of setoptionsof

The Set Options Of rule type enables you to define rules to add check boxes dynamically to the adaptive form. You can use a form data model or a custom function to define the rule.

To define a rule based on a custom function, select Function Output from the drop-down list, and drag-and-drop a custom function from the Functions tab. The number of checkboxes defined in the custom function are added to the adaptive form.

To create a custom function, see custom functions in rule editor.

To define a rule based on a form data model:

Understanding the rule editor user interface understanding-the-rule-editor-user-interface

Rule editor provides a comprehensive yet simple user interface to write and manage rules. You can launch the rule editor user interface from within an adaptive form in authoring mode.

To launch the rule editor user interface:

Let’s look at each component of the rule editor UI in detail.

A. Component-rule display a-component-rule-display

Displays the title of the adaptive form object through which you launched the rule editor and the rule type currently selected. In the above example, the rule editor is launched from an adaptive form object titled Salary and the rule type selected is When.

B. Form objects and functions b-form-objects-and-functions-br

The pane on the left in the rule editor user interface includes two tabs — Forms Objects and Functions.

The Form Objects tab shows a hierarchical view of all objects contained in the adaptive form. It displays the title and type of the objects. When writing a rule, you can drag-drop form objects onto the rule editor. While creating or editing a rule when you drag-and-drop an object or function into a placeholder, the placeholder automatically takes the appropriate value type.

The form objects that have one or more valid rules applied are marked with a Green dot. If any of the rules applied to a form object is invalid, the form object is marked with a Yellow dot.

The Functions tab includes a set of built-in functions, such as Sum Of, Min Of, Max Of, Average Of, Number Of, and Validate Form. You can use these functions to compute values in repeatable panels and table rows and use them in action and condition statements when writing rules. You can, however, create custom functions too.

In the left tree of the form objects, you can select the form objects to display the rules applied to each of the objects. Not only you can navigate through the rules of the various form objects, you can also copy-paste rules between the form objects. For more information, see Copy-paste rules.

C. Form objects and functions toggle c-form-objects-and-functions-toggle-br

The toggle button, when tapped, toggles the form objects and functions pane.

D. Visual rule editor d-visual-rule-editor

Visual rule editor is the area in the visual editor mode of the rule editor user interface where you write rules. It lets you select a rule type and accordingly define conditions and actions. When defining conditions and actions in a rule, you can drag-drop form objects and functions from the Form Objects and Functions pane.

For more information about using visual rule editor, see Write rules.

E. Visual-code editors switcher e-visual-code-editors-switcher

Users in the forms-power-users group can access code editor. For other users, code editor is not available. If you have the rights, you can switch from visual editor mode to code editor mode of the rule editor, and conversely, using the switcher right above the rule editor. When you launch rule editor the first time, it opens in the visual editor mode. You can write rules in the visual editor mode or switch to the code editor mode to write a rule script. However, note that if you modify a rule or write a rule in code editor, you cannot switch back to the visual editor for that rule unless you clear the code editor.

AEM Forms tracks the rule editor mode you used last to write a rule. When you launch the rule editor next time, it opens in that mode. However, you can also configure a default mode to open the rule editor in the specified mode. To do so:

F. Done and cancel buttons f-done-and-cancel-buttons

The Done button is used to save a rule. You can save an incomplete rule. However, incomplete are invalid and don’t execute. Saved rules on a form object are listed when you launch the rule editor next time from the same form object. You can manage existing rules in that view. For more information, see Manage rules.

The Cancel button discards any changes you made to a rule and closes the rule editor.

Write rules write-rules

You can write rules using the visual rule editor or the code editor. When you launch the rule editor the first time, it opens in the visual editor mode. You can switch to the code editor mode and write rules. However, note that if you write or modify a rule in code editor, you cannot switch to the visual editor for that rule unless you clear the code editor. When you launch the rule editor next time, it opens in the mode that you used last to create rule.

Let’s first look at how to write rules using visual editor.

Using visual editor using-visual-editor

Let’s understand how to create a rule in visual editor using the following example form.

The Loan Requirements section in the example loan application form requires applicants to specify their marital status, salary, and if married, their spouse’s salary. Based on the user inputs, the rule computes the loan eligibility amount and displays in the Loan Eligibility field. Apply the following rules to implement the scenario:

Perform the following steps to write rules:

Using code editor using-code-editor

Users added to the forms-power-users group can use code editor. The rule editor auto generates the JavaScript code for any rule you create using visual editor. You can switch from visual editor to the code editor to view the generated code. However, if you modify the rule code in the code editor, you cannot switch back to the visual editor. If you prefer writing rules in code editor rather than visual editor, you can write rules afresh in the code editor. The visual-code editors switcher helps you switch between the two modes.

The code editor JavaScript is the expression language of adaptive forms. All the expressions are valid JavaScript expressions and use adaptive forms scripting model APIs. These expressions return values of certain types. For the complete list of adaptive forms classes, events, objects, and public APIs, see JavaScript Library API reference for adaptive forms.

For more information about guidelines to write rules in the code editor, see Adaptive Form Expressions.

While writing JavaScript code in the rule editor, the following visual cues help you with the structure and syntax:

Custom functions in rule editor custom-functions

Apart from the out-of-the-box functions like Sum of that are listed under Functions Output, you can write custom functions that you frequently need. Ensure that the function you write is accompanied by the jsdoc above it.

Accompanying jsdoc is required:

For more information, see usejsdoc.org.

Supported jsdoc tags:

Adding a custom function

For example, you want to add a custom function which calculates area of a square. Side length is the user input to the custom function, which is accepted using a numeric box in your form. The calculated output is displayed in another numeric box in your form. To add a custom function, you have to first create a client library, and then add it to the CRX repository.

Perform the following steps to create a client library and add it in the CRX repository.

After you have added your client library in the CRX repository, use it in your adaptive form. It lets you use your custom function as a rule in your form. Perform the following steps to add the client library in your adaptive form.

Function declaration supported types function-declaration-supported-types

Function Statement

function area(len) {
    return len*len;
}

This function is included without jsdoc comments.

Function Expression

var area;
//Some codes later
/** */
area = function(len) {
    return len*len;
};

Function Expression and Statement

var b={};
/** */
b.area = function(len) {
    return len*len;
}

Function Declaration as Variable

/** */
var x1,
    area = function(len) {
        return len*len;
    },
    x2 =5, x3 =true;

Limitation: custom function picks only the first function declaration from the variable list, if together. You can use function expression for every function declared.

Function Declaration as Object

var c = {
    b : {
        /** */
        area : function(len) {
            return len*len;
        }
    }
};

Manage rules manage-rules

Any existing rules on a form object are listed when you select the object and select . You can view the title and a preview the rule summary. Furthermore, the UI lets you expand and view the complete rule summary, change the order of rules, edit rules, and delete rules.

You can perform the following actions on rules:

Copy-paste rules copy-paste-rules

You can copy-paste a rule from one field to other similar fields to save time.

To copy-paste rules, do the following:

Nested expressions nestedexpressions

Rule editor lets you use multiple AND and OR operators to create nested rules. You can mix multiple AND and OR operators in rules.

Following is an example of a nested rule that displays a message to the user about eligibility for a child’s custody when the required conditions are met.

You can also drag-and-drop conditions within a rule to edit it. Select and hover over the handle ( ) before a condition. Once the pointer turns into the hand symbol as shown below, drag and drop the condition anywhere within the rule. The rule structure changes.

Date expression conditions dateexpression

Rule editor lets you use date comparisons to create conditions.

Following is an example condition that displays a static text object if the mortgage on the house is already taken, which the user signifies by filling up the date field.

When the date of mortgage of the property as filled in by the user is in the past, the adaptive form displays a note about the income calculation. The following rule compares the date filled in by the user with the current date and if the date filled in by the user is earlier than the current date, the form displays the text message (named Income).

When filled date is earlier than the current date, the form displays the text message (Income) as following:

Number comparison conditions number-comparison-conditions

Rule editor lets you create conditions that compare two numbers.

Following is an example condition that displays a static text object if the number of months an applicant is staying at his current address is less than 36.

When the user signifies that he has been living at his present residential address for less than 36 months, the form displays a notification that additional proof of residence may be requested.

Impact of rule editor on existing scripts impact-of-rule-editor-on-existing-scripts

In AEM Forms versions prior to AEM 6.1 Forms feature pack 1, form authors and developers used to write expressions in the Scripts tab of the Edit component dialog to add dynamic behavior to adaptive forms. The Scripts tab is now replaced by the rule editor.

Any scripts or expressions that you must have written in the Scripts tab are available in the rule editor. While you cannot view or edit them in visual editor, if you are a part of the forms-power-users group you can edit scripts in code editor.

Example rules example

Invoke form data model service invoke

Consider a web service GetInterestRates that takes loan amount, tenure, and applicant’s credit score as input and returns a loan plan including EMI amount and rate of interest. You create a form data model using the web service as a data source. You add data model objects and a get service to the form model. The service appears in the Services tab of the form data model. Then, create an adaptive form that includes fields from data model objects to capture user inputs for loan amount, tenure, and credit score. Add a button that triggers the web service to fetch plan details. The output is populated in appropriate fields.

The following rule shows how you will configure the Invoke service action to accomplish the example scenario.

Invoke form data model service using adaptive form rule

Triggering multiple actions using the When rule triggering-multiple-actions-using-the-when-rule

In a loan application form, you want to capture whether the loan applicant is an existing customer or not. Based on the information user provides, the customer ID field should show or hide. Also, you want to set focus on the customer ID field if the user is an existing customer. The loan application form has the following components:

When you write a When rule on the radio button to implement this behavior, the rule appears as follows in the visual rule editor.

Rule in the visual editor

In the example rule, the statement in the When section is the condition, which when returns True, executes the actions specified in the Then section.

The rule appears as follows in the code editor.

Rule in the code editor

Using a function output in a rule using-a-function-output-in-a-rule

In a purchase order form, you have the following table, in which users will fill in their orders. In this table:

A. Row1 B. Quantity C. Total Quantity

Now, you want to add specified quantities in the Product Quantity column for all products and display the sum in the Total Quantity cell. You can achieve this by writing a Set Value Of rule on the Total Quantity cell as shown below.

Rule in the visual editor

The rule appears as follows in the code editor.

Rule in the code editor

Validating a field value using expression validating-a-field-value-using-expression

In the purchase order form explained in the previous example, you want to restrict user from ordering more than one quantity of any product that is priced more that 10000. To do this, you can write a Validate rule as shown below.

Rule in the visual editor

The rule appears as follows in the code editor.

Rule in the code editor