If you have been struggling with connecting a form to a database, are wanting to know what the best practices and/or security concerns are, or have some specific questions you would like to ask, I highly recommend you attend the session. It’s free to attend (and free to become a member in order to attend)!

I’ll be answering chat questions “live” as the session unfolds. I hope you can join us!

The service is quite simple: It displays what you submit to it. Since Designer’s “PDF Preview” tab is actually an instance of Internet Explorer hosting a PDF version of the form you’re previewing (a temporary PDF if your form is saved as an XDP or is new), the results are conveniently displayed within the tab itself after clicking on the submit button.

To use the service, simply use either an http submit button (or a regular button with its “Object palette > Field tab > Control Type property” set to “Submit”) and set its URL to:

http://forms.stefcameron.com/services/http-submit-test/

The idea is to use this service as a means to test/debug your forms before spending time writing the actual server code that will receive the data. You can also use it to ensure that you are submitting the correct data to a third-party service (for which you don’t control the server-side code).

Choosing a Submit Format

HTTP submissions can be made in various formats: XML, XDP, URL-encoded (HTTP post), and PDF. If you are using Reader instead of Acrobat, you will not be able to submit in PDF format unless you have enabled this ability using LC Reader Extensions.

The most important difference amongst the formats is that repeating data sets cannot be submitted using URL-encoding (HTTP post). This is due to the way the data is submitted: In HTTP post directives, data is submitted in “name=value” pairs. Since repeating data sets involve hierarchy and duplicate data node names, only the last instance of the repeating set will be submitted.

To submit repeating data sets, you must choose either XML, XDP or PDF as the data format.

Sample Form

The following sample form demonstrates the use of the HTTP Submit Test service.

Download Sample [pdf]

The form has a typical address block as well as a table to demonstrate both static and repeating data sets. Use the submit buttons to try submitting in different formats (XML, XDP, PDF, URL-encoded). Notice how only the last table row is submitted when using the URL-encoded (“post”) submit button.

Minimum Sample Requirements: I created this sample using Designer 9.0 and Acrobat 9.2 however it should work fine back to Acrobat 7.0.5.

Last February, I announced the release of a new Designer book titled, “PDF Forms Using Acrobat and LiveCycle Designer Bible”.

Over the past few months, I had the opportunity to review it and I thought I would share my comments, with respect to the second-half of the book, which deals with LiveCycle Designer ES and XFA forms, to help you decide if it would be a good book for you*. (The first-half deals with authoring PDF forms, a.k.a. AcroForms, in Acrobat and is beyond the scope of my blog.)

How Lists Store Selected Items

To better understand the challenges, let’s look at how list form objects store a multi-selection of values.

In the Form DOM, the list’s value actually contains XML rather than plain text. For example, say we have a multi-selection list named “ListBox1″ (bound to a data element named “list1″) with items (“item1″, “item2″, “item3″). If the first two items were selected, the list’s value would look like this:

<value>
    <exData contentType="text/xml">
        <list1>
            <value>item1</value>
            <value>item2</value>
        </list1>
    </exData>
</value>

In script, this would translate to a newline (\n)-delimited string when the list’s value is accessed from its rawValue property:

item1\nitem2

In the Data DOM, the list’s value is stored in a series of repeating <value> nodes, much like the way it is stored in the Form DOM:

<list1>
    <value>item1</value>
    <value>item2</value>
</list1>

Adding the Schema

A schema describes how XML should be structured. Given how lists store their selected items in data, a schema that includes a multi-selection list will need to allow for the element that defines the list to contain zero or more repeating <value> nodes. Unfortunately, this means modifying your schema, if you already have one. (I can think of at least one workaround to this which would involve script and a sibling, hidden text field bound to the element in your schema, as opposed to the list itself, in which you would store the selection, but I won’t get into that in this article.)

For example, this is a schema that defines a “form1″ root element that contains an element named “list1″ that has a multi-selection list type (the way XFA expects it).

Data Connection

The problem with this structure is that once you connect your form to this schema, the Data View connection tree will interpret the list1 element as being a subform that contains a repeating node, “value”:

Because of this interpretation, you cannot simply drag & drop the “list1″ schema element into your form in order to get a multi-selection list. Instead, you’ll get a subform with a text field inside of it instead (only an element with a simple type restricted to an enumeration of values would be interpreted as a list). Furthermore, you cannot use the picker widget next to the “Object palette > Binding tab > Data Binding property” to assign “list1″ to a listbox you have already dragged into your form from the Object Library palette because “list1″ is viewed as a container (subform) and the form object you are attempting to bind is a field.

Data Binding

In order to bind the listbox to the “list1″ schema element, you must manually type its binding expression into the “Object palette > Binding tab > Data Binding property”. For our simple use case, the binding is “list1″. Note that you don’t actually bind the repeating “value” element to anything and that the schema data connection tree will not actually indicate that the “list1″ element is bound to a form object even though it now is (I’m guessing this is because it is expecting “list1″ to be bound to a subform, not a field).

The result of binding the listbox to the “list1″ schema element is that the Form DOM output changes slightly to include the proper namespace on the bound element within the field’s value:

<value>
    <exData contentType="text/xml">
        <scof:list1 xmlns:scof="http://forms.stefcameron.com/ns/2009/">
            <value>item1</value>
            <value>item2</value>
        </scof:list1>
    </exData>
</value>

Submitting Data

As you might expect, given the structure of the listbox’s selection in the Form DOM above, the list’s selection data will be similar in the Data DOM (which is what would be submitted from the form as well):

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
    <scof:form1 xmlns:scof="http://forms.stefcameron.com/ns/2009/">
        <scof:list1>
            <value>item1</value>
            <value>item2</value>
        </scof:list1>
    </scof:form1>
