Best Practices

We recommend the following best practices when working with scripts in your forms.

• Ensure you do not use keywords for variables.

  • Do not use control and currentValue for creating variables.

• Ensure you use a string for the Value property of the Boolean, Date, Time, and DateTime controls.

  • Enable, Visible, Read-Only, and Mandatory properties hold their value as true or false. However, the Value property for the Boolean control has a string value, which can be either "True" or "False".

  • Value property for the Date, Time, and DateTime should be given in the specific string format. Refer the scripting section on these controls for more details.

• Ensure you refer to the same control.

  • Refer to the same control when scripting for the Enable, Visible, Read-Only, Value, or Validate property of a control.

  • Use the currentValue method in the script to refer to the value of the property of a control that is scripted.

  • Do not validate the Value property of a control that is set as invisible.

• Ensure the script returns a value.

  • The script must return a value even when the entire script is commented except when scripting for the On Data Change, On Form Load, On Click, and so on events.

  • Most of the scripts present in the Scripts Tab of which the common ones are Name, Description, Enable, Visible, Read-Only, Mandatory, Validate, and Default Value, require a return value.

  • Refer the scripts documentation for the control to know which ones require a return value and accordingly have the scripts written.

• Ensure the script returns the required value.

  • The script should return a Boolean value for the Enable, Visible, Read-Only, or Mandatory property of a control.

  • The default value of the property for a control is returned when the script does not have a return statement.

  • The previous value for the Enable, Visible, Read-Only, or Mandatory property of a control is retained when the script does not have a return statement or the return value is invalid.

• Ensure invalid values are not set through the scripts.

  • The invalid values are cleared on submission of a form, and other rules such as validation, minimum value, and maximum value are not triggered when an invalid value is set through the scripts for the Value property of a Number, Date, or Time control.

• Ensure commented code is handled in the script.

  • The script should not contain only commented code as in such cases the code is executed.

  • The script should not contain unnecessary comments, and the code that is no longer required should be removed.

• Scripts like Name, Description, Enable, Visible, etc. in the Scripts tab, except for the On Form Load script, create dependency injections based on the Script written. Hence, we recommend to write code that would perform the required checks and return a value. Also, these scripts should not set values to other controls or properties..

• Ensure the rules are triggered.

  • Validation rules for a Number, Date, or Time control are not triggered at form load when scripting for the Value property of the control.

• Ensure the Equality Operator (==) is used instead of the Identity Operator (===) when type conversion is not required.

  • The Equality Operator (==) is used for an abstract comparison and converts the operands to the same type before making the comparison, whereas the Identity Operator (===) is used for a strict comparison and is true only if the operands are of the same type.

    Example

    If the Number (N1) control is set to 123.00, then the following comparison is false as the Number (N1) control returns 123.

    if(control.findById("N1").value === "123.00")

    {

    alert("True");

    }

    else

    {

    alert("False");

    }

    The comparison will be true when the operator or operand is changed as follows:

    if(control.findById("N1").value == "123")

    OR
    

    if(control.findById("N1").value === 123.00)

    Note: If the Number (N1) control is set to 123.45, then the Number (N1) control returns 123.45, and you can continue to compare as follows:
    
    if(control.findById("N1").value === "123.45")
    
    as the decimal value other than 0 is not discarded.

• Ensure you create a variable outside the AJAX call and assign that variable inside the success function. Then return the variable after the AJAX call, when you code a synchronous AJAX call which returns a result, as shown in below example.

  var returnData;

  $.ajax({

  type: …,

  async: false,

  url: …,

  contentType: …,

  dataType: …,

  data: …,

  success: function(result)

  {

  returnData = result;//true or false

  },

  error: …

  });

  return returnData;

• Ensure you check the syntax of the script before you save the script.

• In case of scripts that return value, when you use control.findByXmlNode, control.findById, and/or control.findByName APIs to refer to the properties like Enable, Visible, Value, etc., the dependency would be created on these properties. So if any value change occurs to the dependent properties, the script would re-trigger.

• Ensure you write the scripts for functions as shown below:
  

  Assign function to Variable:

  var count = function(value) {

  return value.length;

  };

  IIFE functions:

  function () {

  //write your js code here

  });

  Global functions:

  window.calculateLength = function(value) {

  return value.length;

  };

