xfa.host.openList(@object)
xfa.host.openList(@string) -- deprecated since XFA 2.6

where @object is a reference to the drop down list field and @string is the SOM expression of the drop down list field.

xfa.host.openList(myDropDownList); // set focus/show the drop list

The second form of the API has been deprecated since XFA 2.6 which means that since Designer 8.1, it is preferred to use the first form which takes a reference to the field rather than its SOM expression.

If you’re using Designer 8.0 or earlier, you can get the SOM expression of any field by using its somExpression property:

xfa.host.openList(ddlInDesigner71.somExpression)

This works in both JavaScript and FormCalc with the same syntax.

Now if only there was a way to programmatically show the drop calendar of a date/time field…

As he puts it, there are limitations, the biggest ones of them being, in my opinion, the inability to debug script objects and the inability to retain breakpoints between debugging sessions. Nonetheless, this tool can give you way more insight than the good old “JavaScript Console + saveXML(‘pretty’)” combination can in certain cases, and it does it in a nice tree to boot!

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!

In days of yore, if you wanted to disable all fields and exclusion groups (for the sake of brevity, I’ll refer to these collectively as “fields” in this article) in a particular section of your form, you would’ve had to write a script that recursively drilled down into all children of that section looking for fields to disable. This is because the access attribute only applied to fields.

With this change, assuming the section in question is contained within a subform, you can now easily disable all fields contained within it simply by setting the subform‘s access attribute to “readOnly”!

The following table describes the four levels of restrictiveness (in XFA 2.8, from the highest level to the lowest) that can be imposed on fields using the access attribute, either directly on a field or by a parent subform:

When a subform imposes restrictions on the fields it contains (meaning all fields within any level of nesting, not just immediate children), the inheritance on child fields and subforms follows that of the most restrictive parent imposition. For example, if a subform imposes access=”protected” and a child subform has access=”readOnly”, all of the inner subform’s children, including the inner subform itself, will effectively have a “protected” access level.

The explanations of the various access types in the table above are summarized. “Access Restrictions” on page 48 of the XFA 2.8 specification has more precise, albeit more technical, explanations of each level of restrictiveness.

Setting Access by Script

Setting the access attribute of a field or subform by script is simple, both in JavaScript and FormCalc:

// set access level to read-only:
FormObject.access = "readOnly";

If you wanted to disable all fields in the entire form with a single line of script, you would simply set the root subform’s access attribute to something other than “open”, as appropriate:

// if the root subform's name is "form1":
xfa.form.form1.access = "nonInteractive"

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.

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.