</xfa:data>

The only problem with the data above is that it isn’t valid against the schema which specifies that the repeating <value> nodes inside the list1 element are part of the “scof” (target) namespace and should therefore look like <scof:value>.

Submitting Namespaced Data

In order to get the namespace into the repeating <value> nodes for the selected values, we have to use a workaround that involves a little script in the listbox’s Exit event (though the script could be triggered elsewhere, if you like):

// JavaScript:

// schema namespace info
var nspace = "scof";
var nsUri = "http://forms.stefcameron.com/ns/2009/";

// get selection from list
var selection = this.rawValue.split("\n");

// build XML string for new selection in *Form DOM*
//  that includes the namespace in the <value>
//  nodes the outer <listSelection> node is
//  essentially irrelevant and will be discarded later
//  however it is required so that we can load its
//  content into the listbox's exData value node where
//  its value is set in the Form DOM
// this.dataNode.name gets the listbox's bound data
//  element name from the Data DOM which is required
//  in the XML
var newSelection = "<listSelection>\n<" + nspace +
    ":" + this.dataNode.name + " xmlns:" + nspace +
    "='" + nsUri + "'>";

// add selected items into the new selection -- take
//  note of the newline character at the beginning of
//  the string as it is critical to the XML loading
//  properly later on (it shouldn't be but it is...)
for (var i = 0; i < selection.length; i++)
{
    newSelection += "\n<" + nspace + ":value>" +
        selection[i] + "</" + nspace + ":value>";
}

// close the XML elements in the string
newSelection += "\n</" + nspace + ":" +
    this.dataNode.name + ">\n</listSelection>";

// load the new namespaced selection into the listbox's
//  exData value node, ignoring the root <listSelection>
//  node in the XML string
this.value.exData.loadXML(newSelection, true, true);

The script above essentially builds an XML string equivalent in structure to that which is normally used to store the list’s selection in the Form DOM however it adds the necessary namespaces to the repeating <ns:value> nodes. This change is then replicated in the list1 data node in the Data DOM and the form’s exported data changes to this (which can be successfully validated against the schema we’re using):

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
    <scof:form1 xmlns:scof="http://forms.stefcameron.com/ns/2009/">
        <scof:list1>
            <scof:value>item1</scof:value>
            <scof:value>item2</scof:value>
        </scof:list1>
    </scof:form1>
</xfa:data>

Import Data Warning

Unfortunately, I have to point-out a bug as it relates to exporting multi-selection values with namespaces (which you only get when you use the above workaround script): Importing data with namespaced <ns:value> nodes for multi-selection lists — though valid XML and valid against the schema — will fail in Acrobat 9.1.3 (I have not done any testing on previous versions). My testing has revealed that the form doesn’t render properly after the data merge. Importing namespaced data that does not have namespaced <value> nodes for multi-selection lists, however, does work fine (this is the default way data is exported, unless you use the script I outlined above).

Sample Form

I have built a sample form that demonstrates how multi-selection lists store their data in the Form DOM and Data DOM. The form also includes a checkbox which, when checked, will generate namespaced <ns:value> nodes instead of the default <value> nodes, using the workaround script in the list’s Exit event.

Download:

• Form [pdf]
• Schema [xsd]
• Sample Data [xml]
• Sample Data (namespaced) [xml]

Minimum Requirements: I designed this form using Designer ES2 Beta and Acrobat 9.1.3 however the form should work all the way back to Designer 7.1 and Acrobat 7.0.5.

Using metadata based on a combination of the XML Schema appInfo and Dublin Core title and description elements, you can influence how the Data Connection Wizard creates fields you drag and drop from the data connection tree into your form. You can also direct the Data View palette to show some of this information in the Schema Data Connection Tree that it displays.

To demonstrate these features, I have extended the original movie rental schema by adding metadata to its schema elements.

Element Descriptions

Sometimes a schema element’s purpose or use isn’t immediately clear based on its name and/or other properties. For example, just by seeing that the schema has a “customer.account” element wouldn’t necessarily tell you that this element should be empty for a new customer (since the system would generate a new account number upon submission of the customer’s first movie rental order). To clarify the use of this element, a description can be provided:

<xs:element name="account" type="xs:string" minOccurs="0">
    <xs:annotation>
        <xs:appinfo>
            <dc:description>
                Customer's account number (empty if it's a new customer).
            </dc:description>
        </xs:appinfo>
    </xs:annotation>
</xs:element>

Using the “Data View palette > Palette menu button > ‘Show Both’ command”, you can see the <dc:description> metadata associated with elements in your schema right within the Data Connection Tree:

