Adobe Experience Manager (AEM) forms can help you transform complex transactions into simple, delightful digital experiences. However, it requires concerted effort to implement, build, execute, and maintain an efficient and productive AEM Forms ecosystem.
This document provides guidelines and recommendations that forms administrator, authors, and developers can benefit from when working with AEM Forms, especially adaptive forms component. It discusses best practices right from setting up a forms development project to configuring, customizing, authoring, and optimizing AEM Forms. These best practices collectively contribute to the overall performance of AEM Forms ecosystem.
In addition, here are some recommended reads for general AEM best practices:
A simplified and standardized project structure can significantly reduce development and maintenance efforts. Apache Maven is an open source tool recommended for building AEM projects.
- Use Apache Maven multimodule-content-package-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. For more information, see How to Build AEM Projects using Apache Maven.
- 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 and create AEM applications. For details, see AEM developer tools for Eclipse.
Once you have your AEM project set up, define strategy for authoring and customizing adaptive forms templates and components.
- 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 data models. The data 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 data 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 data model. The data XML generated from such forms has flat structure with fields and corresponding values.
- XSD or XML schema: XML schema represents the structure in which data is produced or consumed by the back-end system in an organization. It decouples form design from data and binds a field with its value using XPATH. You can associate an XML schema to an adaptive form and use its elements to add dynamic content to the adaptive form. The data XML generated contains data as per the XPATH defined in the XML schema. It is the recommended form data model for creating adaptive forms. For more information, see Creating adaptive forms using XML Schema.
- XFA form template: It is an ideal form data 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.
It is important to carefully choose the data model that not only suits your requirements but extends your existing investments in XFA and XSD assets, if any. It is recommended to use XSD Model to create form templates because the generated XML contains data as per XPATH defined by schema. Using XSD Model as a default choice for Form Data Model also helps because it decouples form design from back end system that processes and consumes data and it improves the performance of form because of one to one mapping of form field. Also, BindRef of the field can be made the XPATH of its data value in XML.
- There are some sections that are common across forms. You should identify such sections and define a strategy to promote content reuse. Adaptive forms allow you to create stand-alone fragments and reuse them across forms. You can also save a panel in an adaptive form as a fragment. Any change in a fragment is reflected in all associated forms. It helps you reduce the authoring time and ensures consistency across forms. In addition, the use of fragments makes adaptive forms light-weight resulting in improved authoring experience, especially of large forms. For more information, see Adaptive form fragments.
- AEM Forms installation provides some in-built adaptive form templates that you can use to create adaptive forms. Depending on your requirements, you can create custom templates from scratch or using the default templates as base. To change the header-footer or style of an AEM Page containing an adaptive form, it is recommended to create a new template or modify an existing one to create an adaptive form. For more information, see Creating a custom adaptive form template.
- AEM client libraries define the appearance and styling of an adaptive form. You can create themes and apply on adaptive form templates to give your forms consistent styling and branding. It uses Less variables to extend CSS capabilities and allows you to customize adaptive forms. For details, see Creating custom adaptive form themes.
- Create reusable styles that can be applied across forms. It is recommended to use Themes to define styling for form components and panels. Themes can be applied on different forms for consistent styling.
- If a theme does not fulfill your styling requirement, you can use predefined classes such as guideFieldNode, guideFieldLabel, guideFieldWidget, and guidePanelNode to apply common style across forms.
- 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.
- 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 the keyboard shortcuts to take quick actions on your forms.
AEM Forms provides a rule editor that allows you to create rules to add dynamic behavior to adaptive form components. Using these rules, you can evaluate conditions and trigger actions on components, such as show or hide fields, calculate values, change drop-down list dynamically, and so on.
Rule editor provides a visual editor and a code editor for writing rules. Consider the following when writing rules using the code editor mode:
- 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 will ensure 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.
- 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.
- field.enabled to enable/disable a field.
- field.visible to change visibility of a field.
Form authors and end users typically face performance issues when loading large forms in authoring mode or at runtime. As number of objects (fields and panels) in form increases, the authoring and runtime experience starts degrading. It also prevents multiple authors to collaborate and author a form simultaneously.
Consider the following best practices to overcome performance issues with large forms:
- 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. You can also embed a fragment in 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.
Also, 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
- 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. For more information, see Configure lazy loading.
AEM Chrome Plug-in is a browser extension for Google Chrome that provides tools for debugging adaptive forms. Form authors and developers can use these tools to:
- Identify bottlenecks and optimize performance of form rendering
- Debug keywords and bindRef errors in the form
- Enable and configure logs
- Debug rules and scripts in the form
- Explore and learn about guideBridge APIs
For more information, see AEM Chrome Plug-in - Adaptive Form.
A document of record (DoR) is a flattened PDF version of an adaptive form that you can print, sign, or archive. 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.
In addition, you can auto-generate DoR for an XSD-based form. The auto-generated DoR is basically an XDP template based on the adaptive form structure. The advantage of using auto-generated DoR is that any modifications in the form reflect in the DoR. You can also download and modify the auto-generated DoR in Forms Designer and associate the modified XDP template as DoR with the form. Also, you can optionally associate a metatemplate to control the header, footer, and structure of the auto-generated DoR.
- None: Use auto-generated DoR.
Server-side validations are required to prevent any attempts to bypass validations on the client and any possible compromise of data submissions and business rules violations. Server-side validations are executed on server by loading the required client library.
- Include functions in a client library for validating expressions in adaptive forms and specify the client library in the adaptive forms container dialog. For more information, see Server-side revalidation.
- Server-side validation validates the form model. It is recommended to create a separate client library for validations and not mix it with other things like HTML styling and DOM manipulation in the same client library.
AEM provides translation workflows that you can use to localize adaptive forms. For information, see Using AEM translation workflow to localize adaptive forms.
Some best practices when localizing adaptive forms are as follows:
- 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:
- 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-tn), 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.
You can configure an additional instance of AEM Forms server that resides behind the firewall in a secured zone. You can use this instance for:
- Batch processing: jobs that are recurring or scheduled in batches with heavy load. For example, printing statements, generating correspondences, and using document services like PDF Generator, Output, and Assembler.
- Storing PII data: Save PII data on the processing server. It is not required if you are already using custom storage provider for storing PII data.
You often need to move your AEM projects from one environment to another. Some of the key things to remember when moving are as follows:
- Take backup of your existing client libraries, custom code, and configurations.
- Deploy product packages and patches manually and in the specified order in the new environment.
- Deploy project-specific code packages and bundles manually and as a separate package or bundle on the new AEM server.
- (AEM Forms on JEE only) Deploy LCAs and DSCs manually on Forms Workflow server.
- Use Export-Import functionality to move assets to the new environment. You can also configure the replication agent and publish the assets.
Some best practices to configure AEM to improve the overall performance are as follows:
- Cache all client libraries at /etc/clientlibs/fd/ and any additional custom client libraries on AEM dispatcher to increase the responsiveness and security of your published forms. For more information, see Dispatcher.
- It is not recommended to cache adaptive forms. Therefore, do not cache /content/forms/af/ and /content/dam/formsanddocuments/* paths.
- Enable HTML via web server compression module. For more information, see Performance tuning of AEM Forms server.
- Configure adaptive forms caching as per your requirements. See Caching adaptive forms.
- Increase calls per request configuration for large forms. See Optimizing performance of large and complex forms.
- Create custom error pages shown by error handler.
- Secure AEM Forms server.
- Use nosamplecontent run mode to ensure there are no sample content and sample users deployed on the production server. See Running AEM in Production Ready Mode.
- Keep the heap size to a minimum of 8 GB. For other settings, see Performance tuning of AEM Forms server.
- Use service user sessions instead of admin sessions for executing service-level tasks. For more information, see Service authentication.
In a production environment, it is recommended not to store submitted form data in AEM repository. The default implementation of Forms Portal Store, Store Content, and Store PDF submit actions store form data in AEM repository. These submit actions are meant only for demonstration purposes. Also, the Save and Resume and Auto Save features use portal storage by default. Therefore, consider the following recommendations:
- Storing draft data: If you are using the Draft feature of adaptive forms, you should implement a custom Service Provide Interface (SPI) to store draft data in more secure storage like database. For more information, see Sample for integrating drafts & submissions component with database.
- Storing submission data: If you are using Form Portal Submit Store, you should implement a custom SPI to store submission data in a database. See Sample for integrating drafts & submissions component with database for a sample integration.
You can also write a custom submit action that stores form data and attachment in secure storage. See Writing custom Submit action for adaptive forms for more information.
One of the key challenges for organizations is how to handle personally identifiable (PII) data. Some best practices that will help you handle such data are as follows:
- Use a secure, external storage like database to store data from draft and submitted forms. See Configuring external storage for drafts and submitted forms data.
- Use Terms and Conditions form component to take explicit consent from user before enabling auto save. In this case, enable auto save only when user agrees to the conditions in Terms and Conditions component.