Function Parameters
When using the intrinsic functions, you may need to pass information to the function. For example, when using the Move to page function, you need to tell the function which page you want to move to. Information is passed to a function in the standard way using parameters.
If you are not familiar with JavaScript or other programming languages, click here for more information about parameters
Parameters are included in the call to the function between the brackets which come after the function name, e.g. in the function call:
NDLLibrary.moveToPage(ndlParams, pageName);
ndlParams and pageName are parameters and in this case will provide, amongst other things, the name of the page to move to.
Parameters are used to pass different types of information to a function, with each parameter passing a particular piece of information or data, e.g. the pageName parameter in the example above will always hold the name of a page within your form. Since the page name could differ each time the function is called, using a parameter to pass in the page name allows the same function to be used over and over again without having to rewrite it for each page. Individual functions are, therefore, written with a specific set of parameters depending upon the information they need. Some functions do not require additional information and may have no parameters. In the description of the functions provided in Digitise Forms for use in your Digitise Forms Scripts, the parameters are given names to represent them in the description, such as ndlParams and pageName in the example above. When you use the function in a script, you replace the parameter names found in the description with the required information, e.g."Page1", or with a variable which contains the information the parameter needs. A 'variable' is a programming term for a storage item used to hold a piece of information or data within a script where the value can vary or won't be known until runtime. Each variable in a script is given a name, which is used to refer to it within the code and so you can substitute the parameter name in a function call with the name of a variable which will hold the relevant information for the parameter at runtime.
If you add an action to an Element's Event property and then convert that into a JavaScript function, a JavaScript function will be generated by Form Studio and added into the form's Script file. This JavaScript function will perform the same actions as the Event action but can be modified if required. As mentioned above, for example, if you want to display a specific page in your form you will need to tell the function which page you want to move to.
When you generate one of these custom functions from an Element's Event properties, the function will include one or more parameters allowing you to pass information into the function, such as the name of the page to move to. These functions always include a special parameter called ndlParams.
If you are not familiar with JavaScript and are just editing a JavaScript function as part of assigning a predefined function to an Event, you don't need to worry about the contents of ndlParams - Digitise Forms will deal with it for you. The intrinsic function descriptions will explain what changes, if any, you need to make to the function call to provide the information you need. Check which functions are used in the generated JavaScript within the Script Editor and then refer to the descriptions of these functions in the Function List for details of how to edit the functions. Each description has a Using as Predefined Action in Event section which will tell you what you need to change.
For developers, the default version of the ndlParams parameter consists of a JavaScript object, also called ndlParams, which contains the following four properties, the values of which are automatically set by Digitise Forms before passing the object to the function:
|
Property |
Contents |
|---|---|
| event | a jQuery event indicating the event which triggered the script |
| form | a global object containing the definition of the current form |
| hash | the section of the URL used to call the current form starting with #!/ |
| scope | AngularJS scope object |
If you are editing the Script file and adding in your own code, you can manually include calls to any of the intrinsic functions provided with Digitise Forms, as listed in the Function List or shown in the code samples within the function descriptions. Choose a function from the list to display a description of how to use it, including any parameters required. You will see from the descriptions that some functions include an ndlParams parameter, some add properties to an ndlParams object and the rest have their own individual parameters specific to their behaviour or don't take any parameters at all.
When you manually add a function call which uses an ndlParams parameter, this parameter will be an empty object and won't automatically be populated with the properties listed above. If you want to use any of the properties listed above, or the functions requires you to add properties to the ndlParams object, you will need to create a version of the object and add the properties to it within your script. You don't have to call it ndlParams, you can name it something more meaningful within the context of your script, if you prefer. For examples refer to the code samples supplied in the function descriptions, in particular under loadDatasource and updateDatasource.