Chapter 4, Exchanging Data Between an External Application
and a Basic XFA Form
XFA Specification
Creating, Updating, and Unloading a Basic XFA Data DOM
119
<title>Introduction to XML</title>
<desc>Basic primer on <keyword>XML</keyword> technology.</desc>
</book>
In the above example the element
book
is represented in the XFA Data DOM by a
dataGroup
node with a
name
property of
book
. The
isRecord
property may have a value of true or false depending on the
context within the XML data document and depending on the configuration option described in
“The
record Element” on page 386.
If the above text was the entire XML data document and default mapping
rules were used,
isRecord
would be true.
Relationship Between the XFA Data DOM and the XML Data DOM
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.
Some data loader options cause the data loader to load only a subset of data from the XML Data DOM into
the XFA Data DOM. The result is that the ignored data is still in the XML Data DOM but is not accessible
through the XFA Data DOM. Consequently the XFA application is unable to alter the ignored data. When
the data unloader writes out a new XML data document, since the ignored data has been kept untouched
in the XML Data DOM, it is written out in the new document without significant changes. This applies by
default to attributes. It also applies to data which is always excluded from the document range as
described in
“Document Range” on page 121.
It applies to data which is excluded using the extended
mapping rules described in
“The excludeNS Element” on page 370, “The startNode Element” on page 394,
and
“The range Element” on page 385.
Finally, it applies to all extended mapping rules invoked by the
ignore
keyword, as described in
“The attributes Element” on page 366, “The presence Element” on
page 383,
and
“The presence Element” on page 383.
The
name
property of a node in the XFA Data DOM may be altered by the application or by the data loader,
but doing so does not affect the
name
property of the peered node in the XML Data DOM. Consequently
the node in the XFA Data DOM is accessible to scripts under its new name, but when the peered node is
written out from the XML Data DOM to a new XML data document it retains its original name. This applies
to nodes renamed via the data-loading options described in
“The nameAttr Element” on page 381
and
“The rename Element” on page 392.
On the other hand when the application creates a new node in the
XFA Data DOM, there is no existing peer in the XML Data DOM, so one is created and given the same
name
property.
The remaining data loader options cause the data loader to alter the content of the XML Data DOM along
with the XFA Data DOM. When the data is unloaded the alteration is reflected in the new XML data
document. This applies to extended mapping rules described in
“XSLT Preprocessing” on page 399, “The
whitespace Element” on page 395
“XSLT Postprocessing” on page 400.
It also applies to the rules
invoked via the
remove
,
dissolve
or
dissolveStructure
keywords as described in“The
Element” on page 383,
and
“The ifEmpty Element” on page 377.