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 client application queries a database for user information. The data is merged into the form and then the form is rendered to the user. As a result, the user is able to 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 in 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 (the examples in this section use an arbitrary XML data source).

An XML element must exist for every form field that 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 in which the XML elements are displayed, as long as all XML elements are specified.

When you prepopulate a form that already contains data, you must specify the data that is already displayed within the XML data source. Assume that a form containing 10 fields has data in four fields. Next, assume that you want to prepopulate the remaining six 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 six elements, the original four fields are empty.

For example, you can prepopulate a form such as the sample confirmation form. (See Confirmation form.)

To prepopulate the sample confirmation form, you have to create an XML data source that contains three XML elements that match the three fields in the form. 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 located in the form design. 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 then render the form, the data values that you assigned to the XML elements are displayed, as shown in the following diagram.

Prepopulating forms with flowable layouts

Forms with flowable layouts are useful to display an undetermined amount of data to users. Because the layout of the form adjusts automatically to the amount of data that is merged, you do not need to predetermine a fixed layout or number of pages for the form as you need to do with a form with a fixed layout.

A form 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 in-memory XML data source.

Consider a web-based application, such as an online store. After an online shopper finishes purchasing items, all purchased items are placed into an in-memory XML data source that is used to prepopulate a form. The following diagram shows this process, which is explained in the table following the diagram.

The following table describes the steps in this diagram.

The following diagram shows an example of a purchase order form. The information in the table can adjust to the number of records in the XML data.

Form design considerations

Forms with flowable layouts are based on form designs that are created in Designer ES2. A form design specifies a set of layout, presentation, and data capture rules, including calculating values based on user input. The rules are applied when data is entered into a form. Fields that are added to a form are subforms that are within the form design. For example, in the purchase order form shown in the previous diagram, each line is a subform. For information about creating a form design that contains subforms, see Creating a purchase order form that has a flowable layout.

Understanding data subgroups

An XML data source is used to prepopulate forms with fixed layouts and flowable layouts. However, the difference is that an XML data source that prepopulates a form with a flowable layout contains repeating XML elements that are used to prepopulate subforms that are repeated within the form. These repeating XML elements are called data subgroups.

An XML data source that is used to prepopulate the purchase order form shown in the previous diagram contains four repeating data subgroups. Each data subgroup corresponds to a purchased item. The purchased items are a monitor, a desk lamp, a phone, and an address book.

The following XML data source is 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 that is located in the form design. For example, in the previous diagram, notice that the name of the data subgroup's parent XML element is detail. This corresponds to the name of the subform that is located in the form design on which the purchase order form is based. 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 located in the form design contains the following fields:

• txtPartNum
• txtDescription
• numQty
• numUnitPrice

Summary of steps

To prepopulate a form with a flowable layout, perform the following tasks:

1. Include project files.
2. Create an in-memory XML data source.
3. Convert the XML data source.
4. Render a prepopulated form.

Include project files

Include necessary files into your development project. If you are creating a client application using Java, include the necessary JAR files. If you are using web services, ensure that you include the proxy files.

Include project files

Include necessary files into your development project. If you are creating a client application using Java, include the necessary JAR files. If you are using web services, ensure that you include the proxy files.

Create an in-memory XML data source

You can use org.w3c.dom classes to create an in-memory XML data source to prepopulate a form with a flowable layout. You must place data into an XML data source that conforms to the form. For information about the relationship between a form with a flowable layout and the XML data source, see Understanding data subgroups.

Convert the XML data source

An in-memory XML data source that is created by using org.w3c.dom classes can be converted to a com.adobe.idp.Document object before it can be used to prepopulate a form. An in-memory XML data source can be converted by using Java XML transform classes.

Render a prepopulated form

You render a prepopulated form just like other form. The only difference is that you use the com.adobe.idp.Document object that contains the XML data source to prepopulate the form.

See also

Prepopulating forms using the Java API

Prepopulating forms using the web service API

Including LiveCycle ES2.5 Java library files

Setting connection properties

Forms Service API Quick Starts

Rendering Interactive PDF Forms

Creating Web Applications that Renders Forms