Note that the description element must be part of the Dublin Core namespace (xmlns:dc=http://purl.org/dc/elements/1.1/) and must be contained within the XML Schema //annotation/appInfo elements in order for the Data Connection Wizard to detect it.

Form Object Captions

Often times schemas are defined at a corporate level because they can represent business rules and describe how data must be structured for its systems to be able to interpret it correctly. In those cases, it may be useful to also influence/dictate the labels that should be used to identify fields associated to certain schema elements. This can also be achieved with metadata by specifying title information:

<xs:element name="account" type="xs:string" minOccurs="0">
    <xs:annotation>
        <xs:appinfo>
            <dc:title>Account #:</dc:title>
        </xs:appinfo>
    </xs:annotation>
</xs:element>

Unlike descriptive metadata, this information is not displayed in the Data Connection Tree. Instead, it is used by the Data Connection Wizard when you drag and drop a schema element from the Data Connection Tree into your form.

Remember that, in the original schema (that didn’t have any metadata), generated fields would get captions similar to their schema element names. For example,  dragging the “customer.account” field into a form would produce a field with “Account” as its caption. With the title metadata as defined above, the generated caption would instead be “Account #:”, as in the image below:

Note that the title element must be part of the Dublin Core namespace (xmlns:dc=http://purl.org/dc/elements/1.1/) and must be contained within the XML Schema //annotation/appInfo elements in order for the Data Connection Wizard to detect it.

Extra Descriptive Information

There’s one more way to provide information related to an element in a schema: Any text that is directly specified within an XML Schema //annotation/appInfo element (and is not further contained within a Dublin Core title or description element) is interpreted as extra “descriptive information”. When the element is dragged and dropped into a form, this text will be imported and associated with the generated field within a <desc> node, provided the “Generate Descriptive Information” option is checked in the “Data View palette > Palette menu button > Options dialog”:

For example, the “returnBy” schema element is defined as follows:

<xs:element name="returnBy" type="xs:date">
    <xs:annotation>
        ...
        <xs:appinfo>
            Movies must be returned by 11:59pm on this date.
        </xs:appinfo>
        <xs:appinfo>
            The late fee is is $0.50/hour.
        </xs:appinfo>
    </xs:annotation>
</xs:element>

Dragging and dropping that element into your form would produce the following field mark-up in the XML Source view:

<field name="returnBy">
    ...
    <desc>
        <text name="Schema Annotation">
            Movies must be returned by 11:59pm on this date.
        </text>
        <text name="Schema Annotation 2">
            The late fee is is $0.50/hour.
        </text>
    </desc>
</field>

The Info palette could then be used to view the contents of all nodes inside the selected field’s <desc> node:

You can associate any number of extra “descriptive information” metadata elements to a single schema element definition. Each one would be imported as a separate <text name=”Schema Annotation {x}”> node within the associated form object’s <desc> node

This information can also be viewed within the Data View palette by choosing the “Palette menu button > ‘Show Info’ command”. This will display the Info Panel in the bottom half of the palette. Selecting the “returnBy” schema element would then display the following information:

• XFA object name (returnBy);
• associated XFA object type (date/time field, since the schema defines its type as “date”);
• occurrence (single since it isn’t repeatable like the “movie” element, for example); and
• all other metadata identified as “descriptive info” associated to the element.

Script Access

Finally, the descriptive information found in a form object’s //desc/text nodes can be retrieved via script by accessing its “desc” node property and iterating through all child nodes that are of type “text” and have “Schema Annotation” in their name.

For example, to output the two descriptions in the “returnBy” field (as defined above) to the JavaScript Console in Acrobat, you could use the following script:

// JavaScript:
var descList = returnBy.desc.nodes;
for (var i = 0; i < descList.length; i++)
{
    var item = descList.item(i);
    if (item.className == "text" && item.name &&
            item.name.indexOf("Schema Annotation") == 0)
    {
        console.println(item.value);
    }
}

With a little more effort, you could parse-out all sorts of useful information provided by this type of metadata in your schemas though, most of the time, that information can usually be expressed in real schema mark-up (e.g. list items and values).

Combinations

Of course, you aren’t limited to using a single type of metadata on a given schema element: You can combine them to provide the degree of information you require for any element. For example, the “customer.account” element specifies both title and description metadata while the “returnBy” element specifies title and descriptive information metadata.

If you work in an enterprise setting, chances are you may have already had to deal with corporate data schemas that define how that data is structured. The goal, when connecting a form to a schema, is to ensure that the data consumed and output by the form adheres to a specific structure. Any fields bound to data nodes that aren’t inside the schema space are basically ignored at time of submission.

To help put things in context, I decided to define a schema for movie rentals to stay on the movie theme for the data I used in my other data connection tutorials.

Before we get started, I wanted to point-out that there are so many features related to schema handling and the Data View palette that I won’t be able to cover them all in a single tutorial. It would be information overload. Instead, I’ll try to point-out the basics along with a few interesting things that I think would be useful.

Creating the Connection

Right-click in the Data View palette and choose “New Data Connection”. In the first step, set the name for the connection (I set it to “SchemaConnection” so it’s easy to identify amongst any other connections that might be defined) and choose “XML Schema” as the type.

Note that while you may have multiple ODBC and web service data connections, a form may be connected to only one schema. As of XFA 3.0 (Designer ES2, Acrobat/Reader 9.1), however, you can inject foreign data nodes into the Data DOM even if they aren’t in the schema, which may help if you need to get extra data into/out of your form (a topic for another post; for now, have a look at the new “File > Form Properties > Data Binding tab” in the Designer ES2 Beta). You can also merge schemas into a single, larger schema (<import/> nodes are supported which can make importing multiple schemas into a single one relatively easy).

The next and final steps are to choose the schema file and root element. Depending on how your schema is defined, you may have a choice of elements to use as the root. In the Movie Rental schema, there is only one root: “movieRental”.

There are other options that let you embed the schema definition into your form (good if you don’t want to have to keep the schema file along with your form; otherwise, whenever you edit your form, you will need to ensure that the schema file is available) as well as specify XSLT files for incoming and outgoing data transformations (also a topic for another post).

Data View Palette

The initial view of the connection in the palette shows the data structure specified by the schema as represented in XFA. Each node in the schema gets an associated XFA object type depending on its description.

For example:

• Complex types (such as {customer} and {movie}) are usually mapped to subforms since they are elements that contain child elements.
• Simple types (such as {customer.firstName} and {customer.prov}) are typically mapped to XFA fields. As you can see, the Schema Data Connection Wizard detected various types and assigned specific XFA fields to each data node: The {customer.prov} node is set to a drop down list because that element is defined as an enumeration of specific values in the schema while {movie.cost} is set to a decimal field because it’s type is “xs:decimal”.

Root Subform Name

When the connection was created, there was a change to your form’s root subform name. Note how it has changed to movieRental:

The name of the root subform is always the name of the root data element in the Data DOM. This ensures that data submitted from the form has the correct root element to match the schema and data merged into the form will be bound first by the root subform, then by child form objects.

Inserting New Fields

The Data View palette can be used to insert fields into your form. This makes it really easy to create new fields with the proper settings and bindings. You can customize how fields are created by choosing “Palette menu button > Options”:

• Generate Validation Scripts: If enabled, field Validate events will be generated for elements that have certain restraints defined in the schema.
• Generate Descriptive Information: If enabled, particular forms of metadata in the schema will be inserted into the field definitions in your form (more on this in another post).
• Allow Tables to be Generated: If enabled, tables, rather than plain subforms, will be generated where appropriate.
• Show Binding Properties Dialog Box: If enabled and you drag & drop an element onto an existing field, a customization dialog will be displayed (more on this later).

To insert a new field configured according to an element in the schema, just drag & drop the element from the connection tree (in the Data View palette) into your form. You can add an entire group in a single operation by dragging a container element (e.g. {customer}). When a field in your form is bound to an element in the schema, a binding icon is displayed next to the element in the connection tree.

Start by dragging and dropping the {customer} element into your form. The result should be a new subform named “customer” containing 8 fields named according to the schema’s {customer} element and the elements it contains.

New fields on the form.

New structure in the hierarchy.

Notice how each leaf element in the connection now has a binding icon next to it in the connection tree (indicating that fields on the form are bound to those schema elements). The inserted fields were also customized according to their schema element counterparts. For example:

• All fields have appropriate data bindings (see “Object palette > Bindings tab > Data Binding property”).
• The {customer.prov} element became a drop down list which has a list of items, as well as a default value of “ON”, as specified in the schema.
• All new form objects have names that match their schema element names (though these could be altered, if better suited to any scripting requirements you may have, without affecting the data bindings).
• All new form objects have captions that are derived from their schema element names (e.g. the field bound to {customer.firstName} has a caption of “First Name”).

Next, drag and drop the {movie} element from the connection into your form. This element is special because the schema specifies it may have multiple occurrences:

<xs:element
    name="movie"
    type="movieDef"
    minOccurs="1"
    maxOccurs="unbounded"/>

The result is a repeatable subform, as you can see by the Binding properties that were automatically set on the new “movie” subform (bound to movie[*] with Min Count set to 1 and no specified Max Count (unbounded)):

(Note that if the properties on the “Object palette > Binding tab” are partially disabled, it’s most likely because the movie subform is not inside a flowed container. Though it isn’t an XFA requirement, Designer requires it in order to enable the repeatable properties. We’ll fix this shortly.)

Binding to Existing Fields

There are two ways to bind an existing field to an element in the schema connection:

1. Simply choose the element to which the field should bind by using the “Object palette > Binding tab > Data Binding property” pop-out menu (button to the right-hand side of the property) and selecting it from within the schema connection’s sub menu.
2. Drag an element from the connection tree, in the Data View palette, and drop it on top of a field in your form. Doing so will — if it’s enabled — cause the Binding Properties Dialog Box to be displayed, giving you some options to further customize the existing field with information from the schema.

Binding Properties Dialog Box

Add a new text field to your form. This will be for the {returnBy} schema element. Ensure that the “Show Binding Properties Dialog Box” option is checked in the “Data View palette > Palette menu button > Options” dialog. Now drag the {returnBy} element from the connection and drop it on top of the new text field.

The above dialog will be displayed, giving you the option to update the following properties of the field on which the schema element was dropped:

• Name: Updates the name of the field to match the name of the schema element (from “TextField1″ to “returnBy”).
• Caption: Updates the caption of the field to one derived from the schema (from “Text Field” to “Return By”).
• Type: Updates the field’s object type to match the kind of data represented by the schema element (from text field to date/time field).
• Type > Default Value: Updates the field’s default value to that specified in the schema, if any (in the case of {returnBy}, the schema does not specify a default value).
• Type > Data Pattern: Updates the field’s patterns (display, edit, validate, data) according to the schema (in the case of {returnBy}, no pattern restrictions are specified in the schema, though a “date{YYYY-MM-DD}” data pattern will be set by default).

Choose the “Update all related properties” option and click on the “OK” button. The text field you previously inserted will be updated to a date/time field with various properties matching the {returnBy} schema element’s specifications (as detailed above).

Finishing Touches

At this point, your form should look something like this (the positioning of the objects may differ depending on where you dropped them):

Here are a few steps you can take to make things look a little nicer (in my opinion) as well as enable instances of the movie subform to be added for new movies to rent:

1. Place the movie subform in a flowed subform so that multiple instances can be added, flowed one after the other.
2. Place an “add” button next to the movie subform to add instances as well as a “remove” button inside the movie subform to remove specific instances.
3. Add an unbound decimal field that shows the running total cost for the movie rental order.
4. Add script to the returnBy field to automatically set the date 30 days in the future.
5. Add a submit button to submit the order.

Following the steps above should yield a more functional movie rental form. The only thing missing is the ability to pull-in movies to choose from. For one thing, this would avoid having to specify the movie ID, title and cost when choosing a movie to rent. To accomplish this, you could connect the form to a movie database (note that the database in the linked tutorial doesn’t have a “cost” column associated to a movie so you’ll have to add one) or, the more secure and recommended way, to a movie web service.

Download Sample Form [pdf]

Download Schema [xsd]

Download Sample Data [xml]

Minimum Requirements: I designed this form using Designer ES2 Beta and Acrobat 9.1 however the principals should work all the way back to Designer 7.1 and Acrobat 7.0.5. There may be a few features lacking from the Data View palette if you go back that far but the concept of connecting the form to a schema remains the same.

Aug 28, 2009 — Added link to Schema Metadata tutorial.

Nov 4, 2009 — Fixed a couple of syntax errors in the sample PDF form that were preventing the addition and removal of movie subform instances.

Creating Data Nodes

In a similar article, John Brinkman showed how to create form variable nodes at runtime however what’s not obvious about data nodes is that you don’t create them using

a class name of your choice.

For example, say you wanted to create the following data node structure:

<custom>
    <message>Hello World!</message>
</custom>

Given the following syntax for the createNode() function (see page 367 in the LC Designer 8.2 Scripting Reference):

{model}.createNode(className [, name, namespace]);

you might try the following, using “custom” as the class name for the first group/container node <custom>:

var n = createNode("custom");

Doing the above would generate an error stating that “custom” is an invalid node type.

The trick here is that only specific XFA class names are allowed, such as “text”, “decimal”, “integer”, etc., as well as two special types for data nodes: “dataGroup” and “dataValue”. When you need a data node that will contain other data nodes, you use the “dataGroup” class. When you need a data node to which you will assign a value, you use the “dataValue” node.

The JavaScript code to create the above XML structure then becomes:

// <custom> data group to contain <message>
var c = xfa.datasets.createNode("dataGroup", "custom");
// <message> data value for "Hello World!"
var m = xfa.datasets.createNode("dataValue", "message");
// set value of data value node
m.value = "Hello World!";
// add <message> into <custom> data group node
c.nodes.append(m);
// print result to JavaScript Console (Ctrl + J in Acrobat)
console.println(c.saveXML("pretty"));

// output from above:

<custom>
    <message>Hello World!</message>
</custom>

Note that the createNode() function must be called on an object of type “model” and since we’re creating nodes in the Data DOM, we use the xfa.datasets object since it is a model object.

At this point, the <custom> node (and the nodes/values it contains) is not part of the Data DOM. To add it to the Data DOM so that it gets submitted with the rest of the form’s data, you would have to append it to a node inside the root subform (the top-most subform in the Hierarchy palette). For example, if your root subform’s name was “form1″, you would do the following to add the <custom> node to the form’s data:

xfa.datasets.data.form1.nodes.append(c);

This can be very useful. In fact, this technique is used in Correspondence Management letter template scripts to flag a selection list’s default selection as having been processed. Since the data merged into the list to print the letter based on the template may not match the default selection in the list, the scripts generate a special node directly in the Data DOM to indicate whether the list’s data value should be processed instead of its default selection (i.e. no need for a hidden checkbox field for each list, keeping the form/PDF file size down).

The “Custom Node Example” section in my sample form demonstrates the above technique.

Loading Data Nodes

Another use for creating data nodes is they give you the ability to load existing XML in order to parse it without having to modify the Data DOM. If you create a new, orphaned (un-parented) data group node, you can use its loadXML() function to load an XML string into it, thereby giving you a handy XML node structure for parsing.

One example use of this would be in a form that retrieves various settings from a web service data connection where the structure of the returned data is determined by the input parameters (i.e. you have a single data connection which you can use to retrieve various data). You can return the XML data as a string and load it into a new data group node in order to parse-out the value you’re looking for without ever touching the Data DOM.

Another example would be an extension of my URL Request article. In this case, you could pass some XML data into your form via the URL request if your PDF form was available on a website. Warning: This is a not a secure method to pass data to your form.

Clicking the following link will load some movie data into the “Movies loadXML() Example” section of my sample form:

CreateLoadDataNodes.pdf?data=%3Cmovies%3E%3Cmovie%3E%3Ctitle%3ENacho%20Libre%3C%2Ftitle%3E%3Ccost%3E21.00%3C%2Fcost%3E%3CactorName%3EJack%20Black%3C%2FactorName%3E%3CcatName%3EComedy%3C%2FcatName%3E%3C%2Fmovie%3E%3Cmovie%3E%3Ctitle%3EMI%3AI%3C%2Ftitle%3E%3Ccost%3E20.00%3C%2Fcost%3E%3CactorName%3ETom%20Cruise%3C%2FactorName%3E%3CcatName%3EAction%3C%2FcatName%3E%3C%2Fmovie%3E%3C%2Fmovies%3E

Finally, my sample form also has a handy “URI Encoding Tool” section which you can use to encode various strings to include in a website address (as above).

Samples

Download Sample [pdf]

Minimum Sample Requirements: I created this sample using Designer 8.2 and Acrobat 9 however it should work fine back to Acrobat 7.0.5.

There is also a great example on creating data nodes on page 438 of the LiveCycle Designer ES Scripting Reference for Designer 8.2 — an excellent XFA form scripting reference.

The default setting is “Normal” which means that all new subforms you insert from the Object Library with have their “Object palette > Binding tab > Default Binding property” set to “Normal” which means implicit binding using the subform’s name.

Setting this to “None” will result in all new subforms having a default binding of “None” which means they don’t participate in data binding by default. Since subforms are often needed purely for form layout, I find it’s safer to use this setting because I know inserting new subforms will not affect any bindings I have already setup in my form. (While it’s true that unnamed subforms don’t participate in data binding, I always name my subforms for clarity and scripting purposes so setting the binding to “None” ensures they don’t mess with data binding unless I want them to.)

You could still use import bindings (set using the “Object palette > Bindings tab > Import/Export Bindings property”) but then you might have to hide most — or all — of those fields if you didn’t want to expose them. You would wait for the web service data connection to execute, then find the field that contains the piece of data you want and set it where it needs to go. This isn’t ideal, however, because Designer doesn’t expose any events, in the Script Editor, that would let you know that you now have data from the web service response in your form. Furthermore, having those extra fields around could add a lot of unnecessary weight (read: file size).

postExecute event

Unless you have studied the XML spec or deciphered its existence from the LC Designer ES Scripting Reference, you most likely don’t know about this event because Designer’s Script Editor palette doesn’t expose it. It’s purpose is to allow for post-processing of a web service response after a particular data connection is executed. The response data is temporarily stored in

xfa.datasets.connectionData.{DataConnectionName}

for the duration of the data connection’s PostExecute event.

Since it’s not exposed in the Script Editor, you have to go to the XML Source in order to set it on a form object — typically a subform. What follows is the XFA definition for the WebServiceDC data connection’s PostExecute event:

<event activity="postExecute" ref="$connectionSet.WebServiceDC">
    <script contentType="application/x-javascript">
        // do something...
    </script>
</event>

Note that I said this was the PostExecute event for the WebServiceDC data connection. The PostExecute event on its own — without a ref attribute that specifies the data connection to which it pertains — is of no use. In this case, the ref attribute specifies the WebServiceDC node inside the form’s connectionSet DOM (where web service data connections are defined). (Normally, the ref attribute has a value of “$”, which means “this”, since the event usually pertains to the form object on which it is defined.)

If you combine this with the ability to get web service response data without merging it into the form (either by not checking the “Object palette > Execute tab > Re-merge Form Data property” of the execute button for the data connection or you call xfa.connectionSet.{DataConnectionName}.execute(false)), you can essentially call a web service, get data back and do whatever you like with it.

Sample Form

To demonstrate how this works, I’ve created a sample form that has two web service data connections. It may take some time to open in Designer depending on how fast Designer can download the WSDL files from the two web services.

The first one, EchoEmployee, submits data from the top 4 fields and, using the PostExecute event, adds an item for each piece of data received in the response inside the list box. The following screen shot shows a sample result:

The second one, ConvertTemperature, obtains the conversion of the specified temperature from the web service response and displays it in a message box.

Download Sample [pdf]

Sample Minimum Requirements: While I developed the sample using Designer 8.2 and Acrobat 9.1, I have set the compatibility level to Acrobat/Reader 7.0.5 since this should work back to that version however I have not tested the form with anything earlier than 8.2/9.1.

Pre-Processor Library Snippet

In an effort to ease the pain of having to edit the XML Source, I have created an Object Library Snippet (XFO) that you can use to easily plug into this functionality:

Library Snippet [xfo]

In order to use it, you will have to save it to your Object Library’s Custom snippet folder which, depending on whether you installed Designer on XP or Vista, will be in one of the following locations:

C:\Documents and Settings\{username}\Application Data\Adobe\Designer\{version}\EN\Objects\Custom

C:\Users\{username}\AppData\Roaming\Adobe\Designer\{version}\EN\Objects\Custom

Once inserted into your form, the snippet will look like this:

By default, it’s set to work with a web service data connection that is named “WebServiceDC”. When that data connection’s PostExecute event is fired, the script inside will find the response data and call the processResponse() function defined on a script object that is included in the snippet (which is essentially a subform). Finally, the subform hides itself when the form is initialized so you don’t have to worry about hiding it yourself.

Now all you have to do is put script in the processResponse() function using the Script Editor!

If you need to use a different data connection name, you’ll have to go to the XML Source and make two modifications, highlighted here:

The first modification is to the ref attribute of the <event> node that defines the PostExecute event and the second is in the script itself where it extracts the XML of the response.

Before we get started, you’ll need Designer 7.1 and Acrobat/Reader 7.0.5 at minimum to run through this tutorial. I will be using Designer 8.2 and Acrobat/Reader 9.0 to do the tutorial so it’s possible some of the UI may have changed slightly since the 7.1/7.05 versions.

Creating the Table

The first step is to drag a Table object from the Object Library palette’s Standard tab into your form. When you drop it, the Insert Table wizard appears. Set it to include 5 columns, 1 body row and header and footer rows:

Headers and Footers

Double-click on the first “Header” cell and set the text/caption to “#”. This will be the dynamic index column. Set the remaining headers as follows: “Item”, “Quantity”, “Cost”, “Total”.

In the footer, we only need two cells: One with a caption that reads, “Grant Total:”, and the other for the calculated grand total. To start, select the first 4 footer cells by Ctrl-Clicking each one:

Then, with the cells selected, click on the “Merge Table Cells” button in the Object palette (highlighted in yellow in the image below):

The 4 cells will merge into one and you can then double-click the text to change it to “Grand Total:”. While you’re editing the text, use the Paragraph palette to align it to the right.

We’re pretty much done with the header and footer row except for the grand total cell but we’ll come back to that after the body row has been defined.

Body Row

What we want for the body row is a text/read-only cell for the row number, a drop down list for selecting items, a numeric cell for the quantity, a numeric/read-only cell for the cost (which will be set depending on the selection in the item list) and a numeric/read-only cell for the calculated total (quantity * cost) for the row.

The first thing to do is to rename the “Row1″ body row to “Item” and set it to repeat for each data item by selecting Row1 from the Hierarchy palette and setting its “Object palette > Binding tab > Name property” to “Item”, its “Default Binding” property to “Normal” and checking its “Repeat Row for Each Data Item” property to enable it to repeat so that the table can expand.

Row Number Cell

While this may sound complex, it’s actually quite easy to achieve. Since the Item body row will repeat, it will have an index and the index will be zero-based. This means our row number is simply the index of the cell’s parent (Item body row) + 1.

Drop a text field from the Object palette onto the first cell in the Item row. This will change the cell’s type to a text field. Set its name to “ItemIndex” (not just “index” because it’ll cause conflicts with the Item row’s index property), its “Object palette > Binding tab > Default Binding property” to “None” (since we don’t need the index in the submitted data — it’s just for show, after all) and its “Object palette > Value tab > Type property” to “Calculated – Read-Only”.

Finally, using the Script Editor, set its Calculate event to the following JavaScript code:

(this.parent.index + 1) + ".";

If we preview the form at this point, we’ll see that the first and only Item row has a row number of “1.”:

Item Name and Cost Cells

The next cell is the item name. This will be a drop down list with a few items to choose from which have associated values that we’ll use to set the cost field depending on the selected item.

Drop a down down list from the Object Library onto the second cell in the Item row. Set its name to “ItemName” (not just “name” because it’ll cause conflicts with the Item row’s name property) and add some items to it using the Object palette’s Field tab. The following image shows that I’ve populated my list with 3 items:

An important thing to note here is that we did not associate values as costs to each item. It would’ve been convenient to store them like that however if we had, the item’s name would’ve shown-up as the cost in the submitted data which is not the intention. When data is submitted, we want the item’s name (e.g. “Helmet”) to show-up as the ItemName data.

With the ItemName cell defined, we need to setup the Cost cell so that we can set its value to the value associated with the selected item.

Drop a numeric field from the Object Library onto the 4th cell (the 3rd cell is for quantity) in the Item row. Set its name to “Cost”, its “Object Palette > Binding tab > Data Format property” to “Float”, its Value Type to “Read-Only” and its Display Pattern to “num{($zzzz9.99)}” (without the double-quotes).

Now set the following JavaScript code as the Change event for the ItemName drop down list:

switch (xfa.event.newText)
{
    case "Helmet":
        Cost.rawValue = 45.00;
        break;

    case "Pedals":
        Cost.rawValue = 150.00;
        break;

    case "Wheel":
        Cost.rawValue = 225.00;
        break;

    default:
        // unknown item
        Cost.rawValue = 0;
        break;
}

This simple script looks at the new selection in the ItemName list and sets the Cost field’s value accordingly.

At this point, we preview the form and choose “Pedals” as the item, the Cost cell will get a value of “150″ which will be displayed as “$150.00″ because of the display pattern we set on the Cost field earlier:

Quantity Cell

With the ItemName and Cost cells defined, we can now define the Quantity cell. This one is quite simple: Drop a numeric field onto the 3rd cell in the Item row. Set its name to “Quantity” and its default value to 1.

Total Cell

The last cell in the Item row is the one what will show the total for that Item which is “Quantity * Cost”. This is another easy one: Drop a numeric field onto the 5th cell in the Item row. Set its name to “Total”, its Default Binding to “None” (no need to store calculated values in the data), its Value Type to “Calculated – Read-Only”, its Display Pattern to “num{($zzzz9.99)}” (without the double-quotes) and its Calculate event to the following FormCalc code:

Quantity * Cost

That’s it! FormCalc is great for spreadsheet-like calculations and in FormCalc, the “rawValue” property is implied so you don’t need to specify it like in JavaScript.

At this point, previewing our form and choosing “Pedals” as the item shows a calculated total of “$150.00″ for that item:

Footer Grand Total Cell

Now that the Item body row is complete, we just have a couple of things left to do. First, we need to setup the Grand Total field in the footer row which will display the grand total of the order. This field will be a numeric/read-only field which will calculate the sum of all Total fields in all Item rows that exist. This may sound complicated but once again, FormCalc makes this easy-as-pie.

Drop a numeric field onto the 5th (or 2nd or last) cell in the footer row. Set its name to “GrandTotal”, its Default Binding to “None” (no need to store calculated values in the data), its Value Type to “Calculated – Read-Only”, its Display Pattern to “num{($zzzz9.99)}” (without the double-quotes) and its Calculate event to the following FormCalc code:

Sum(Item[*].Total)

You’re probably wondering what the “[*]” notation means. Put simply, it’s like a wildcard for the index of the Item row and it tells the Sum function to get the value of the Total field in all instances of the Item row and calculate their sum.

At this point, if we preview our form and choose “Pedals” as the item, the total and grand total values are automatically calculated:

Adding/Removing Items

Last but not least, we need a mechanism to add and remove items in the table. Since we had the Item row repeatable, this will be done using the Instance Manager associated with the Item row.

To start, place two buttons on the form and name them “Add” and “Remove”. Set their captions to “Add” and “Remove” as well.

Using the Script Editor palette, set the Add button’s Click event to the following JavaScript code:

Table1._Item.addInstance(0);

This script will add a new instance of the Item row to the table. Now set the Remove button’s Click event to the following JavaScript code:

if (Table1._Item.count > 1)
    Table1._Item.removeInstance(Table1._Item.count - 1);

This script will first make sure that there are at least 2 rows (since the minimum row count is 1) and if so, will remove the last row that was added to the table. Note the use of the underscore prefix to access the Item row’s Instance Manager.

Previewing the form at this point will now allow you to add/remove rows and you’ll see that the totals are all being calculated automatically as you choose items and set quantities:

Sample Form

Here is the sample form for the tutorial. It’s the solution so try not to look at it until you’ve run through the tutorial on your own…

Download Sample [pdf]

Sample Minimum Requirements: Designer 7.1/Acrobat 7.0.5

Sample Form with Page Totals

Reader Sandeep Goli asked an interesting question: How would one show a page total?

This can be done by adding first allowing the table’s content to break across pages by checking the “Object palette > Table tab > ‘Allow Page Breaks within Content’ property”. The next step is to add another footer row to the table, located prior to the existing “FooterRow” row object (select the FooterRow row, duplicate it, rename it to “PageFooter”, rename the field inside to “PageTotal” and drag it up above the FooterRow object in the Hierarchy palette), and set it up to be included on subsequent pages as well as a the final page (rather than just the final page) using the “Object palette > Pagination tab > ‘Include Footer Row in Subsequent Pages’ and ‘Include Footer Row in Final Page’ properties”. This will cause the footer row to appear at the bottom of all pages, including the last page, as the table breaks across pages.

The final step in making this work is to set script in the new footer row’s Layout:Ready event. (If you duplicated the FooterRow, make sure you remove its Calculate script.) In this event, you can use APIs from the Layout Model which will let you determine the set of table “Item” rows that are on a given page — that being the page on which the PageTotal field was rendered:

xfa.layout.page(object)

will return the 1-based page number on which that object (field, subform, etc.) was rendered and

xfa.layout.pageContent(zeroBasedPageIndex, type, 0)

will return a list of all form objects of the specified type (a string, such as ’subform’, ‘field’, ‘draw’, etc.) on the specified 0-based page index.

The following script finds all Item rows on the same page as the rendered PageTotal field, sums their Total child field values and sets that number as the PageTotal’s value:

// get a list of all subforms rendered on the same page as this field
var pageSFList = xfa.layout.pageContent(xfa.layout.page(this) - 1, "subform", false);
var pageTotal = 0;
// for each subform named "Item", sum its "Total" field value
for (var i = 0; i < pageSFList.length; i++)
{
    var sf = pageSFList.item(i);
    if (sf.name == "Item")
        pageTotal += sf.Total.rawValue;
}
// set this field's value to the sum of all Item rows on this page
this.rawValue = pageTotal;

Download Sample [pdf]
Download Sample Data [xml]

Sample Minimum Requirements: Designer 8.0/Acrobat 8.0. This is due to bug fixes with table footer placement which are available only as of Acrobat 8.0.

Sample Form with Row Remove Button

Reader Susila asked an interesting question: How do you remove a specific row using a “remove” button in the row to be removed?

This is done simply by inserting a column to the left of the ItemIndex column in the table and setting the cell’s type to a button. The button’s Click event is then set to remove the row to which it belongs.

The trick lies in writing the script in such a way that it automatically relates to (i.e. removes) the row instance to which it belongs. This is achieved by retrieving the instance index of the row to which it belongs and using that as the parameter supplied to the Item row Instance Manager’s removeInstance([index]) method. The method expects a zero-based index and that’s what the index property gives you:

// JavaScript:
this.parent.parent._Item.removeInstance(this.parent.index);

The script above first accesses the button’s grand-parent (Table1). Then it gets the Instance Manager for the Item row and executes its removeInstance() method providing it with the index property value of its (the button’s) parent (Item row instance). By accessing parent objects, you ensure that you’re doing things with relation to the button that was clicked and, therefore, the row that contains the button.

Note that simply removing the row won’t necessarily update the ItemIndex field in other row instances that remain. If your form’s Target Version is set to Acrobat/Reader 7.0.5, you will have to explicitly tell the form to re-execute calculations. This issue was addressed in Acrobat 8.0+ so there’s no need to do this if your form targets a later version of Acrobat/Reader.

Download Sample [pdf]

Sample Minimum Requirements: Designer 7.1/Acrobat 7.0.5

Further Improvements

As I mentioned earlier, this is a simple dynamic table with a repeatable row. It demonstrates only the basics. You could enhance it further by including row shading options, validations, better formatting (font and paragraph), smarter add/remove buttons (e.g. put the remove button on the Item row in order to delete that specific row instead of always deleting from the end), put an insert button on the Item row in order to insert new items instead of always appending to the end of the list, etc.

For an advance sample, you should check-out the “Dynamic Interactive Purchase Order” sample that ships with Designer. Depending on how Designer was installed (either with Acrobat, with LiveCycle or standalone) and whether it was on Win 2k, XP or Vista, you should be able to find it in one of the following folders:

C:\Program Files\Adobe\LiveCycle ES\Workbench ES\Designer ES\{version}\EN\Samples\Forms\Purchase Order\Dynamic Interactive\Forms

C:\Program Files\Adobe\LiveCycle Designer ES\{version}\EN\Samples\Forms\Purchase Order\Dynamic Interactive\Forms

C:\Program Files\Adobe\Acrobat\Designer\{version}\EN\Samples\Forms\Purchase Order\Dynamic Interactive\Forms

(Note that in Vista, “Program Files” changes to “Program Files (x86)”.)

Updated Oct 2, 2009 — Added page totals sample.

Updated Oct 2, 2009 — Added row remove button sample.