Introduction to Widgets

In the browser, Mobile Forms render XFA templates in HTML5 format. Mobile Forms uses jQuery, Backbone.js and Underscore.js libraries for appearance and scripting. The forms also use the jQuery UI Widgets architecture for all interactive elements (such as fields and buttons) in the form. All the widget elements inside the XFA field elements have an associated jQuery widget. This architecture enables Form developer to use a rich set of available jQuery widgets and plug-ins in Forms. You can also implement XFA-specific logic while capturing data from users like leadDigits/trailDigits restrictions or implementing picture clauses. Form developers can create and use custom widgets to improve the data capture experience and make it more user-friendly.

This article is for developers with sufficient knowledge of jQuery and jQuery widgets. 

To plug-in a widget to Mobile Forms, fulfill following pre-conditions: 

  • Mobile Forms provide a set of options for all the widgets of a field. These options are key-value pairs and divided into two categories: common options and field type-specific options.
  • The widget, as a part of the contract, triggers a set of XFA Events such as enter and exit,.
  • The widget is required to implement a set of functions; some of the functions are common and some are field type-specific functions.

Common options

The following are the set global options. These options are available for every field. 

Property  Description
name Specifies an identifier that is used to specify this object or event in script expressions. For example, this property specifies the name of the host application.
value Actual value of the field. In XFA terminology value property is the rawValue of the field.
displayValue This value of the field is displayed. In XFA terminology the displayValue property is the formattedValue of the field.
screenReaderText Screen Readers use this value to narrate information about the field. The XFA form provides the value and you can override the value.
tabIndex The position of the field in the tab sequence of the form. Override the tabIndex only if you want to change the default tab order of the form.
role Role of the element, for example, Heading or Table.
height height of the widget. The height is specified in pixels. 
width width of the widget. The height is specified in pixels.
access Controls used to access the contents of a container object, such as a subform.
paraStyles the para property of an XFA element to the widget
dir direction of the text. The possible values are ltr(left-to-right) and rtl (right-to-left).

Apart from these options, the Mobile Forms provide some other options which vary depending on the type of field. The details for the fields-specific options are listed below.

Interaction with Mobile Forms

To interact with Mobile Forms, a widget triggers some events to enable the form script to work. If the widget does not throw these events, then some of the scripts written in the form for that field does not work.

Events to trigger

Event  Description
XFA_ENTER_EVENT
This event is triggered whenever the widget is in focus. It allows the “enter” script to run on the field. The syntax for triggering the event is
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_ENTER_EVENT)

XFA_EXIT_EVENT
This event is triggered whenever the user leaves the widget. It allows the engine to set the value of the field and run its “exit” script. The syntax for triggering the event is
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_EXIT_EVENT)

XFA_CHANGE_EVENT
This event is triggered to allow the engine to run the “change” script written on the field. The syntax for triggering the event is
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CHANGE_EVENT)

XFA_CLICK_EVENT
This event is triggered whenever the widget is clicked. it allows the engine to run the “click” script written on the field. The syntax for triggering the event is
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CLICK_EVENT)

APIs to Implement

Mobile Forms call some functions of the widget which are implemented in the custom widgets. The widget must implement  the following functions:

Function Description
focus: function() puts focus on the widget.
click: function() puts focus on the widget and calls XFA_CLICK_EVENT.

markError:function(errorMessage, errorType)

erorrMessage: string representing the error
errorType: string (“warning”/”error”)

This function sends error message and error type to the widget. The widget displays the error.
clearError: function() If the errors in the field have been fixed, this function is called. It is the responsibility of the widget to hide the error.

Options specific to type of field

All custom widgets should conform to the above specifications. To use the features of different fields, the widget has to conform to the guidelines for that particular field.

TextEdit: Text Field

Option Description
multiline True if the field supports entering a newline character, else false.
maxChars Maximum number of characters that can be entered in the field.
limitLengthToVisibleArea Specifies behavior of text field when the width of text exceeds the width of the widget.

ChoiceList: DropDownList, ListBox

Option Description
value
Array of selected values.
items
Array of objects to be displayed as options. Each object contains two properties -
save: value to save, display: value to display.

editable
If value is true, custom text entry is enabled in the widget.
displayValue
Array of values to display.
multiselect
True if multiple selections are allowed, else false.

API

Function Description

addItem: function(itemValues)
itemValues: object containing the display and save value
{sDisplayVal: <displayValue>, sSaveVal: <save Value>}

Add a item to the list.
deleteItem: function(nIndex)
nIndex: index of the item to remove from the list


Delete an option from the list.
clearItems: function() Clear all the options from the list.

NumericEdit: NumericField, DecimalField

Options Description
dataType String representing the data type of the field (integer/decimal/field).
leadDigits Maximum leading digits allowed in the decimal number.
fracDigits Maximum fraction digits allowed in the decimal number.
zero String representation of zero in locale of the field.
decimal String representation of decimal in locale of the field.

CheckButton: RadioButton, CheckBox

Options Description
values

Array of values(on/off/neutral).

It is array of values for the different states of the checkButton. values[0] is the value when the state is ON, values[1] is the value when the state is OFF,
values[2] is the value when the state is NEUTRAL. Length of the values array is equal to the value of state option.

states Number of states allowed. 3, if neutral is allowed, else 2.
state Current state of the element (0: On, 1: Off, 2: neutral).

DateTimeEdit: (DateField)

Option Description
days Localized name of days for that field.
months Localized month names for that field.
zero The localized text for the number 0.
clearText The localized text for clear button.

Registering custom widget with XFA Scripting Engine

When the custom widget code is ready, register the widget with the scripting engine by using registerConfig API for Form Bridge. It takes widgetConfigObject as input.

 

window.formBridge.registerConfig("widgetConfig" , widgetConfigObject);

widgetConfigObject

The widget configuration is provided as a JSON object (a collection of key value pairs) where the key identifies the fields and value represents the widget to use with those fields. A sample configuration looks like:

{

“identifier1” : “customwidgetname”,
“identifier2” : “customwidgetname2”,
..
}

where “identifier” is a jQuery CSS selector that  represents a particular field, a set of fields of a particular type, or all fields. The following lists the value of the identifier in different cases:

Type of identifier Identifier  Description
Particular field with name fieldname Identifier:"div.fieldname" All fields with the name ‘fieldname’ are rendered using the widget.
All fields of type ‘type’(where type is NumericField, DateField, and so on.): Identifier: "div.type" For Timefield and DateTimeField, the type is textfield as these fields are not supported.
All fields Identifier:  "div.field"