• Avoid writing huge scripts in the scripts editor in Forms. The script editor has an auto save functionality, which would save the scripts without having the script been completely verified on the syntax. This is due to the fact that the scripts are not lost in case of a system crash. But there is a negative effect for this functionality as well. After the system crash (let's assume), when you open the form and preview, it might not show the preview and give exceptions. So you would need to update the scripts where you had left off before the system crash, and make appropriate corrections. Hence, it is better to avoid large scripts written in the script editor. Instead, use custom js files to write down the huge scripts and have a call to those custom script functions from the Form scripts.

• The On Data Change script for a control would not execute when value is set in the On Form Load script. This is done to prevent inadvertent triggering of On Data Change event when instance xml is set while invoking the form.

  Example:

  A Form is having only 1 Textinput control. The On Form Load script is defined as below:

  console.log("********************************************************Textinput1 value set from On Form Load");

  control.findByXmlNode("Textinput1").value = "Value set from On Form Load";

  And have the On Data Change script for the Textinput control as below:

  console.log("********************************************************Textinput1 - On Data Change script - value: " + currentValue);

  When you preview the form, it would not execute the On Data Change script of the Textinput control, as you have set the value of the TextInput control in the On Form Load script. Below is the console log result:

  ********************************************************Textinput1 value set from On Form Load

• Property based scripts takes precedence – Name, Description, Enable, Visible, Mandatory, Value, Default Value type of scripts

  • Example with On Form Load script and Textinput Value script:

    A Form is having only 1 Textinput control. The On Form Load script is defined as below:

    console.log("********************************************************Textinput1 value set from On Form Load");

    control.findByXmlNode("Textinput1").value = "Value set from On Form Load";

    And have the Value script for the Textinput control as below:

    console.log("********************************************************Textinput1 value set via Value script");

    return "Value set from Textinput control's Value script";

    When you preview the form, it would execute the On Form Load event of the Textinput control, but as you have the Value script defined for the TextInput control, the Value script would take precedence. Below is the console log result:

    ********************************************************Textinput1 value set from On Form Load

    ********************************************************Textinput1 value set via Value script

    ********************************************************Textinput1 value set via Value script

    ********************************************************Textinput1 value set via Value script

    Note: The last 2 logs related to Value script execution happens due to internal handling of scenario around value script for Validation and On Form Load completion events.

  • Example with Button On Click script and Textinput Enable script:

    A Form is having only 1 Textinput control. In the Textinput control properties, set Enable property as No and define the Enable script as below:

    console.log("********************************************************Textinput Enable property set to True via Textinput Enable script");

    return true;

    Let us add a button control and give the On Click script as below:

    console.log("********************************************************Textinput Enable property set to False via button click");

    control.findByXmlNode("Textinput1").enable = false;

    When you preview the form, it shows the Textinput control in enabled state, as the Enable script takes precedence.

    When you click on the button, you would see that the Textinput control is still in the enabled state, as the Enable script takes precedence. Below is the console log result:

    ********************************************************Textinput Enable property set to True via Textinput Enable script

    ********************************************************Textinput Enable property set to False via button click

    ********************************************************Textinput Enable property set to True via Textinput Enable script

• The control's value set last via a script would have it's On Data Change script executed last.

  Example:

  A Form having controls - 2 Dateinput, 1 Textinput, and 1 Button.

  The Dateinput1 control has the On Data Change script as below:

  console.log("********************************************************Dateinput1 On Data Change script - Update Textinput1 with value");

  control.findByXmlNode("Textinput1").value = currentValue;

  The Dateinput2 control has the On Data Change script as below:

  console.log("********************************************************Dateinput2 On Data Change script - Update Textinput1 with value");

  control.findByXmlNode("Textinput1").value = currentValue;

  The button control has the On Click script as below:

  console.log("********************************************************Set Dateinput1 value as 03/20/2022");

  control.findByXmlNode("Dateinput1").value = "03/20/2022 00:00:00";

  console.log("********************************************************Set Dateinput2 value as 03/30/2022");

  control.findByXmlNode("Dateinput2").value = "03/30/2022 00:00:00";

  When you preview the form, it would show the Textinput control’s value as the Dateinput2 control’s value, as the button On Click script sets the Dateinput2 control’s value at the end. Below is the console log result:

  ********************************************************Set Dateinput1 value as 03/20/2022

  ********************************************************Dateinput1 On Data Change script - Update Textinput1 with value

  ********************************************************Set Dateinput2 value as 03/30/2022

  ********************************************************Dateinput2 On Data Change script - Update Textinput1 with value

  If you change the order in which the Dateinput control values are set via the button On Click script, you will have to change the button On Click script as below:

  console.log("********************************************************Set Dateinput2 value as 03/30/2022");

  control.findByXmlNode("Dateinput2").value = "03/30/2022 00:00:00";

  console.log("********************************************************Set Dateinput1 value as 03/20/2022");

  control.findByXmlNode("Dateinput1").value = "03/20/2022 00:00:00";

  When you preview the form, it would show the Textinput control’s value as the Dateinput1 control’s value, as the button On Click script sets the Dateinput1 control’s value at the end. Below is the console log result:

  ********************************************************Set Dateinput2 value as 03/30/2022

  ********************************************************Dateinput2 On Data Change script - Update Textinput1 with value

  ********************************************************Set Dateinput1 value as 03/20/2022

  ********************************************************Dateinput1 On Data Change script - Update Textinput1 with value

• Referring to properties of the same control or other control in scripts like Name, Description, Enable, Visible, Read-Only, Mandatory, Default Value, Value, and Validate, would create the dependencies on those properties. If any change happens to those dependent control properties, the scripts would get executed.

  Example:

  Consider a Textinput control’s Scripts Tab containing scripts for Name, Description, Enable, Visible, Read-Only, Mandatory, Default Value, Value, and Validate. These scripts are also based on the control’s respective property except in the case of Validate script, like Enable script of Textinput control would relate to the Enable property of the Textinput control.

  So, when you define these kind of scripts, which require return values, then those return values are targeted to the respective property’s value. When writing scripts, you would refer to other controls and their properties in the scripts, which create dependencies for these kinds of scripts. For example, consider a BooleanInput control and a Textinput control in the Form. The Textinput control’s Enable script is given as below:

  if (control.findByXmlNode("Booleaninput1").value == "True")

  {

  return true;

  }

  else

  {

  return false;

  }

  When you preview the form, the Textinput control is disabled, as the BooleanInput control is set to No. If you change the BooleanInput control to Yes, then the Textinput control is enabled. This is how dependency gets created for BooleanInput control’s Value property when used in the Textinput control’s Enable script.

  Note: You should not set any other control properties or value in these scripts, only reading the values can be done. For example, you cannot set the Read-Only property’s value for the same control or other control, in the control’s enable script. This is to avoid unwanted behavior and/or recursive loops in the form.

• When all the property based scripts like Name, Description, Enable, Visible, etc. are given for a control, the properties are defined for the control initially. Once the On Form Load script completes execution, these scripts would get executed.

  Example:

  Lets define a form with a Textinput control. Have the On Form Load script as below:

  console.log("********************************************************On Form Load script executed");

  Have the Textinput control’s Name script as below:

  console.log("********************************************************Textinput1 Name script");

  return currentValue;

  Similarly, have the Textinput control’s Description script as below:

  console.log("********************************************************Textinput1 Description script");

  return currentValue;

  Similarly, define the scripts for Enable, Visible, Read-Only, Mandatory, Default Value, and Value in the Scripts tab for the Textinput control.

  When you preview the form, the console log result is as below:

  ********************************************************On Form Load script executed

  ********************************************************Textinput1 Mandatory script

  ********************************************************Textinput1 Name script

  ********************************************************Textinput1 Description script

  ********************************************************Textinput1 Visible script

  ********************************************************Textinput1 Read-Only script

  ********************************************************Textinput1 Enable script

  ********************************************************Textinput1 Value script

  The order of these scripts execution is not important, they might get triggered again based on the dependencies they have. The important point is that we should never set any other control’s value in these scripts. We can only refer or read other control’s property values or the same control’s property values in these scripts, which would create the dependencies and accordingly the execution of the scripts would happen based on the dependencies, as and when these dependent values are changed.