Best practices for working with adaptive forms

Use Apache Maven aem-project-archetype to create and manage structure for AEM project. It creates recommended structure and templates for your AEM project. Also, it provides build automation and change control systems to help manage the project.

• Use the maven archetype:generate command to generate the initial structure.
• Use maven eclipse:eclipse command to generate the eclipse project files and import the project into eclipse.

The FileVault tool or VLT helps you map the content of a CRX or AEM instance to your file system. It provides change control management operations, such as check-in and check-out of the AEM project content. See How to use the VLT Tool.

If you use Eclipse-integrated development environment, you can use AEM Developer tools for seamless integration of Eclipse IDE with AEM instances to create AEM applications. For details, see AEM developer tools for Eclipse.

An adaptive form template is a specialized AEM page that defines structure and the header-footer information of an adaptive form. A template has preconfigured layouts, styles, and basic structure for an adaptive form. AEM Forms provides out-of-the-box templates and components that you can use to author adaptive forms. However, you can create custom templates and components as per your requirements. It is recommended to gather requirements for additional templates and components you will need in your adaptive forms. For details, see Customizing adaptive forms and components.

AEM Forms allows you to create adaptive forms based on the following form models. The form models act as interface for data exchange between a form and AEM system and provide an XML-based structure for data flow within and outside an adaptive form. Also, the form models impose rules and constraints on adaptive forms in the form of schema and XFA constraints.

• None: Adaptive forms created with this option don’t use any form model. The data XML generated from such forms has flat structure with fields and corresponding values.
• XML or JSON schema: XML and JSON schemas represent the structure in which data is produced or consumed by the back-end system in your organization. You can associate a schema to an adaptive form and use its elements to add dynamic content to the adaptive form. The elements of the schema are available in the Data Model Object tab of the content browser for authoring adaptive forms. You can drag-drop the schema elements to build the form.
• XFA form template: It is an ideal form model if you have investments in XFA-based HTML5 forms. It provides a direct way to convert your XFA-based forms into adaptive forms. Any existing XFA rules are retained in the associated adaptive forms. The resulting adaptive forms support XFA constructs, such as validations, events, properties, and patterns.
• Form Data Model: It is a preferred form model if you are looking to integrate your backend systems like databases, web services, and AEM user profile to prefill adaptive forms and write submitted form data back into the backend systems. A Form Data Model editor lets you define and configure entities and services in a form data model that you can use to create adaptive forms. For more information, see AEM Forms Data Integration.

AEM Forms provides out-of-the-box adaptive form templates that you can use to create adaptive forms. You can also create your own templates. AEM provides static and editable templates.

• Static templates are defined and configured by developers.
• Editable templates are created by authors using template editor. The template editor lets you define a basic structure and initial content in a template. Any modification in the structure layer is reflected in all forms using that template. The initial content may include pre-configured theme, prefill service, submit action, and so on. However, these settings can be modified for a form using the form editor. For more information, see Adaptive form templates.

For styling a specific field or panel instance, use inline styling. Alternatively, you can define a class in a CSS file and specify the class name in the CSS Class property of the component.

Include a client library in a component to consistently apply styles across adaptive forms or fragments that use that component. For more information, see Create an adaptive form page component.

Apply styles defined in a client library to select adaptive forms by specifying the path to the client library in the CSS file path field in the adaptive form container properties.

To create a client library of your styles, you can configure the custom CSS file in the Theme Editor base clientlib or in the Form Container properties.

Adaptive forms provide panel layouts, such as responsive, tabbed, accordions, and wizard, to control how form components are laid out in a panel. You can create custom panel layouts and make them available for use by form authors. For more information, see Creating custom layout components for adaptive forms.

You can also customize specific adaptive form components like fields and panel layout.

• Use the Overlay functionality of AEM to modify a copy of a component. It is not recommended to modify default components.
• To customize the layout of out-of-the-box adaptive form components in /libs, create custom layout components in addition to the default layouts.
• Introduce custom interactivities by creating custom widgets or appearances. It is not recommended to modify default components. For more information, see Appearance framework.

See Handling personally identifiable information for recommendations on handling PII data.

Use Objects browser in the sidebar to quickly access fields deep down in the form hierarchy. You can use the search box to search for objects in the form or objects tree to navigate from one object to another.

To view and edit the properties of a component in the components browser in the sidebar, select the component and click . You can also double-click a component to view its properties in the properties browser.

Use keyboard shortcuts to take quick actions on your forms. See AEM Forms Keyboard Shortcuts.

Adaptive form components are recommended for use only in adaptive form pages. The components have dependency on their parent hierarchy. Hence, do not use them in an AEM page.

Use meaningful and unique names for form fields and components to avoid any possible conflicts while writing rules.

Use this operator for a component to refer to itself in a rule expression. It ensures that the rule remains valid even if the component name changes. For example, field1.valueCommit script: this.value > 10.

Use component names when referring to other form components. Use the value property to fetch the value of a field or component. For example, field1.value.

Refer components by relative unique hierarchy to avoid any conflict. For example, parentName.fieldName.

When handling complex or commonly-used rules, consider writing business logic as functions in a separate client library that you can specify and reuse across adaptive forms. The client library should be a self-contained library and should not have any external dependencies, except on jQuery and Underscore.js. You can also use the client library to enforce server-side revalidation of submitted form data.

