Writing Scripts

Within your JavaScript when referring to forms, pages, Elements and properties the following conventions must be followed:

• Names are case-sensitive.
• The spelling to use for names of forms, pages and Elements is shown in the item's Code Name property, which can be found by displaying the properties for the relevant item in the Properties Pane.
• When referring to properties you will generally need to create a property's name by converting the property label displayed in the Proprieties Pane. The first character must be converted to lower-case and any spaces or hyphens should be removed, with the first character following a space or hyphen being put in upper-case. Ignore the ':' at the end of the property label. For example, a property labelled Max Date: would become maxDate for use in your JavaScript.

  For a full list of properties which can be referenced within your custom JavaScript see: Accessible Properties.

• Elements and their properties are referred to using the following format:

  <form name>.<page name>.<element name>.<property name>

  For Elements omit the .<property name> from the end.

  For example, suppose you have a Checkbox Element called AddressChanged on a page called ContactDetails on your Change_of_Address form. To refer to the Checkbox you would use:

  change_of_Address.contactDetails.addressChanged

  and to refer to its Value property, you would use:

  change_of_Address.contactDetails.addressChanged.value

• Header's and Footers are not part of an individual page, therefore in order to reference Elements placed in the form's Header or Footer, you need to replace the page name with the word controller:

<form name>.controller.<element name>

<form name>.controller.<element name>.<property name>

For a full list of the Element's properties which can be referenced within your custom JavaScript see: Accessible Properties.

Digitise Forms includes a number of pre-coded functions which you can use within your JavaScript to perform various actions without having to write the code to do these yourself. These functions are called intrinsic functions because they are used by Digitise Forms itself but are also made available to developers to use within custom JavaScript. They cover various areas including navigation, saving and restoring the state of a form and database actions.

Many of these functions are available as the predefined actions you can assign to Events but you can also use them directly when writing your own custom JavaScript.

When you assign a predefined action to an Event and then convert the assignment to custom JavaScript, a JavaScript function is added to the form's Script file containing the intrinsic functions required to perform your chosen action. For some of these actions you will need to edit the generated function in order to supply additional information required by the intrinsic functions, for example if you assign 'Move to page' to an Event, you will need to edit the function to specify which page to move to.

The List of Functions topic provides a list of the available intrinsic functions with links to a description of each one. These descriptions will help you to use these functions within your custom JavaScript and, for those not familiar with JavaScript, also explain how to edit the functions, if necessary, when used as predefined actions assigned to an Event.

 

The intrinsic functions are supplied within global objects and when including them within your scripts, you will need to reference them using the format:

<object>.<function name>

For Datasource functions, each Datasource has its own global object named NDLDS<datasource name> and functions within the object are referenced using:

NDLDS<datasource name>.<function name>

For Dataset functions, each Dataset has its own table object and the functions can be referenced using:

NDLDS<datasource name>.<dataset name>.<function name>

Datasource and Dataset names can only include A-Z, a-z, 0-9 or '_' and cannot begin with a number. If you are importing a Datasource where the database or any of its tables don't follow this naming convention, the relevant names will be converted when the Datasource is imported and you will need to use the names as they appear under the Datasources tab in the Project Explorer. Any non-allowed characters will be replaced with an '_' and if the name begins with a number, an '_' will be prefixed to the name, e.g. a database name of 7My D4t4#1 would become _7My_D4t4_1.

When using the Dataset object names to reference the intrinsic functions, due to various factors, the name you need to use may need to change slightly from the Dataset's name, including converting the first character to lower case, if it isn't already, and pluralising the name. For example, if you are calling an intrinsic function to act on a Datasource called My_Datasource with a Dataset called MyDataset, the function call would be: NDLDSMy_Datasource.myDatasets.<function name>.

You can check the global object name you need to use in your custom JavaScript for a Datasource or Dataset in its properties. To display a Datasource's properties in the Properties Pane, select the Datasource under the Datasources tab in the Project Explorer and to display a Dataset's properties, select its parent Datasource in the Project Explorer and then open the Dataset from the Form Design workspace. The global object name will be found in the Code Name property. The names here are case-sensitive and should be used in your JavaScript exactly as they appear here.

If you experience issues running a Script, it is worth checking your Datasource and Dataset names against the names in the Code Name property.

You might also be able to check the required Datasource and Dataset names you need to use by generating a Script function via an Element's Event property and then looking at the code generated in the Script or alternatively, by using the Dev Tools from the Form Design workspace.To use the Dev Tools, with the workspace in design mode, choose Show Dev Tools from the Editor group on the Ribbon's Developer tab. The standard browser Dev Tools will open in a separate window. Choose the Sources tab from the tab bar at the top of the window and then click on the Sources tab in the left-hand pane. Expand the branch top ➝ localdomain ➝ app/ndl and look for a .js file with the relevant Datasource in its name. Click on the file to open its content in the Dev Tools' central pane. Look through the contents of this file to find an example of the Dataset object, e.g. <datasourcename>.<datasetname>= new ... This will show you the names of the Datasource and Dataset global objects.

 

When referring to a Datasource or Dataset itself, and not its global object, the names are written as they appear in the Datasource or Dataset's Name property and Dataset names aren't changed, e.g. when including the Datasource and Dataset names as parameters to a function, such as NDLRuntime.prepareDatasource("MyDatasource","MyDataset");.

 

If a Dataset has a Primary Key with a data type of int and its Identity property set to True or a data type of uniqueidentifier (GUID), Form Studio will automatically assign a value to the Primary Key field. For Primary Key(s) which have other data types, you will need to manually enter a suitable value into the Primary Key field(s), either within your custom JavaScript or via an output mapping from a suitable Element on the form, before you submit the form or update the physical database. When you publish your form, Form Studio will warn you if there are any Datasets which won't automatically have their Primary Keys generated.

Digitise Forms Datasources automatically have their Primary Key set to be a GUID, so this is generally only a potential issue with Imported Datasources. You can check a Primary Key's data type by opening the appropriate Dataset from the Datasources tab in the Project Explorer.

 

The function descriptions include the relevant object name(s) for each function.

Many of the intrinsic functions use one or more parameters to pass information into the function. Some use a standard parameter, called ndlParams, e.g. functionName(ndlParams); others have their own set of parameters. The required parameters are set out in the function descriptions, available from the Function List.

For more information about function parameters see Function Parameters.