Script can be entered against any of an element’s events, but the Message and Valid properties can only be set in the OnValidate event. To place script against an event, select the element, then the script button. The Script Template window will open with the element name selected in the top left, and the possible events underneath Then select which event you would like to place the script in, this will highlight it in blue. You can change the element selected by hovering over the element path separated by ‘/’ to enter additional script against any other element or events.
The most common use of scripting is to ensure that valid entries have been made. You can perform this by selecting the element, then selecting the OnValidate event. You test the value for the element and if this is incorrect, you set the element’s Valid property to false and display an appropriate error message.
The term ‘this’ refers to the selected element, so the line “this.valid = false” is setting the Page1.Section1.Name text box element’s Valid property to false. This will prevent the form from submitting and cause the value in the element’s Message property to be displayed. In this instance, the message property has been set to “Please enter your name”.
It is possible to check the values from multiple elements in script. To achieve this, place the validation code in the OnValidate event of one of the elements and refer to the other elements either by their full names, or by their Aliases. Aliases are unique names supplied when the elements are named in the Form Designer. Obviously employing aliases entails less typing. You use the “and” keyword to combine the fields of the query.
You can check if most of the elements have been left empty by testing whether they have a value of an empty string (“”). The elements that can be tested this way include:
●Text elements (including text, number, email, phone etc).
●Paragraph text
●Date
●Time
●Single-select
●Photo
●Sketch
●Signature
To confirm if a checkbox has been selected, you use the true and false keywords. As demonstrated in this example.
To confirm if a selection has been made from a multiple selection element, you can use the count(), countSelected() and getOption() functions. Count() returns the number of items in a multi-select element, countSelected() returns the number of items selected and getOption().value will return true or false, depending on whether the option specified within the brackets has been selected. For example, this.getOption("Option 1").value would return true if “Option 1” had been selected.
When a device user attempts to submit a form, and the script for a required element sets the element’s Valid property to false, a message will appear on the Form Submission window informing the user that there is an error in their input. They will be prevented from submitting the form. Multiple elements can have their Valid properties controlled in this way, and an individual line of text will appear on the device for each element that has its Message property set to a value.
You can set the Message property for an element without setting its Valid property to false. In this way you can warn a user that their input may be incorrect, without preventing them from submitting the form. When the Message property is set in this way, it is indicated on the device by an amber circle containing an exclamation mark.
The OnValidate event is used to test data when the device user submits a form. But you may wish to change the value or condition of an element prior to this point – for example when the user enters data in a text box, or selects a value from a drop down list. In this case, you could use the OnValueChange event.
When a user makes a change, such as selecting a value from a single selection element, it is possible to change the values of another element’s properties. For example, if the user selected ‘House’ from a single selection element, you could disable other elements that relate to flats. In this example, if the “Other” option in a salutation single selection element is selected, the element’s OnValueChange event is used to enable a text element (TitleIfOther), to permit the user to enter an alternative title.
The OnValidate event of the TitleIfOther element then ensures that if “Other” has been selected, text has been entered.
A more complex example could be to check the values from a list of names, and use them to populate an email address field. The script in the following example will populate the hidden field, “SendTo” with a value depending on the selection from a single selection element. If “Other” is selected, then the “OtherEmailAddress” field is enabled, so it can be used instead. It is also possible to directly acquire the device user’s email address, using the getCurrentUserEmail() function, which returns a string value of the logged in user’s email address.
Formworks supports rudimentary Intellisense in version 2. Currently this works using either the “this” keyword, or element alias names. To use Intellisense, you need to use the fully qualified element name or Alias, enter a full-stop, then select the Ctrl and Space keys simultaneously. A drop down list of available properties will appear.