Binding an XML Schema Document (XSD) to repeating subform elements using Adobe LiveCycle Designer

Additional required other products (third-party/labs/open source)

• An XML/XSD editor program of one’s choice

  or

• A text editor program (like Notepad++)

The problem that this article aims to solve is how to bind dynamic form fields to an XML Schema Document (XSD) element using LiveCycle Designer ES. 

Dynamic interaction with electronic forms is one of LiveCycle’s most attractive features.  Having a form conform to the size document required for a particular transaction can save on printing costs (if the form needs to be printed) and by presenting only the amount of information required to complete a transaction, a form is easier to read and understand by a user.  Form objects, like buttons, can be used to add or delete the required number of data-input fields from a form.  

Data captured by a form’s objects are stored within the form as XML data.  In order to feed this XML data to back-end services, the XML needs to be structured.  By default, the XML data that is output in a form conforms to an XML Path (XPath) structure that mimics the layout of the form objects themselves and their relation to their position on the form.  This method of naming XPaths often isn’t useful to a back-end developer, so in order to structure the XML being output from a form in a manner that is logical to the back-end developer, an XSD document is used. 

The XSD document is basically a schema or rule-set document written in the XML mark-up language.  This XSD describes how the XML data should be structured when it is extracted from the form.  Once a form object has been bound to the schema elements, the data captured in the form becomes stored in an XML document in the format as described by the XSD.

The issue at hand is: how does one bind an element of a dynamically repeating form object to a schema element?  After all, the objects only appear in the form structure once and in the schema structure once, but could be used to store several sets of data.  This document seeks to explain the forms’ structural requirements and binding conventions required to bind a form to a schema for these sets of repeating data.

The form that will be used as an example for this tutorial (see Figure 1) is a simple form that one could use to petition a site administrator to allow its corporate partners to have some power users use the corporate Web site.  The number of users varies, so in order for the site administrator to add the appropriate amount of users, an “Add User” button is added.  By pressing this button, a new block of users appears, which captures the same information: User First Name, User Last Name, Add/Change/Delete (the named user), User Phone Number, and User Email Address.

First, a form needs to be constructed that contains the desired repeating field functionality.  This is achieved by creating a form with a flowed layout.  A flowed layout is not a static layout.  Rather, as the name implies, a flowed layout can change size and expand or retract as needed.  By default, a flowed layout will stack all form objects on top of each other and align them to the left. Since this does not adequately use up the form’s real estate (usable whitespace area on a form), one needs to use either a table, or preferably, a subform that has a positioned layout within the flowed layout.

Create a SubForm That has a Flowed Layout

It does not matter if one makes the entire page, or a wrapped subform the flowed section, it only needs to be flowed.

Note: If you are making the entire page flowed, you would do this by right clicking on the item in the form object hierarchy that represents the page in the design view (by default this is called, “(untitled Subform)(page 1)”. Be sure that you are not right-clicking on the “Page1” object under the “(Master Pages)” object.

To create a new subform:

1. Right-click on the page in the form-object hierarchy (by default on the left side of Designer)
2. In the pop-up menu that appears, select “Insert Subform”
3. Name your subform accordingly (in the example shown below this object has been named “UserDesigneeContainer”)
4. Be sure that the “Content” setting in the “Subform” tab under the “Object” Palette is set to “Flowed”

Within the Flowed Subform, Create a Subform that has a Positioned Layout

1. Right-click on the newly created flowed subform in the form-object hierarchy
2. In the pop-up menu that appears, select “Insert Subform”
3. Name your subform accordingly (in the example shown below this object has been named “UserDesigneeSubform”)
4. Be sure that the “Content” setting in the “Subform” tab under the “Object” Palette is set to “Positioned”
5. Add the form elements that will be repeated in this subform (as shown in Figures 2 and 3 below)

XML schema development is out-of-scope for this tutorial, but one must create an XML schema for the form and then create a data connection between the form and the schema. Information on how to establish a data connection between a form and an XML schema is available in the Adobe LiveCycle documentation.

An XML schema can be developed with any XML or XSD schema development tool, or it can simply be made with a simple text editor like the open source product Notepad ++.  The one requisite trait about the XML schema is that one must include a section that mimics the structure of the repeating subform.

In the example shown above, the “UserDesigneeSubform” has a few data-capture elements, namely:

• UserFirstNm – a text field
• UserLastNm – a text field
• UserAddChangeDelIn – a drop-down list selector
• UserTelNo – a text field (could also be a numeric field)
• UserEmailAd – a text field

This means that the XML schema document must also have the same elements defined (as shown in Figure 4 below).  Note that both the containing “flowed” object (UserDesigneeContainer) and the subform “positioned” object (UserDesigneeSubform) need to have the attribute “maxOccurs” set to unbounded.  Note also how the repeating “UserDesigneeSubform” object must also be embedded within the “UserDesigneeContainer” object to reflect its position in the form hierarchy in Designer.

Once the schema has been developed, and the data connection established, one can begin the process of binding the forms elements to the schema. You can find information on binding fields to a data source here.

Use the Bracketed Asterisk Convention “[*]”

The one difference between a typical binding of a form object to an XML schema, is that the developer must also include a bracketed asterisk “[*]” in the binding path in Designer (as shown in Figure 5 below).

That’s all that is required to bind the repeating subform to the XSD.  Now when a user adds a section to the form for completion, another identical XML output node will appear (as shown in Figure 6 below).

Where to go from here

This tutorial explained how to create a repeating subform in LiveCycle Designer, and how to bind that subform to an XSD in such a way that it dynamically adds XML output data to identically structured nodes in the XML output file.

• For more information on the general principles of XSD creation, refer to the w3schools website.
• For specific details about XML schemas and Designer, refer to the Adobe LiveCycle Designer Help.