Last update: Wed Dec 06 2023 00:00:00 GMT+0000 (Coordinated Universal Time)
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 common-options
The following are the set global options. These options are available for every field.
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.
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.
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)
The appearance framework calls some functions of the widget which are implemented in the custom widgets. The widget must implement the following functions:
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 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 textedit-text-field
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
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 choicelist-dropdownlist-listbox
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
Note: Applicable only for HTML5 forms.
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 api
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.
NumericEdit: NumericField, DecimalField numericedit-numericfield-decimalfield
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.
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).
DateTimeEdit: (DateField) datetimeedit-datefield
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.