DocumentationAEM 6.5User Guide

Appearance framework for adaptive and HTML5 forms appearance-framework-for-adaptive-and-html-forms

Last update: Mon Jun 24 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

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 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 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 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 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:

Function
Description
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

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

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

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

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

Function
Description
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

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 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).

DateTimeEdit: (DateField) 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.
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2