Create custom appearances in HTML5 forms

Last update: June 24, 2024

CREATED FOR:

  • Admin
  • User
  • Developer

You can plug in custom widgets to a Mobile Forms. You can extend existing jQuery Widgets or develop your own custom widgets using appearances framework. XFA engine uses various widgets, see Appearance framework for adaptive and HTML5 forms for detailed information.

An example of default and custom widget

An example of default and custom widget

Integrating custom widgets with HTML5 forms

Create a profile 

You can create a profile or choose an existing profile to add a custom widget. For more information on creating profiles, see Creating custom Profile.

Create a widget

HTML5 forms provide an implementation of the widget framework that can be extended to create new widgets. The implementation is a jQuery widget abstractWidget that can be extended to write a new widget. The new widget can be made functional only by extending/overriding the below mentioned functions.

Function/ClassDescription
renderThe render function returns the jQuery object for the default HTML element of the widget. The default HTML element should be of focusable type. For example, <a>, <input>, and <li>. The returned element is used as $userControl. If the $userControl specifies the above constraint, then functions of the AbstractWidget class work as expected, otherwise some of the common APIs (focus, click) require changes.
getEventMapReturns a map to convert HTML events to XFA events.
{
blur: XFA_EXIT_EVENT,
}
This example shows that the blur is an HTML event and XFA_EXIT_EVENT is corresponding XFA event.
getOptionsMapReturns a map which provides detail what action to perform on change of an option. The keys are the options that are provided to the widget and values are the functions that are called whenever a change in that option is detected. The widget provides handlers for all the common options (except value and displayValue)
getCommitValueThe Widget framework loads the function whenever the value of the widget is saved in the XFAModel (for example, on exit event of a textField). The implementation should return the value that is saved in the widget. The handler is provided with the new value for the option.
showValueBy default, in XFA on enter event, the rawValue of the field is displayed. This function is called to show the rawValue to the user.
showDisplayValueBy default, in XFA on exit event, the formattedValue of the field is displayed. This function is called to show the formattedValue to the user.

To create your own widget, in the profile created above, include references of the JavaScript file which contains overridden functions and newly added functions. For example, the sliderNumericFieldWidget is a widget for numeric Fields. To use the widget in your profile in the header section, include the following line:

window.formBridge.registerConfig("widgetConfig" , widgetConfigObject);

Register custom widget with XFA Scripting Engine 

When the custom widget code is ready, register the widget with the scripting engine by using registerConfigAPI for Form Bridge. It takes widgetConfigObject as input.


window.formBridge.registerConfig("widgetConfig",
        {
        ".<field-identifier>":"<name-of-the-widget>"
        }
    );

widgetConfigObject

The widget configuration is provided as a JSON object (a collection of key value pairs) where the key identifies the fields and value represents the widget to use with those fields. A sample configuration looks like:

*{*

*"identifier1" : "customwidgetname",
"identifier2" : "customwidgetname2",
..
}*

where “identifier” is a jQuery CSS selector that represents a particular field, a set of fields of a particular type, or all fields. The following lists the value of the identifier in different cases:

Type of identifierIdentifierDescription
Particular field with name fieldnameIdentifier:“div.fieldname”All fields with the name ‘fieldname’ are rendered using the widget.
All fields of type ‘type’(where type is NumericField, DateField, and so on.):Identifier: “div.type”For Timefield and DateTimeField, the type is textfield as these fields are not supported.
All fieldsIdentifier: “div.field”

Experience Manager


Espressos & Experience Manager: AEM Forms

Espressos & Experience Manager

Thursday, Mar 6, 7:00 PM UTC

Join Adobe's AEM product team as they highlight AEM Forms' latest innovations, including: the new Gen AI Assistant, Unified Composition with AEM Sites, and new ways to deploy forms through conversations.

Register

Connect with Experience League at Summit!

Get front-row access to top sessions, hands-on activities, and networking—wherever you are!

Learn more

Register now