某些 Creative Cloud 应用程序、服务和功能在中国不可用。
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.
| 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.
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.
| 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) |
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) |
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. |
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.
| 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. |
| 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. |
| Function | Description |
|---|---|
addItem: function(itemValues) |
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. |
| 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. |
| 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, |
| states | Number of states allowed. 3, if neutral is allowed, else 2. |
| state | Current state of the element (0: On, 1: Off, 2: neutral). |
| 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. |
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);
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" |