Skip to content

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:

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 normally defined by task properties. A section is a form area identified by the SectionName attribute on a content or container widget. Scripts can update the same section state map when the state needs to be decided from form data or script logic.

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

If a script changes a section state after the form has already been rendered, refresh or rebuild the form so widgets read the new section defaults.

Available Section States:

State Description
Default Uses the normal form and widget behavior
Enabled Enabled unless the form is read-only or rules override it
Disabled Shows the section as read-only
Hidden Hides the section

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
});