Appearance framework for adaptive and HTML5 forms

Last update: June 24, 2024

CREATED FOR:

  • User
  • Developer

Forms (adaptive forms and HTML5 forms) use 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. 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.

PropertyDescription
nameAn identifier used to specify this object or event in script expressions. For example, this property specifies the name of the host application.
valueActual value of the field.
displayValueThis value of the field is displayed.
screenReaderTextScreen Readers use this value to narrate information about the field. The form provides the value and you can override the value.
tabIndexThe 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.
roleRole of the element, for example, Heading or Table.
heightThe height of the widget. It is specified in pixels.
widthThe width of the widget. It is specified in pixels.
accessControls used to access the contents of a container object, such as a subform.
paraStylesThe para property of an XFA element to the widget.
dirThe 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

EventDescription
XFA_ENTER_EVENTThis 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_EVENTThis 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_EVENTThis 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_EVENTThis 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:

FunctionDescription
focus: function()Puts focus on the field.
click: function()Puts focus on the field and calls XFA_CLICK_EVENT.

markError:function(errorMessage, errorType)

erorrMessage: string representing the error
errorType: string ("warning"/"error")

Note: Applicable only for HTML5 forms.

Sends error message and error type to the widget. The widget displays the error.

clearError: function()

Note: Applicable only for HTML5 forms.

Called if the errors in the field are fixed. The widget hides 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

OptionDescription
multilineTrue if the field supports entering a newline character, else false.
maxCharsMaximum number of characters that can be entered in the field.

limitLengthToVisibleArea

Note: Applicable only for HTML5 forms

Specifies behavior of text field when the width of text exceeds the width of the widget.

ChoiceList: DropDownList, ListBox

OptionDescription
valueArray of selected values.
itemsArray of objects to be displayed as options. Each object contains two properties -
save: value to save, display: value to display.

editable

Note: Applicable only for HTML5 forms.

If value is true, custom text entry is enabled in the widget.
displayValueArray of values to display.
multiselectTrue if multiple selections are allowed, else false.

API

FunctionDescription
addItem: function(itemValues)
itemValues: object containing the display and save value
{sDisplayVal: <displayValue>, sSaveVal: <save Value>}		Adds a item to the list.
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.