Appearance framework for adaptive and HTML5 forms

CAUTION

AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

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.

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:

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

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

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

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

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

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

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.

Business.Adobe.com resources

Docs links
Automated Onboarding Customer Communications Asset Collections Dynamic Forms Headless Cms Content Management System

On this page