Synchronizing Adaptive Forms with XFA Form Templates
You can create an adaptive form based on an XFA form template ( *.XDP file). This reuse allows you to preserve your investment in existing XFA forms. For information on how to use an XFA form template for creating an adaptive form, Create an Adaptive Form based on a template .
You can reuse fields from the XDP file in your adaptive form. These fields are referred to as binded fields. The properties of the binded fields (such as scripts, labels, and display format) are copied from the XDP file. You can also choose to override the value of some of these properties.
AEM Forms provides a way to help you keep the fields of the adaptive forms synchronized with any changes that are later made to the corresponding fields in the XDP file. This article explains how you can enable this synchronization.
In the AEM Forms authoring environment, you can drag fields from an XFA form (left) to an adaptive form (right)
To use the information in this article, a familiarity with the following areas is recommended:
- XFA (XML Forms Architecture)
To use the assets provides for the example in the article, download the sample package as explained in the next section, Sample package .
The article uses an example to demonstrate how to synchronize the adaptive form with an updated XFA form template. The assets used in the example are available in a package, which can be downloaded from the Downloads section in this article.
After uploading the package, you can view these assets in the AEM Forms UI.
Install the package using the package manager: https://<server>:<port>/crx/packmgr/index.jsp
The package contains the following assets:
- sample-form.xdp : The XFA form template used as an example
- sample-xfa-af : The adaptive form based on the sample-form.xdp file. This adaptive form, however, does not include any fields. In the next step, we will add content to this adaptive form.
Add content to adaptive form
- Navigate to https://<server>:<port>/aem/forms.html. Enter your credentials if asked.
- Open the sample-af-xfa for editing in author mode.
- From the Content browser in the sidebar, choose Data Model Objects tab. Drag NumericField1 and TextField1 onto the Adaptive Form.
- Change the Title of the NumericField1 from Numeric Field to AF Numeric Field.
In the preceding steps, we overwrote a property of a field in the XDP file. This property will, therefore, not be synchronized if the corresponding property in the XDP file is modifiled later.
Detecting changes in XDP file
Whenever there is any change in an XDP file or a fragment, the AEM Forms UI flags all adaptive forms that are based on the XDP file or the fragment.
After updating an XDP file, you need to upload it again in the AEM Forms UI for the changes to be flagged.
As an example, let us update the sample-form.xdp file using the following steps:
- Navigate to https://<server>:<port>/projects.html. Enter your credentials if prompted.
- Click the Forms tab on the left.
- Download the sample-form.xdp file on your local machine. The XDP file is downloaded as a .zip file, which can be extracted using any file decompression utility.
- Open the sample-form.xdp file and change the title of the field TextField1 from Text Field to My Text Field .
- Upload the sample-form.xdp file back into the AEM Forms UI.
If an XDP file gets updated, you see an icon in the editor, when you edit the adaptive forms based on the XDP file. This icon indicates that the adaptive form is out of sync with the XDP file. In the following image, see the icon next in the sidebar.
Synchronizing adaptive forms with the latest XDP file
When an adaptive form that is out of sync with the XDP file is opened for authoring the next time, the following message is displayed: Schema/Form Template for the Adaptive Form has been updated. Click Here to rebase it with the new version.
Clicking on the message synchronizes the fields in the adaptive form with the corresponding fields in the XDP file.
For the example used in this article, open sample-xfa-af in authoring mode. The message is displayed toward the bottom of the adaptive form.
Updating the properties
All the properties that were copied from the XDP file to the adaptive form are updated except for the properties that were explicitly overridden in the adaptive form (from the Component Dialog) by the Author. The list of properties that have been updated is available in the server logs.
To update the properties in the example adaptive form, click the link (labeled "Click Here" ) in the message. The title of TextField1 changes from Text Field to My Text Field .
The label AF Numeric Field did not get changed because you had overridden this property from the component properties dialog, as described in Add content to adaptive forms .
Adding new fields from XDP file to adaptive form
Any fields that are added later to the original XDP file appear in the Form Hierarchy tab and you can drag those new fields to the adaptive form.
You do not need to click the link in the error message to update the fields in the Form Hierarchy tab.
Deleted fields in XDP file
If a field that was earlier copied to an adaptive form is deleted from an XDP file, an error message is displayed in the authoring mode stating that the field doesn't exist in the XDP file. In such cases, manually delete the field from adaptive form or clear the bindRef property in the component dialog.
The following steps illustrate this use flow for the assets in the example used in this article:
- Update the sample-form.xdp file and delete NumericField1.
- Upload the sample-form.xdp file in the AEM Forms UI
- Open the sample-xfa-af adaptive form for authoring. The following error message is displayed: Schema/Form Template for the Adaptive Form has been updated. Click Here to rebase it with the new version.
- Click the link (labeled " Click Here ") in the message. An error message is displayed noting that the field doesn't exist anymore in the XDP file.
The field that has been deleted is also marked with an icon to indicate an error in the field.
The fields in the adaptive form that have an incorrect binding (an invalid bindRef value in the edit dialog) are also considered as deleted fields. If the author doesn't fix these errors and publish the adaptive form, the field is treated as a normal unbinded adaptive form field and is included in the unbinded section of the output XML file.
Content-package for the example in this article