Prepopulating forms

Prepopulating forms with a flowable layout
Understanding data subgroups

Prepopulating forms displays data to users within a rendered form. For example, assume a user logs in to a website with a user name and password. If authentication is successful, the custom application queries a database for user information. The data is merged into the form and the form is then rendered to the user. As a result, the user can view personalized data within the form.

Prepopulating a form has the following advantages:

Enables the user to view custom data in a form
Reduces the amount of typing the user does to fill a form
Ensures data integrity by having control over where data is placed

The following two XML data sources can prepopulate a form:
An XDP data source, which is XML that conforms to XFA syntax (or XFDF data to prepopulate a form created using Acrobat).
An arbitrary XML data source that contains name/value pairs matching the form’s field names.

An XML element must exist for every form field you want to prepopulate. The XML element name must match the field name. An XML element is ignored if it does not correspond to a form field or if the XML element name does not match the field name. It is not necessary to match the order that the XML elements are displayed in if all XML elements are specified.

When you prepopulate a form that already contains data, specify the data that is already displayed within the XML data source. Assume that a form containing 10 fields has data in 4 fields. Next, assume that you want to prepopulate the remaining 6 fields. In this situation, you must specify 10 XML elements in the XML data source that is used to prepopulate the form. If you specify only 6 elements, the original 4 fields are empty.

For example, to prepopulate a confirmation form, you must create an XML data source containing three XML elements that match the three form fields. This form contains the following three fields: FirstName, LastName, and Amount. The first step is to create an XML data source that contains XML elements that match the fields in the form design. This step is shown in the following XML code.
```
<Untitled> 
    <FirstName> 
    <LastName> 
    <Amount> 
</Untitled>
```
The next step is to assign data values to the XML elements, as shown in the following XML code.
```
<Untitled> 
    <FirstName>Jerry</FirstName> 
    <LastName>Johnson</LastName> 
    <Amount>250000</Amount> 
</Untitled>
```
After you prepopulate the confirmation form with this XML data source and render the form, data values that you assigned to the XML elements are displayed. The displayed data values are shown in this illustration.

View full size graphic

Prepopulating forms with a flowable layout

Forms with a flowable layout are useful to display an undetermined amount of data to users. The layout of the form adjusts automatically to the amount of data that is merged. Therefore, predetermining a number of pages is not required as with a form with a fixed layout.

A form with a flowable layout is typically populated with data that is obtained during run time. As a result, you can prepopulate a form by creating an in-memory XML data source and placing the data directly into the data source.

The following illustration shows an example of a purchase order form with a flowable layout.

View full size graphic

A.: Represents the dynamic portion of the form.
B.: Represents the form’s header data.

Note: Forms can be prepopulated with data from other sources, such as an enterprise database or external applications.

Understanding data subgroups

An XML data source is used to prepopulate a form. An XML data source that is used to prepopulate a form with a flowable layout contains repeating data subgroups. The following XML code shows the XML data source used to prepopulate the purchase order form.

    <header>  
        <!-- XML elements used to prepopulate non-repeating fields such as address 
        <!and city  
        <txtPONum>8745236985</txtPONum>  
        <dtmDate>2004-02-08</dtmDate>  
        <txtOrderedByCompanyName>Any Company Name</txtOrderedByCompanyName>  
        <txtOrderedByAddress>555, Any Blvd.</txtOrderedByAddress>  
        <txtOrderedByCity>Any City</txtOrderedByCity>  
        <txtOrderedByStateProv>ST</txtOrderedByStateProv>  
        <txtOrderedByZipCode>12345</txtOrderedByZipCode>  
        <txtOrderedByCountry>Any Country</txtOrderedByCountry>  
        <txtOrderedByPhone>(123) 456-7890</txtOrderedByPhone>  
        <txtOrderedByFax>(123) 456-7899</txtOrderedByFax>  
        <txtOrderedByContactName>Contact Name</txtOrderedByContactName>  
        <txtDeliverToCompanyName>Any Company Name</txtDeliverToCompanyName>  
        <txtDeliverToAddress>7895, Any Street</txtDeliverToAddress>  
        <txtDeliverToCity>Any City</txtDeliverToCity>  
        <txtDeliverToStateProv>ST</txtDeliverToStateProv>  
        <txtDeliverToZipCode>12346</txtDeliverToZipCode>  
        <txtDeliverToCountry>Any Country</txtDeliverToCountry>  
        <txtDeliverToPhone>(123) 456-7891</txtDeliverToPhone>  
        <txtDeliverToFax>(123) 456-7899</txtDeliverToFax>  
        <txtDeliverToContactName>Contact Name</txtDeliverToContactName>  
    </header>  
    <detail>  
        <!-- A data subgroup that contains information about the monitor> 
        <txtPartNum>00010-100</txtPartNum>  
        <txtDescription>Monitor</txtDescription>  
        <numQty>1</numQty>  
        <numUnitPrice>350.00</numUnitPrice>  
    </detail>  
    <detail>  
        <!-- A data subgroup that contains information about the desk lamp> 
        <txtPartNum>00010-200</txtPartNum>  
        <txtDescription>Desk lamps</txtDescription>  
        <numQty>3</numQty>  
        <numUnitPrice>55.00</numUnitPrice>  
    </detail>  
    <detail> 
        <!-- A data subgroup that contains information about the Phone> 
            <txtPartNum>00025-275</txtPartNum>  
            <txtDescription>Phone</txtDescription>  
            <numQty>5</numQty>  
            <numUnitPrice>85.00</numUnitPrice>  
    </detail>  
    <detail> 
        <!-- A data subgroup that contains information about the address book> 
        <txtPartNum>00300-896</txtPartNum>  
        <txtDescription>Address book</txtDescription>  
        <numQty>2</numQty>  
        <numUnitPrice>15.00</numUnitPrice>  
    </detail>

Notice that each data subgroup contains four XML elements that correspond to this information:

Items part number
Items description
Quantity of items
Unit price

The name of a data subgroup’s parent XML element must match the name of the subform in the form design. For example, in the previous illustration, notice that the name of the data subgroup’s parent XML element is detail. This corresponds to the name of the subform located in the form design that the purchase order form is based on. If the name of the data subgroup’s parent XML element and the subform do not match, a server-side form is not prepopulated.

Each data subgroup must contain XML elements that match the field names in the subform. The detail subform in the form design contains the following fields:
txtPartNum
txtDescription
numQty
numUnitPrice