Forms (adaptive forms and HTML5 forms) use jQuery, Backbone.js and Underscore.js libraries for appearance and scripting. The forms also use the jQuery UIWidgets architecture for all interactive elements (such as fields and buttons) in the form. This architecture enables Form developer to use a rich set of available jQuery widgets and plug-ins in Forms. You can also implement form-specific logic while capturing data from users like leadDigits/trailDigits restrictions or implementing picture clauses. Form developers can create and use custom apperances 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. It provides insight into the appearance framework and enables developers to create an alternate appearance for a form field.

The appearance framework relies on various options, events (triggers), and functions to capture user interactions with the form, and responds to model changes to inform the end-user. In addition:

The framework provides a set of options for the appearance of a field. These options are key-value pairs and divided into two categories: common options and field type specific options.

The appearance, as a part of the contract, triggers a set of events such as enter and exit.

The appearance is required to implement a set of functions. Some of the functions are common while others are specific to field type functions.

Common options

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

Property

Description

name

An identifier 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.

displayValue

This value of the field is displayed.

screenReaderText

Screen Readers use this value to narrate information about the field. The 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

The height of the widget. It is specified in pixels.

width

The width of the widget. It 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

The direction of the text. The possible values are ltr (left-to-right) and rtl (right-to-left).

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

Interaction with forms framework

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

Events triggered by widget

Event

Description

XFA_ENTER_EVENT

This event is triggered whenever the field 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 field. 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 field 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 implemented by widget

The appearance framework calls some functions of the widget which are implemented in the custom widgets. The widget must implement the following functions:

API

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

Deletes an option from the list.

clearItems: function()

Clears all the options from the list.

NumericEdit: NumericField, DecimalField

Options

Description

dataType

String representing the data type of the field (integer/decimal).

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.

Two for adaptive forms (On, Off) and three for HTML5 forms (On, Off, Neutral).

state

Current state of the element.

Two for adaptive forms (On, Off) and three for HTML5 forms (On, Off, Neutral).