Chapter 4, Exchanging Data Between an External Application
and a Basic XFA Form
XFA Specification
Creating, Updating, and Unloading a Basic XFA Data DOM
115
specifications when a tree is drawn pictorially sibling nodes are shown in order by age, with the oldest at
the left and the youngest at the right. In the case of the XFA Data DOM the result of this ordering is that a
tree walk that goes in depth-first order, and left-to-right at any level, traverses the data in the same order
as it was present in the original XML data document.
The objects in the XFA Data DOM and their properties are exposed via the XFA Data DOM interfaces. Every
object in the XFA Data DOM has the following exposed property:
Property
name
Description
A string of any length (including zero-length, that is empty) which is a non-unique
identifier for the object. This corresponds to the local part of either the element type
or the attribute name in the XML data document.
In addition, each object created by the data loader has an internal pointer to the node in the XML Data
DOM with which it is peered. Furthermore, some objects have additional properties appropriate to their
object types, as described below.
For example, consider the following fragment of XML:
<abc:tree xmlns:abc="http://www.example.org/orchard/">apple</abc:tree>
When loaded into the XFA Data DOM using default mapping rules, the
dataValue
node representing this
data has a property called
name
with a value of
tree
.
After the XFA Data DOM has been loaded the XFA application may update it. Updates may include adding,
deleting, moving, and changing the properties of nodes. These changes are passed through to the XML
Data DOM by the XFA Data DOM so that the two data DOMs stay synchronized. When the data unloader
runs it creates the new XML data document based upon the contents of the XML Data DOM, as updated by
the application.
Note that the exposed properties may be set by an XFA application to any Unicode string, including the
empty string
""
. This allows XFA applications to construct arbitrary data structures. However the XML 1.0
Specification [XML] imposes additional restrictions upon element types, namespace prefixes, and URIs.
Hence when the XFA Data DOM is unloaded to an XML data document the result may be malformed XML.
It is up to the application to ensure, if desired, that the restrictions of XML with regard to element types,
namespace prefixes and URIs are respected.
The XFA Data DOM is part of a larger tree that holds all exposed XFA nodes. The single large tree makes it
possible to refer to XFA nodes using a unified format known as a Scripting Object Model (SOM) expression.
The grammar of SOM expressions is described in
“Scripting Object Model” on page 81.
Briefly, an
expression consists of a sequence of node names separated by periods (
"."
characters). Starting from
some point in the XFA tree, each name identifies which child of the current node to descend to. The Data
DOM descends from a node named
data
which is a child of
datasets
, which is a child of
xfa
, which is
the root. The XML data document does not supply the
xfa
,
datasets
, or
data
nodes; instead the data
loader creates them automatically and makes the node mapped to the outermost element of the data the
child of
data
. Consider the following XML data document:
<book>
<ISBN>15536455</ISBN>
<title>Introduction to XML</title>
</book>
When loaded into the XFA Data DOM, the node representing the
book
element would be referenced by
the SOM expression "xfa.datasets.data.book". The
ISBN
element would be referenced by
"xfa.datasets.data.book.ISBN" and the
title
element by "xfa.datasets.data.book.title".