The time has come for me to focus my extra energy on other goals and projects at Adobe and at home.

I have thoroughly enjoyed helping the XFA community for these past 4.5 years. All of the content on this blog was a direct result of your questions and I learned a great deal about Adobe’s XFA technology and its LiveCycle Enterprise Suite along the way. Thank you!

I leave you now with a final “form to end all forms” (in my mind, anyway): A version of the classic Tank Wars game implemented entirely in XFA + JavaScript.

Why do this, you wonder? Well, it was a good challenge, you couldn’t embed Flash in an XFA form back then and I wanted to do something that would really put LiveCycle Designer’s Script Editor through its usability paces.

Comments are now closed on all posts and pages except for this one and the XFA Tank Wars page which will close on December 31, 2010. I will continue to host this blog for your reference and bookmarks however I cannot guarantee it will be available forever.

Good luck on all your present and future form development projects.

Stefan

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"

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.)

What’s more, you can now find all of the ES2 Developer and Programmer documentation all in a single place just like all ES2 documentation (which includes the Dev and Prog docs from the former link). Great sites to bookmark and nice to finally have it all in one spot!

This all comes to you due to the recent LiveCycle Developer Center site refresh in conjunction with the recent release of LiveCycle ES2. Check it out!

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.

For example, say you have a simple form with a text field and a numeric field. The following statement will output the form’s data to the JavaScript Console in Acrobat:

console.println(xfa.datasets.data.saveXML());

The result, however, isn’t very readable:

<?xml version="1.0" encoding="UTF-8"?>
<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
><form1
><TextField1
>asdf</TextField1
><NumericField1
>1234</NumericField1
></form1
></xfa:data
>

Though I had been using saveXML() for quite some time, I hadn’t realized that it actually takes an optional parameter, a string with a value of “pretty”, that results in much nicer output.

console.println(xfa.datasets.data.saveXML('pretty'));

results in the following pretty/readable output:

<?xml version="1.0" encoding="UTF-8"?>
<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
   <form1>
      <TextField1>asdf</TextField1>
      <NumericField1>1234</NumericField1>
   </form1>
</xfa:data>