Chapter 4, Exchanging Data Between an External Application
and a Basic XFA Form
XFA Specification
Creating, Updating, and Unloading a Basic XFA Data DOM
137
Updating the XML Data DOM for Changes Made to the XFA Data DOM
The XFA application may make edits to the XFA Data DOM during processing. These edits may include
insertions and deletions of nodes, moving nodes, and updating the content of nodes. The XFA Data DOM
is responsible for ensuring that all such edits are propagated to the XML Data DOM to ensure the XFA Data
DOM and the XML Data DOM stay synchronized. The XFA Data DOM detects and refuse to carry out edits
that would lead to the production of invalid XML during data unloading. For example, if the XFA
application attempts to create a data value with the same name as a sibling and both siblings have their
contains
properties set to
metadata
, the XFA Data DOM refuses to create the new data value on the
grounds that attributes of the same element must have unique names.
Updating the XFA Data DOM for Changes Made to the XML Data DOM
(Append Loading)
The XFA Data DOM provides a facility for loading data from an XML data document into an XFA Data DOM
that already contains nodes. This specification refers to such a load as an
append-load.
Append-loads are
not used in normal processing but may be employed by scripts.
When carrying out an append-load the data loader follows the same rules described elsewhere in this
specification, except that:
●
The start element for the load is determined at invocation time, without regard to
startNode
option
of the XFA Configuration DOM.
The new data is appended as a subtree, the root of which is the child of an existing node. The node to
which the new subtree is appended must be determined at invocation time.
●
The XFA Data DOM is responsible for propagating
nullType
properties into the XFA Form DOM. When the
the XFA Data DOM is asked to provide node information, it consults the node’s data description to
determine whether it provides null type information. If the node provides such information, the XFA Data
DOM provides it as the new data value node’s
nullType
property. Otherwise the
nullType
property is
inherited from the node’s parent. The highest-level data group cannot inherit, so if its
nullType
is not
specified, it defaults to the value
empty
.
Unload Processing
The data unloader provides a facility for creating or updating an XML data document that represents the
XML Data DOM.
When invoked, the data unloader produces an XML data document which reflects the contents of the XML
Data DOM, as of the moment at which the data unloader was invoked.
When unloading the XML Data DOM, the XML data document produced by the data unloader is such that
insofar as possible
the data can make a round-trip back to the XFA Data DOM. Round-tripping means that
when the new document is subsequently loaded into an empty XFA Data DOM using all the same data
loader configuration options, the resulting XFA Data DOM is indistinguishable from the original XFA Data
DOM at the moment the data unloader was invoked. When the default data mapping rules described in
this chapter are used round-tripping is always supported. Round-tripping is also supported for most, but
not all, extended data mapping rules.
The data unloader encodes characters using XML character references when necessary to conform to XML.
In lieu of character references it may use the special strings defined by the XML Specification [XML] which
includes
"<"
for
"<"
(less-than sign),
">"
for
">"
(greater-than sign), and
"&"
for
"&"