Adaptive form fragments adaptive-form-fragments

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

Adobe recommends using the modern and extensible data capture Core Componentsfor creating new Adaptive Formsor 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.

While every form is designed for a specific purpose, there are some common segments in most forms, such as to provide personal details like name and address, family details, income details, and so on. Form developers are required to create these common segments every time a new form is created.

Adaptive forms provide a convenient mechanism to create form segment like a panel or a group of fields only once and reuse them across adaptive forms. These reusable and standalone segments are called Adaptive Form Fragments.

NOTE
You can easily customize your fragment experience for users with the Configure dialog and Design dialog of Form Fragment component.

Create a fragment create-a-fragment

You can create an Adaptive Form Fragment from scratch or save a panel in an existing adaptive form as fragment.

Create fragment from scratch create-fragment-from-scratch

  1. Log into AEM Forms author instance at https://[hostname]:[port]/aem/forms.html.

  2. Click Create > Adaptive Form Fragment.

  3. Specify title, name, description, and tags for the fragment.

    note note
    NOTE
    Ensure that you specify a unique name for the fragment. If there already exists another fragment with the same name, the fragment fails to create.
  4. Click to open the Form Model tab, and from the Select From drop-down menu, select one of the following models for the fragment:

    • None: Specifies to create the fragment from scratch without using any form model.

      note note
      NOTE
      In Adaptive Forms based on core components, you can use a single form fragment multiple times in a form. It supports both none-based and schema-based form fragments.
    • Form Template: Specifies to create the fragment using an XDP template uploaded to AEM Forms. Select the appropriate XDP template as the form model for the fragment.

    Creating an adaptive form using form template as model

    The sub forms marked as fragments in the selected form template are also displayed. You can select a sub form for adaptive form fragment from the drop-down list.

    Select subforms from the specified form template

    In addition, you can create an adaptive form fragment using sub forms that are not marked as fragments in the form template by specifying the SOM expression for the sub form in the drop-down box.

    • XML Schema: Specifies to create the fragment using an XML schema uploaded to AEM Forms. You can upload or select from the available XML schemas as the form model for the fragment.

    Create an adaptive form fragment based on an XML schema as model

    You can also create an adaptive form fragment by selecting a complexType present in the selected schema from the drop-down box.

    Select a complex type from the specified XML schema model

  5. Click Create and then click Open to open the fragment, with a default template, in edit mode.

In edit mode, you can drag-and-drop any adaptive form component from the AEM sidekick onto the fragment. For information about adaptive form components, see Introduction to authoring adaptive forms.

In addition, if you selected an XML schema or XDP form template as the form model for your fragment, a new tab displaying the form-model hierarchy appears in the content finder. It lets you drag-and-drop form-model elements onto the fragment. The added form-model elements get converted into form components while retaining the original properties from the associated XDP or XSD.

Save panel as a fragment save-panel-as-a-fragment

  1. Open an adaptive form that contains the panel you want to save as adaptive form fragment.

  2. In the panel toolbar, click Save as Fragment. The Save As Fragment dialog opens.

    note note
    NOTE
    If the panel you are saving as fragment contains child panel, the resulting fragment will include them.
  3. In the Fragment Creation dialog, specify the following information:

    • Name: Name of the fragment. The default value is the element name of the panel. It is a mandatory field.

      note note
      NOTE
      Ensure that you specify a unique name for the fragment. If there already exists another fragment with the same name, the fragment fails to create.
    • Title: Title of the fragment. The default value is the title of the panel.

    • Description: Description of the fragment.

    • Tags: Tags metadata for the fragment.

    • Target Path: Repository path where the fragment will be saved. If you do not specify a path, a node with the same name as that of the fragment gets created next to the node containing the adaptive form. The fragment is saved in this node.

    • Form Model: Depending on the form model for the adaptive form, this field displays the XML Schema, Form Template, or None. It is a non-editable field.

    • Fragment Model Root: Appears only in XSD-based adaptive forms. It specifies the root for the fragment model. You can choose / or the XSD complex type from the drop-down. Note that you can reuse the fragment in another adaptive form only if you select the complex type as the fragment model root.
      If you choose / as the fragment model root, the complete XSD tree from the root is visible in the adaptive form data model tab. For a complex type fragment model root, only the descendants of the selected complex type are visible in the adaptive form data model tab. If you create a fragment and choose a complex type as the Fragment Model Root, you can use it wherever that complex type is used, either within the same form or across multiple forms.

    • XSD Ref: Appears only in XSD-based adaptive forms. It displays the location of the XML schema.

    • XDP Ref: Appears only in XDP-based adaptive forms. It displays the location of the XDP form template.

    save-fragment

    Save As Fragment dialog

  4. Click OK.

    The panel is saved at the specified or the default location in the repository. In the adaptive form, the panel is replaced by a snapshot of the fragment. As shown below, the General Information panel and its child panels, Personal Information and Address, are saved as a fragment.

    To edit the fragment, click Edit Asset in the panel toolbar. The fragment opens in a new tab or window in edit mode.

    Editing fragment

