Advanced Scripting for JavaScript Developers

This topic provides additional advanced information about customising your forms for JavaScript developers. It is intended to supplement the information found in the topic Writing Scripts.

 

Forms are created as Single Page Applications (SPAs) built with AngularJS v1.8.2.

Forms and pages are implemented as AngularJS directives, which are generated by Form Studio, with a directive for the form and for each page.

Each page has an AngularJS controller defined on its outermost div. This controller contains:

  • Objects for each Element, including a member variable for data which is bound to the Element using the ng-model directive. A data member variable is named after properties that have a ‘dataType’ property in the Element’s configuration.
  • Functions which implement calls to intrinsic functions in the NDLLibrary, data access objects and custom functions defined by the user. They are called from eventhandler functions bound to the AngularJS scope.

The display of each page is controlled by an intrinsic page manager object. The page manager has an interface/api which facilitates navigation through the pages and which is used by some of the intrinsic functions in the NDLLibrary object such as MoveToNextPage, MoveToPreviousPage, and MoveToPage.

Datasources are implemented as global objects with functions calling into an AngularJS http service. They are named by prefixing the Datasource name with NDLDS, e.g. NDLDSMyDatasource or NDLDSSP_dbo_MyDatasource. They include functions for reading, creating and updating records within the Dataset.

You can think of a Datasource as consisting of:

  • A set of table objects, one for each Dataset within the Datasource, which contain an array of records retrieved from the source and/or created by the form.
  • The concept of a ‘current’ record in each table: this is the record which is currently bound to the Elements on the form
  • Functions to:
    • Populate the record array from the defined source (usually a database defined by the Datasource’s connection string).
    • Apply any updates (create or modify) stored in the record array to the defined source.
    • Obtain the table object for a particular Dataset.

 

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.

Remember, 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. Check a Datasource's or Dataset's Code Name property to find the name of its global object and use the names exactly as you find them in these properties.

When referring to a Datasource or Dataset itself, and not its global object, the names are written as they appear in the Name property under the Datasources tab, e.g. when adding Datasource or Dataset names to the standard NDLParams object for use in one of the intrinsic functions or passing Datasource and Dataset names directly into an intrinsic function as string parameters : NDLRuntime.prepareDatasource("MyDatasource","MyDataset");.

If you experience issues when running a Script, always check that you have used the correct Datasource and Dataset names.

 

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), FX 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, FX will warn you if there are any Datasets which won't automatically have their Primary Keys generated.

FX 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.

 

Each Dataset record consists of one or more columns. When referring to these columns in custom JavaScript, you will need to convert the name of the column to a JavaScript compatible format. You can check the column names you need to use within your JavaScript under the Mappings tab when the Dataset is open in the Form Design workspace:

Picture showing an open Dataset.

The SQL Name column shows the name of the column in the SQL database or Stored Procedure Result Set.

The FX Name column shows the SQL Name with any invalid characters replaced with '_'s.

When referencing a column within custom JavaScript, however, you may need to further convert the FX Name for JavaScript compatibility and other factors. The Code Name column shows the name of the column you need to use when referring to the column as part of a Dataset object, e.g. to obtain or set the value of a column in the current record you could use:

<datasourcename>.<datasetname>.current.<columnname>

where Datasource, Dataset and column names are all taken from the respective Code Name properties, e.g.:

NDLDSMy_Datasource.myDatasets.current.myColumn

The name as shown in the Code Name column is case-sensitive and must be used in your custom JavaScript exactly as it appears in that column.

Validations are implemented as AngularJS directives. They are all generated into a single file, ndlvalidations.js, and bind a function to the AngularJS ngModel validations collection.

Form Studio is supplied with a set of standard validations, such as checking that data entered is an email address, postcode or phone number. You can create your own validations to add to the default validations supplied using JavaScript or regular expressions. Each validation should be contained in a separate file and saved to the following folder:

<fx installation folder>\Frameworks\AngularJS18_Bootstrap\Validations

Easy access to the Validations folder is available by clicking the Validations button in the Resources group on the Ribbon's Developer tab, which will load the Windows File Explorer and automatically display the contents of this folder.

Validations added to this folder will appear on the list of predefined validations within the validation properties for an Element.

For details of the required format, refer to the existing files in this folder.

You can also create JavaScript validations within the Script file or regular expression validations within the Element properties - see Validate User Input.

Be aware when referencing an Element's property that is apparently a Boolean that it may actually be a string, and so your JavaScript expression would need to put the value in quotes. The list of accessible properties includes the data type of all the accessible properties.

The NDLRuntime object is a global object defined in ndlruntime.js, a static JavaScript file supplied with the Studio, distributed when a form or project is published and downloaded to the client in the header section of every form. It includes a number of intrinsic functions, mostly simple navigation functions providing access to key objects.

NDLRuntime functions are used throughout the generated code, so you should only amend them if you are really sure you know what you’re doing.

Ndlruntime.js also includes the statement which creates the AngularJS application.

Descriptions of the intrinsic functions contained in the NDLRuntime object can be found from the function list.

The NDLLibrary object is a global object containing a number of intrinsic functions. Each function is stored as a separate file in a folder below your Form Studio installation folder called: Frameworks\AngularJS18_Bootstrap\Prefabs. When you publish your form, the files in this folder are compiled into a file called ndllib.js which is distributed with your form. You can add your own files to this folder and each function will get added to the ndllib.js file and the NDLLibrary object when it is generated. For details of the required format, see existing examples in the folder.

Easy access to the Prefabs folder is available by clicking the Prefabs button in the Resources group on the Ribbon's Developer tab, which will load the Windows File Explorer and automatically display the contents of this folder.

For descriptions of the built-in intrinsic functions contained in the NDLLibrary object see the function list.