Chapter 4, Exchanging Data Between an External Application
and a Basic XFA Form
XFA Specification
Basic Data Binding to Produce the XFA Form DOM
158
The match property
This property controls the role played the by parent object in a data binding operation. It must be set to
one of the following values:
once
The node representing the parent object will bind to a node in the XFA Data DOM in accordance
with the standard matching rules. This is the default value.
none
The node representing the parent object will not bind to any node in the XFA Data DOM. This is
normally used for nodes that are
transient,
that is, that will not be written out if the DOM is saved
to a file.
global
This is only allowed if the parent object is a field. It signifies that field is capable of binding to
global data. If the normal matching rules fail to provide a match for it, the data-binding process
will look outside the current record for global data to bind to the field. Note that, whereas a
regular data value node can only bind to one field, a single global data value node can bind to
many fields.
The current record is always a subtree within the Data DOM. Global data is any data value that is
not inside any record but that is at least as high in the hierarchy as a record. See
“Creating,
for more information.
dataRef
The parent object will bind to the node in the XFA Data DOM specified by the accompanying
ref
property.
The picture property
This property specifies the format of data in the Data DOM. When data is copied into the Form DOM the
bind picture is used to convert it into
canonical format.
Canonical format for numbers has a
"."
as a
decimal point and no thousands separator. Canonical format for dates is a subset of [ISO
Converting
data to canonical format makes it possible to manipulate the data using scripts and applications that are
unaware of the local format. When the data is saved to a file, the bind picture is used in the reverse
direction to convert the data from canonical format into local format. For more information about
localization and canonicalization, see
“Localization and Canonicalization” on page 140
When a script reads the
value
property of a form node, the value that it receives is localized using the
bind picture. When it assigns to the
value
property of a form node, the value it supplies is canonicalized
using the bind picture. In effect the script is treated as though it is a user who wishes to deal in localized
formats. However, unlike users, scripts can also read from and assign directly to the canonical format using
the
rawValue
property of the form node. In addition scripts can access the original uncanonicalized data,
as supplied in the XML data document, using the
value
property of the associated data node.
Note that a bind picture may be supplied using the
picture
child of the
transform
element in the XFA
configuration document. A conflict would arise if two bind pictures were supplied for the same form
node, one in the template and one in the configuration. It is up to the form creator to ensure that this does
not happen.
The ref property
This property is used to explicitly bind a field to a particular data value node, overriding the automatic
data-binding process. This property is used only when the accompanying
match
property has a value of