Working with fragments working-with-fragments

Configure fragment appearance configure-fragment-appearance

Any fragment you insert in adaptive forms appears as a placeholder image. The placeholder displays titles of up to a maximum of ten child panels in the fragment. You can configure AEM Forms to show the complete fragment instead of the placeholder image.

Perform the following steps to show complete fragments in forms:

  1. Go to AEM web console configuration page at https:[host]:[port]/system/console/configMgr.

  2. Search and click Adaptive Form and Interactive Communication Web Channel Configuration to open it in edit mode.

  3. Disable Enable Placeholder in place of Fragment checkbox to show complete fragments rather than the placeholder image.

Insert a fragment in an adaptive form insert-a-fragment-in-an-adaptive-form

The adaptive form fragments you create appear in the Adaptive Form Fragments tab of the AEM content finder. To insert an adaptive form fragment in an adaptive form:

  1. Open the adaptive form, in edit mode, in which you want to insert an adaptive form fragment.

  2. Click Assets assets-browser in the sidebar. In the assets browser, select Adaptive Form Fragments from the drop-down.

    You can also choose to display all adaptive form fragments or filter based on their form model - Form Template, XML Schema, or Basic.

  3. Drag-and-drop an adaptive form fragment onto the adaptive form.

    note note
    NOTE
    The adaptive form fragment is not enabled for authoring from within the adaptive form. Moreover, you cannot use an XSD-based fragment in a JSON-based adaptive form and the opposite way.

The adaptive form fragment is inserted by reference in the adaptive form and is synchronized with the standalone adaptive form fragment. It means when you update the adaptive form fragment, the changes reflect in all adaptive forms where the fragment is used.

Embed a fragment in adaptive form embed-a-fragment-in-adaptive-form

You can choose to embed an adaptive form fragment in an adaptive form by clicking Embed Asset: <fragmentName> button on the panel toolbar of the added fragment, as shown in the following example image.

Embed a form fragment in adaptive form

NOTE
The embedded fragment is no longer linked with the standalone fragment. You can edit the components in the embedded fragment from within the adaptive form.

Using fragments within fragments using-fragments-within-fragments

You can create nested adaptive form fragments, which means you can drag-drop a fragment in another fragment, and can have nested fragment structure.

Change fragments change-fragments

You can replace or change an adaptive form fragment by another fragment by using the Select Fragment asset property in the Edit component dialog for an adaptive form fragment panel.

Generate Document of Record for Adaptive Form fragment generate-DOR-for-fragments

Document of Record (DOR) helps you to keep information of your forms in the print or document format. Thereby, it help you to track information about your customers at any time later, and you can also use the Document of Record to archive forms and content together in PDF Format. Learn to generate document of record for Adaptive Form fragments.

Using a form fragment multiple times in an Adaptive Form using-form-fragment-mutiple-times-in-af

You can use a schema-based form fragment multiple times in an Adaptive Form to save data uniquely for each form fragment fields. For example, you can use an address form fragment to collect address details for permanent, communication, and present living addresses in a loan application form.

using multiple fragment in adaptive form

