Form Scripting¶

Emakin forms support scripting for custom behavior and dynamic form interactions. Scripts can execute operations before a form is rendered or respond to changes in the data model. Library functions like $Xml provide essential data operations.

Form Fields and Data Manipulation¶

Form data is accessible through the global variable $Xml. All form data elements can be referenced and manipulated using standard XPath expressions.

To retrieve the value of a specific form field, the $Xml.Evaluate function is used:

1

var fieldValue = $Xml.Evaluate('MyField');

All form data is inherently stored in an XML structure, with field values represented as string types. To work with values as different data types, you can utilize the following dedicated functions for type conversion:

• Xml.EvaluateBoolean: Evaluates the expression and returns a boolean value.
• Xml.EvaluateNumber: Evaluates the expression and returns a numerical value.
• Xml.EvaluateDateTime: Evaluates the expression and returns a Date/DateTime object.

For example, to retrieve a date field's value as a Date object:

1

var date = $Xml.EvaluateDateTime('MyDateField');

To modify the values of form fields, the Xml.SetValue function is employed:

1

$Xml.SetValue('MyField', 'Hello World!');

The SetValue function intelligently handles the data type of the provided value and automatically converts it to the appropriate standard XML format for storage.

1
2

$Xml.SetValue('MyDate', new Date());
var myDate = $Xml.Evaluate('MyDate'); // myDate will contain the date string in ISO 8601 format.

As XML supports the storage of hierarchical data structures, you can create lists of multiple values. This is particularly useful for supporting tabular or grid layouts within forms.

1
2
3

// Appends a new 'MyRow' element under 'MyList' and sets its 'MyField' value.
var row = $Xml.AppendChild('MyList/MyRow');
row.SetValue('MyField', '1');

Please refer to Xml page for further details.

$Form Variable Overview¶

The $Form variable provides access to form properties and functions for managing form elements dynamically.

1
2
3
4
5
6
7
8

$Form = {
    element: $('form'),       // jQuery form element
    refresh() {
        // method to re-build and render form from the scratch
    },
    readonly: boolean,        // Specifies whether the form is in readonly or in edit mode
    sections: {}              // List of form sections
}

Change Form Section States Dynamically¶

Form section states are defined by task properties but can also be updated dynamically through scripting.

1
2
3

if ($Xml.EvaluateBoolean('SomeCondition')) {
    $Form.sections['MySection'] = 'Hidden';     // set MySection to Hidden state.
}

Available Section States:

Attach Change Events¶

Use the $Xml.Bind method to attach a change event to an existing element in the data model.

1
2
3

$Xml.Bind('Person/Name', function () {
    // executed when Person/Name is changed
});

For elements that may not exist at the time of form rendering, use the $Xml.Live method. It attaches event listeners to future elements when they are created.

1
2
3

$Xml.Live('List/Item/Amount', function () {
    // executed when List/Item/Amount is changed
});