Apply conditional logic to forms

You can apply conditional logic to a form to control when individual fields become visible or hidden, read-only or editable, mandatory or optional, and change other settings.

For example, you could use conditional logic to control whether Billing address fields are displayed in an order form or whether evidence must be attached to an expense claim form. You can also use conditional logic to control whether a field is mandatory or hidden based on values that are mapped into fields each time the form is opened.

Tip:

If you are familiar with conditional logic in activities you should find that conditional logic in forms works in a similar way.

Logic options

To add conditional logic to a form, open the Designer tab and on the toolbar click Switch to logic.

You can apply conditional logic when the form is first opened and/or each time a change is made to the form:

• Select the On start tab to apply the logic when the form is opened. This is useful when you want to control the behavior of fields based on values that were populated automatically using mappings. Note that the logic is only applied once; if a user changes a mapped value, this will not cause the logic to be reapplied.
• Select the On change tab to apply the logic each time a user updates a field on the form. This is useful when you want to control the behavior of fields based on user inputs. For example, if you want to control the visibility of billing address fields based on a checkbox, the visibility should update each time a user selects or clears the checkbox.

Add items from the toolbar to configure the form logic:

1. You can either use an If then else statement on its own, or nest one or more If then else statements within an On field change condition.
   • Use an If then else statement on its own to use conditions to specify when actions should be performed. For example, you might want to show a Billing address field and make it mandatory based on the value entered in another field.
   • Use On field change to evaluate the If statement each time the user makes a change to one or more specific fields. This is useful if you only want the If conditions to be evaluated when a particular field has been edited, or if you want to nest an If then else within another If then else. In the latter case, you can use the On field change statement to identify the fields from the If statement conditions so that if any of those fields are modified, the conditions are re-evaluated. Note that if you add multiple fields to an On field change rule, the logic is applied if any of the fields change.
2. Add conditions to the If statement to define when the actions should be performed. You can use conditions to compare the value in a field to the value in another field, or to a value specified using an inline template. For example, you might use a condition to check if a date entered in a form field is later than the current date (using the date. template function) or the same as the date currently stored in a case attribute (using the case. template function).
   Note that if you add multiple conditions, all conditions must be satisfied. To require only one of several conditions to be satisfied, add the conditions to a Condition list and switch the list toggle to Or. For more information, see Operators and conditions.
3. Add the action(s) to be performed if the conditions are satisfied to the Then statement. For example, you might want to make a field mandatory and display a message to explain why the field is required. For a full list of actions, see below.
4. Add any action(s) to be performed if the conditions are not satisfied to the Else statement. This might be the opposite of the actions in the Then statement (such as making a field optional) or a different action.
   If you do not want to perform any actions when the conditions are not satisfied, do not add an Else statement.

For example, to control whether the Billing address fields are displayed in an order form, you could add a bare checkbox field labelled Is the billing address different from the delivery address?. You would then disable and hide the Billing address fields by default (or hide the group containing those fields) as part of the form design. Then, you would add an If then block with a condition that checks the value of the checkbox field. Finally, you would need to add an action to show the Billing address field (and make it mandatory) when the condition is satisfied.

Tip:

You can apply conditional logic to forms that have been divided into multiple tabs or steps. As tabs allow the user to complete the form in any order, we recommend restricting any logic to operate within a single tab. If you are using steps, you can use conditional logic in an earlier step to make changes to later steps.

Form field actions

The following actions are available to change the behavior of form fields. Actions should be added to either Then or Else statements. Once you have configured the action, select the form field(s) that you want to apply the action to. You can apply multiple actions to the same field.

• Enable/Disable - Make the field editable or read-only.
• Show/Hide - Make the field visible or hide it.
• Show group/Hide group - Make the group of fields visible but not editable, or hide the group.
• Mandatory/Optional - Make the field mandatory or optional. If a field is mandatory, the user cannot submit the form (or proceed to the next step) unless they have entered a valid value.
• Require any - Make at least one of the selected fields mandatory. All selected fields are mandatory to begin with. Once a value is provided for one of the fields, the remaining fields become optional.
• Require none - Make all the selected fields optional.
• Message - Display text below the form field. This is useful if you want to display help text, such as explaining why a field has become mandatory.
• Set empty/Set value - Remove the current value from the field or populate the field with the specified value.
• Set label - Change the label of the selected field. For example, you can use this to make the label more context-specific based on other data that has been entered.
• Switch picklist - Change the picklist associated with the field.

A number of combination actions are also provided for convenience.

Tip:

When setting a value, label, or message, you can enter static text and/or use template functions to define the value dynamically. For example, to enter the date five days after the current date, use the date. template part with Add days or Add business days. For more information about using inline templates, see Templates.

Scripted actions

In some situations you may want to perform more complex actions than can be achieved with the form field actions described above. For example, you may want to reformat phone numbers, remove spaces from postal codes, or validate data against an external source. You can achieve this by writing some custom JavaScript and applying it to the form using either a scripted action or a form action plugin.

• Scripted action: This option allows you to add JavaScript directly to the form designer. This is useful when you do not need to reuse the code in multiple places and you don't want to share the code on Grexx Marketplace.
• Form action plugin: This option allows you to create a reusable JavaScript component that you can share on Grexx Marketplace. You can create a new plugin from the Plugins page in your Studio.

To add a custom JavaScript action to form logic:

1. From the form logic designer, select the relevant Then or Else block.
2. From the toolbar, either select Scripted or select an existing form action plugin from the picklist.
3. If you have added a scripted action, select it to open the properties pane and then add the JavaScript to the Code block field. To expand the properties pane, click the "full screen" icon.

Both scripted actions and form action plugins allow you to reference form fields and groups. For details of supported methods, refer to the Grexx Platform JavaScript Library documentation available at https://your-site-url/docs/api/js/modules.html. For more information and examples of how to use JavaScript for form actions, see the Form action plugin reference.