My first tutorial on XML schemas explained how to connect your form to a schema however it did not show some of the Data View palette’s special features with respect to metadata in XML schemas.

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.

---

Posted by Stefan Cameron on August 28th, 2009
Filed under Data Binding,Designer,Scripting,Tutorials,XFA
Both comments and pings are currently closed.

---