Chapter 4, Exchanging Data Between an External Application
and a Basic XFA Form
XFA Specification
Basic Data Binding to Produce the XFA Form DOM
183
the bind-related properties have already had their effects. Changing them with
setProperty
has no
effect on the current merge operation. It may however affect subsequent incremental merge
operations.
●
It is legal for the target to be the
value
property of the parent field or exclusion group, but it is not
recommended. It is better to do an explicit data reference by setting the parent’s
bind.match
property to
dataRef
and the parent’s
ref
attribute to the target instead. By contrast when the parent
is a
draw
object there is no way to specify an explicit data reference and it is proper and expected to
specify its
value
property as the target of a
setProperty
.
Note that
setProperty
processing is a templating process, not a binding process. Whenever a merge is
performed a snapshot of the specified data is copied into the specified properties. Subsequent updates to
the data do not propagate into the target or vice-versa. This is appropriate because the targets of
setProperty
are things that the user does not normally have the ability to change interactively.
Caution:
Careless use of
setProperty
can create security vulnerabilities. It is up to the form creator to
ensure that security is not compromised.
The bindItems property
This property is used to load the
items
property of a field from a set of data value nodes or from a set of
values returned by a web service. If the
items
property already exists and is non-empty the old contents
of the
items
property are lost.
It is always legal for a field to have a
bindItems
property, but as with
items
the property is ignored
unless the field has a suitable user interface. Suitable user interfaces include choice lists, check boxes, and
radio buttons. Note that when
bindItems
refers to a web service but the user interface is unsuitable the
web service is
not
accessed, so there are no side-effects.
The
bindItems
element takes a
ref
attribute, plus an optional
connection
attribute, which together
identify a set of data nodes. Each member of the set is used to create an item for the list. A mandatory
valueRef
attribute identifies a particular data value within each member of the set. These values are
used to generate the actual value strings for the items. In addition an optional
labelRef
attribute
identifies a data value within each member of the set that is used to generate label strings for the items. If
there is no
labelRef
attribute then the value strings are also used as labels.
Note:
Unlike
setProperty
, whenever possible
bindItems
does not merely use the data as a template.
Instead it makes a true binding. Any subsequent change in the bound data automatically
propagates into the
items
property. This is an exception to the usual XFA practice for
non-interactive properties. The exception was made to simplify interoperation with forms written in
XForms and using an
itemset
element. However when the
connection
property is non-empty
binding cannot be done because connection data is transient. In this case the XFA processor
performs a simple templating (copying) operation.
The
ref
attribute takes as its value a SOM expression with one special restriction: the expression may not
use the ".." syntax. When there is no
connect
attribute this expression is evaluated in the context of the
data node bound to the containing field object in the XFA Form DOM. When there is a
connect
attribute
this expression is evaluated in the context of the the nearest ancestor that asserts a fully-qualified XFA
SOM expression as its value of
ref
for the same connection. For example if a subform has a
ref
attribute
with a value of
!connectionData.queryDatabase.body
then its child field could use the relative
expression
queryID
as a synonym for
!connectionData.queryDatabase.body.queryID
. In all
other ways the value of this property is a normal XFA SOM expression.
The values of
valueRef
and
labelRef
must be SOM expressions. These expressions may contain ".." if
desired. They are evaluated in the context of the data node to which the
ref
expression points.