Asynchronous submission of adaptive forms

Last update: June 24, 2024

Applies to:
Experience Manager 6.5

Topics:
Adaptive Forms,Foundation Components

CREATED FOR:

User
Developer

Adobe recommends using the modern and extensible data capture Core Components for creating new Adaptive Forms or adding Adaptive Forms to AEM Sites pages. These components represent a significant advancement in Adaptive Forms creation, ensuring impressive user experiences. This article describes older approach to author Adaptive Forms using foundation components.

Version	Article link
AEM as a Cloud Service	Click here
AEM 6.5	This article

Traditionally, web forms are configured to submit synchronously. In synchronous submission, when users submit a form, they are redirected to an acknowledgement page, a thank you page, or if there is submission failure, an error page. However, modern web experiences like single page applications are gaining popularity where the web page remains static while client-server interaction happens in the background. You can now provide this experience with adaptive forms by configuring asynchronous submission.

In asynchronous submission, when a user submits a form the form developer plugs-in a separate experience like redirecting to other form or a separate section of the website. The author can also plug-in separate services like sending data to a different data store or adds a custom analytics engine. If there is asynchronous submission, an adaptive form behaves like a single page application as the form does not reload or its URL does not change when the submitted form data is validated on the server.

Read on for details about asynchronous submission in adaptive forms.

Configure asynchronous submission

To configure asynchronous submission for an adaptive form:

In adaptive form authoring mode, select the Form Container object and select to open its properties.
In the Submission properties section, enable Use asynchronous submission.
In the On Submit section, select one of the following options to perform on successful form submission.
- Redirect to URL: Redirects to the specified URL or page on form submission. You can specify a URL or browse to choose the path to a page in the Redirect URL/Path field.
- Show Message: Displays a message on form submission. You can write a message in the text field below the Show Message option. The text field support rich text formatting.
Select to save the properties.

How asynchronous submission works

AEM Forms provides out-of-the-box success and error handlers for form submissions. Handlers are client-side functions that execute based on the server response. When a form is submitted, the data is transmitted to the server for validation, which returns a response to the client with information about the success or error event for the submission. The information is passed as parameters to the relevant handler to execute the function.

In addition, form authors and developers can write rules at form level to override default handlers. For more information, see Override default handlers using rules.

Let us first review the server response for success and error events.

Server response for submission success event

The structure for the server response for submission success event is as follows:

{
  contentType : "<xmlschema or jsonschema>",
  data : "<dataXML or dataJson>" ,
  thankYouOption : <page/message>,
  thankYouContent : "<thank you page url/thank you message>"
}

The server response if there is a successful form submission includes:

Form data format type: XML or JSON
Form data in XML or JSON format
Selected option to redirect to a page or display a message as configured in the form
Page URL or message content as configured in the form

The success handler reads the server response and accordingly redirects to the configured page URL or displays a message.

Server response for submission error event

The structure for the server response for submission error event is as follows:

{
   errorCausedBy : "<CAPTCHA_VALIDATION or SERVER_SIDE_VALIDATION>",

   errors : [
               { "somExpression" : "<SOM Expression>",
                 "errorMessage"  : "<Error Message>"
               },
               ...
             ]
 }

The server response if there is an error in form submission includes:

Reason for the error, failed CAPTCHA or server-side validation
List of error objects, which includes the SOM expression of the field that failed validation and the corresponding error message

The errors handler reads the server response and accordingly displays the error message on the form.

Override default handlers using rules

Form developers and authors can write rules, at form level, in code editor to override default handlers. The server response for success and error events is exposed at form level, which developers can access using $event.data in rules.

Perform the following steps to write rules in code editor to handle success and error events.

Open the adaptive form in authoring mode, select any form object, and select to open the rule editor.
Select Form in the Form Objects tree and select Create.
Select Code Editor from the mode selection drop-down.
In the code editor, select Edit Code. Select Edit on the confirmation dialog.
Choose Successful Submission or Error in Submission from the Event drop-down.
Write a rule for the selected event and select Done to save the rule.

recommendation-more-help