Form Change Handler

Form Change Handler

Overview

The form change handler can be used when the fields in the form dialog box should dynamically change values based on the user input. It can be also used to validate the user input and display an error message in case the input doesn't match with the criteria set by the menu creator.

How to enable the form change handler?

Set the value of the triggerOnChange attribute in the field object as true.

Implementation of the form change Handler

The information will be passed through the following parameters to the form change handler.
 
form
Input collected from the user
user
Details of the user executing the menu.
entity
Details of the entity in which the menu is being used.
target
Details of the form field in which the value has been changed.
network
Details of the network in which the menu being.
Table 1 (Parameters of form change handler)

Whenever the user input is made in the field, the form change handler will be executed. Using the form change handler you can add new fields to a form, update or remove the existing ones depending on the user input. The attributes in this handler response are as follows:
 
Attribute
Property
Description
fields
Type: JSONArray
Maximum limit:  20
Array of field objects that you want to add or update in the form
remove
Type: JSONArray
Maximum limit:  20
Array of field names that you want to remove from the form.
error
String (50)
The error message that has to displayed for the entire form.
fieldError
JSONObject
Error message for an individual field.  
(Refer to Table 2 in this document to add error message for each field.)
Table 2 (Attributes in handler response) 

Within the JSONObject of the fieldError, you can include the error message for each field using the attribute given below:
 
Attribute
Property
Description
fieldName
 
(the name of the field in which you'd like to display the error message should be used as attribute. eg: startDate)
String (200)
The error message to be displayed  for each field.
 
In general, new fields are inserted at the bottom of the form. However, by using the attributes: after and before, new fields can be inserted in the middle of the form ( before or after a particular field). You can use these attributes within the field object in the form change handler. 
 
Attribute
Property
Description
Pre-requisite
after
String (20)
Enter the name of the field that has to be inserted/moved next to the particular field
Optional
before
String (20)
Enter the name of the field that has to inserted before/moved up before the particular field
Optional

The form change handler will not be executed in the following cases:
  1. The field object's triggerOnChange value is true, but the function is not written the form change handler. 
  2. Or, the function is written in the form change handler, but the field object's triggerOnChange value is false.
 
A sample code to add 'Assignee' field after 'Project' field in a form is as follows: 
  1. "fields": [
        {
          "before": "taskDueDate",
          "hint": "Select the projects",
          "name": "Project",
          "options": [
            {
              "label": "UI Enhancements",
              "id": "13429993739813",
              "value": "13429993739813"
            }
          ],
          "label": "Project",
          "type": "multiSelect",
          "mandatory": "false"
        },
        {
          "hint": " Select assignees",
          "name": "Assignee",
          "options": [],
          "label": "Assignee",
          "after": "Project", // To add the field after 'Project' field.
          "type": "select",
          "mandatory": "false"
        },
        {
          "hide": "false",
          "name": "taskTitle"
        },
        {
          "hide": "false",
          "name": "taskDesc"
        },
        {
          "hide": "false",
          "name": "taskDueDate"
        }
]
}

Sample code to display an error message for an individual field: 
  1. {
    "fieldError":{
    "endDate":"The end date must be greater than the start date."
}
    }
Sample code to display error message for the entire form: 
  1. {
    "fields":[
    {
    "name":"dLang",
    "value":""
    }
    ],
    "error":"Sorry, we're unable to translate the text to the selected language."

}