Customise Forms with JavaScript

The Event properties allow you to assign actions to pages and Elements, which will be executed when predefined conditions (called 'Events') occur within a form at runtime. For example, Events include a Button being clicked/tapped, the contents of a text box changing and a page being displayed.

All pages and many of the Elements have one or more Event properties, which allows you to add an action from a predefined list or perform whatever actions you want by adding your own JavaScript. The selected action or JavaScript will be executed whenever this Event is triggered at runtime.

Some of the actions require you to provide additional information in order for the action to be performed, e.g. the Move to page action needs you to specify the page to move to, and LoadDatasource needs the Datasource you want to load. For the Datasource actions, the Event property provides extra fields which allow you to provide all the information you need. For the remaining actions, if you need to edit the action you first need to generate a JavaScript function for the Event, which you can then modify to provide the additional information required. Actions which don't require additional information, such as Move to next page, don't need you to generate a JavaScript function.

In addition, for all of the actions, you can also extend the default functionality using JavaScript. If you have generated a JavaScript function for an Event, you can insert additional JavaScript to extend its behaviour. If you haven't generated a JavaScript function for the action, you will need to generate one first and then edit it to add in your custom JavaScript.

As an alternative to selecting a predefined action, you can create a blank function into which you can add your own JavaScript code to perform any actions you like.

Assigning a predefined action or a custom JavaScript function to an Event is done via the Event properties for an Element or page. Once you have assigned an action to an Event, you can also convert the action into a JavaScript function, if you need to edit the action or want to extend the default behaviour, from the Event properties.

When you generate a JavaScript function for an Event action, the function is added to the form's Script file and the file is automatically opened for you to edit the function generated. The function contains the JavaScript required to perform the action, although as mentioned, you may need to edit or add to the provided code to complete the action. Functions generated in this way from an Event are named using the format:

<page name>_<element name>_<event type>_<n>.

This naming convention allows you to recognise functions within the Script file and indicates which Element and Event the function relates to. The first function created for an Event doesn't have the _<n> part of the name. So for example, if you generate a JavaScript function for a button's Clicked Event, you would get a function called something like Page1_ndlbutton1_clicked. If you later decide you want to change the action assigned to this Event and generate a new JavaScript function, the new function would be called Page1_ndlbutton1_clicked_2. The original function is not deleted, so you can still use it if required.

You can see which action or JavaScript function is currently assigned to an Event by displaying the Element's Properties in the Properties Pane and clicking on the (Events) tab. If an action or function is assigned to an Event, the action or function name will be displayed here. If no function or action name is displayed for an Event, the Event will have no effect when the form is run.

If you want to create a new blank function for an Event which has previously had an action or function assigned to it, you can clear the value in the property first, by right clicking on the button and choosing Clear value.

These custom functions all have a parameter called ndlParams, which is passed into the function at runtime, and automatically contains information about the context in which the function has been called, for example it provides information about the Event which triggered the function call and a description of the form. For more details about the contents of ndlParams refer to the topic: Function Parameters.

When users are filling in your form, you might want to check that the information they enter is valid and that they have provided all the information you need. Digitise Forms provides a number of ways to allow you to validate data input including custom validation using JavaScript.

Validation rules are specified on an individual Element basis, allowing you to force users to enter data into important fields or to check that the data entered into an individual field matches the type of data you want.

If you specify validation rules for an Element, validation may be performed when the value within the Element changes, when the Element loses focus, when a user attempts to move to a different page within the form or when they click the form's Submit button.

Each Element you add to your form can be assigned validation rules, if required, or can be left unvalidated, in which case no check will be made at runtime on whether the user completes the corresponding data field in the form or on the type of data entered into the data field.

One way to check the contents of data entered into an Element's data field is to assign a JavaScript function to the Element which will compare the contents of the field against your validation criteria for the data field and if the contents is satisfactory, return the variable isValid set to true.

Adding JavaScript validation to an Element is done via the Elements properties. To find out more, refer to the topic: Validate User Input.

When you create a new JavaScript function within an Element's properties, a skeleton JavaScript function will be created called <page name>_<element name>_validate<property name>. You can edit this function or create one of your own. If you create one of your own, you will need to assign it to the Element's validation rules when you have finished coding it.

You can see what validation rules have been specified for an Element by displaying the Element's Properties in the Properties Pane and clicking on the (Rules) tab. The current validation rules will be displayed here. If no rules are displayed, no validation will take place at runtime for this Element.

Custom error handling allows you to enhance and extend the default error handling available should a problem occur when downloading data from a remote datasource or updating a database with input data from the form. For full details see Display Datasource Error Messages.

Each Element has Visible and Disabled properties, which allow you to specify whether you want the Element to be displayed or hidden and enabled or disabled, respectively, when the page displays.

By default the Element will be displayed and enabled.

The Visible and Disabled properties of an Element allow you to specify a JavaScript expression which determines the visible and enabled status of the Element. These expressions can contain any valid standard JavaScript and can reference other Elements in the form and their properties in the same way as writing custom JavaScript functions. Note, however, that in expressions such as form1.page1.ndlcheckbox1.value=='true', true and false are actually strings here within the property and hence must be in quotes.