NOTE
  • If you use none-based form fragments multiple times in an Adaptive form, data syncing between the fields of fragments occurs. The data syncing issue does not occur in core component-based form fragments, where you can use a fragment either schema-based or none-based multiple times in a form.

Auto mapping of fragments for data binding auto-mapping-of-fragments-for-data-binding

When you create an adaptive form fragment using an XFA form template or XSD complex type and drag-drop the fragment to an adaptive form, the XFA fragment or the XSD complex type is automatically replaced by the corresponding adaptive form fragment whose fragment model root is mapped to the XFA fragment or XSD complex Type.

You can change the fragment asset and its bindings from the Edit component dialog.

NOTE
You can also drag-drop a bound adaptive form fragment from Adaptive Form Fragment library in AEM content finder and provide the correct bind reference from the Edit component dialog of the adaptive form fragment panel.

Manage fragments manage-fragments

You can perform several operations on adaptive form fragments using the AEM Forms UI.

  1. Go to https://[hostname]:'port'/aem/forms.html.

  2. Click Select in the AEM Forms UI toolbar and select an adaptive form fragment. The toolbar displays the following operations you can perform on the selected adaptive form fragment.

Operation
Description
Open
Opens the selected adaptive form fragment in edit mode.
View Properties
Opens the Properties panel. From the Properties panel, you can view and edit properties, generate a preview, and upload a thumbnail image for the selected fragment. For more information, see Managing metadata.
Copy
Copies the selected fragment. The Paste button appears in the toolbar.
Download
Downloads the selected fragment.
Preview
Provides options to preview the fragment as an HTML or a custom preview by merging data from an XML file with the fragment. For more information, see Previewing a form.
Start Review/Manage Review
Allows initiating and managing a review of the selected fragment. For more information, see Creating and managing reviews.
Create Dictionary
Generates a dictionary for localizing the selected fragment. For more information, see Localizing adaptive forms.
Publish / Unpublish
Publishes / unpublishes the selected fragment.
Delete
Deletes the selected fragment.

Localizing adaptive form containing fragments localizing-adaptive-form-containing-fragments

To localize an adaptive form that contains adaptive form fragments, you need to localize the fragment and the form separately. The idea is to localize a fragment once and reuse it in multiple adaptive forms.

NOTE
The localization keys in the fragment won’t appear in the XLIFF file for an adaptive form.

Key points to remember when working with fragments key-points-to-remember-when-working-with-fragments

  • Ensure that the fragment name is unique. The fragment fails to create if there is an existing fragment with the same name.
  • In an XDP-based adaptive form, if you save a panel as fragment that includes another XDP fragment, the resulting fragment will be automatically bound to the child XDP fragment. If there is an XSD-based adaptive form, the resulting fragment will be bound to the schema root.
  • When you create an adaptive form fragment, a fragment node gets created, which is similar to the guideContainer node for an adaptive form, in CRXDe Lite.
  • A fragment in an adaptive form that uses a different form data model is not supported. For example, an XDP-based fragment is not supported in an XSD-based adaptive form and vice-versa.
  • Adaptive form fragments are available for use through the Adaptive Form Fragments tab in AEM content finder.
  • Any expression, script, or style in a stand-alone adaptive form fragment is retained when it is inserted by reference or embedded in an adaptive form.
  • You cannot edit an adaptive form fragment, which is inserted by reference, from within an adaptive form. To edit, you either edit the stand-alone adaptive form fragment or embed the fragment in the adaptive form.
  • When you publish an adaptive form, you need to publish the standalone adaptive form fragments inserted by reference in the adaptive form.
  • When you republish an updated adaptive form fragment, the changes reflect in the published instances of the adaptive form in which the fragment is used.
  • Adaptive form containing the Verify component does not support anonymous users. Also, it is not reommended to use the Verify component in an adaptive form fragment.
  • (Mac only) To ensure that the form fragments functionality works perfectly in all the scenarios, add the following entry to the /private/etc/hosts file:
    127.0.0.1 <Host machine> Host machine: The Apple Mac machine on which AEM Forms is deployed.

Reference Fragments reference-fragments

Reference adaptive form fragments that you can use to create your form are available. For more information, see Reference Fragments.

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2