Add a script to a form

A script adds automatic behaviour to a form while it is being filled in: for example, it fills in some fields when the form opens, such as the office details, or updates a field when the person filling in changes another one.

The script is written in JavaScript, in the form itself, with the simple or the advanced editor. Writing it requires technical knowledge of the language.

Open the script

• In the simple editor, click the Configuration icon (a gear) and open the Script tab. The tab also lists the ids of the form’s fields.
• In the advanced editor, select the Form item, the first in the Tree tab, and open the Input section of the properties panel: the script is written in the Event Map field.

Write the functions

1. To run code when the form opens, write an onInit function.
2. To react to a field event, write a function named after the field’s id followed by On and the event name: text_1OnChange runs when the value of the text_1 field changes.
3. Functions with any other name are helper functions: they are called from the others with this. before the name, for example this.calculate().

A field’s id can be seen and changed:

• in the simple editor, with the Field identity action (the gear next to the field), in the Widget Id field;
• in the advanced editor, in the component’s Unique ID property.

Each id differs from those of all the other fields in the form. In the simple editor it contains only letters, numbers and underscores, and does not start with a number.

This script, taken from the Course attendance register, passes the project and office of the item the form was opened from to the header:

function onInit(event) {
    const context = this.runtime.context || {};
    const header = this.getWidget('form-header');
    if (header) {
        header.project_id = context.project_id;
        header.office_id = context.office_id;
    }
}

What a script can use

In the code	What it holds
this.root	the form
this.getWidget(id)	the field or component with that id
this.runtime.context	the item the form was opened from: entity_id, entity_type, project_id, project_country, office_id, office_country, unit_id, unit_country
this.runtime.target	the launch point the form was opened from
this.functionName()	a helper function written in the script

A form opened from the file system does not start from an item, so the context may be incomplete. If a function contains an error, the form still opens and the error appears in the browser console.