Adaptive forms provide a set of APIs that you can use to communicate with and perform actions on adaptive forms. Some of the key APIs are as follows. For more information, see JavaScript Library API reference for Adaptive Forms.

• guideBridge.reset(): Resets a form.

• guideBridge.submit(): Submits a form.

• guideBridge.setFocus(somExp, focusOption, runCompletionExp): Sets focus to a field.

• guideBridge.validate(errorList, somExpression, focus): Validates a form.

• guideBridge.getDataXML(options): Gets form data as XML.

• guideBridge.resolveNode(somExpression): Gets a form object.

• guideBridge.setProperty(somList, propertyName, valueList): Sets property of a form object.

• In addition, you can use the following field properties:

  • field.value to change value of a field.
  • f ield.enabled to enable/disable a field.
  • field.visible to change visibility of a field.

Adaptive form authors may need to write JavaScript code to build business logic in a form. While JavaScript is powerful and effective, it is likely that it could compromise on security expectations. Therefore, you must ensure that the form author is a trusted persona and there are processes to review and approve the JavaScript code before a form is put into production. Administrator can restrict the access to rule editor access to user groups based on their role or function. See Grant rule editor access to select user groups.

You can use expressions in rules to make adaptive forms dynamic. All the expressions are valid JavaScript expressions and use adaptive forms scripting model APIs. These expressions return values of certain types. For more information about expressions and best practices around them, see Adaptive form expressions.

It is recommended to create adaptive forms using XSD form data model even when converting an XFA to adaptive form, if possible.

Include only those fields and panels in adaptive forms that capture information from the user. Consider keeping static content minimal or use URLs to open them in a separate window.

While every form is designed for a specific purpose, there are some common segments in most forms. For example, personal details, address, employment details, and so on. Create adaptive form fragments for common form elements and sections and use them across forms. You can also save a panel in an existing form as a fragment. Any change in a fragment is reflected in all associated adaptive forms. It promotes collaborative authoring as multiple authors can work simultaneously on different fragments that make up a form.

• Similar to adaptive forms, it is recommended that all fragment-specific styling and custom scripts are defined in the client library using the fragment container dialog. Also, try creating self-sufficient fragments that do not depend on objects outside it.
• Avoid using cross-fragments scripting. If there’s any object outside the fragment that you must refer to, try to make that object a part of the parent form. If the object must still reside in another fragment, refer to it by its name in the script.

Use Save and Resume with auto-save to save the adaptive form periodically and enable users to revisit later to complete the form.

Configure fragments to load lazily. At runtime, fragment marked to load lazily are rendered only when they are required. It significantly reduces the load time for large forms. It is also supported in fragments with repeatable panels. For more information, see Configure lazy loading.

• Do not configure lazy loading on fragments in a responsive grid layout or in the first panel.
• File attachment and Terms and conditions components are not supported in lazily loaded fragments.
• Mark a value in a lazy loaded panel as Use Value Globally if that value is used in some other part the form so that the value is available for use when the containing panel is unloaded.
• Consider writing visibility rules for fragments that should show or hide based on a condition.

AEM Forms provides a prefill service to read data from a pre-defined data XML file and prefill the fields of an adaptive form with the content in the prefill XML file.

The prefill data XML must be compliant with the schema of the form model associated with the adaptive form.

Include afBoundedData and afUnBoundedData sections in the prefill XML to prefill both bound and unbound fields in an adaptive form.

For adaptive forms based on form data model, AEM Forms provides out-of-the-box Form Data Model Prefill Service. The prefill service queries data sources for data model objects in the adaptive form and prefills field values when rendering the form.

You can also use the file, crx, service, or http protocols prefill adaptive forms.

AEM Forms supports custom prefill services that you can plug in as an OSGi service to prefill adaptive forms.

Depending on the form data model an adaptive form is based on, you can configure a template for DoR as follows:

• XFA form template: Use the associated XDP file as the DoR template.
• XSD schema: Use the associated XFA template that uses the same XML schema as used by the adaptive form.
• None: Use auto-generated DoR.

Configure header, footer, images, color, font, and so on right from the Document of Record tab of the adaptive form editor.

Use DoRService to generate the DoR programmatically.

Exclude hidden fields from the DoR.

Use afAcceptLang request parameter to view DoR in another locale.

Use adaptive form fragments for common elements across forms and localize fragments. It ensures that you localize a fragment once and it reflects in all forms where the localized fragment is used.

Any modifications like adding a new component or applying a script in a localized form are not localized automatically. Therefore, you must finalize a form before localizing it to avoid multiple localization cycles.

Use afAcceptLang request parameter to override the browser locale and render the form in the specified locale. For example, the following URL will force to render the form in Japanese locale, irrespective of the locale specified in the browser setting:

https://[*server*]:[*port*]/<*contextPath*>/<*formFolder*>/<*formName*>.html?wcmmode=disabled&afAcceptLang=ja

AEM Forms currently supports localization of adaptive forms content in English (en), Spanish (es), French (fr), Italian (it), German (de), Japanese (ja), Portuguese-Brazilian (pt-BR), Chinese- (zh-CN), Chinese-Taiwan (zh-TW), and Korean (ko-KR) locales. However, you can add support for new locales for adaptive forms at runtime. For more information, see Supporting new locales for adaptive forms localization.