Chapter 4, Exchanging Data Between an External Application
and a Basic XFA Form
XFA Specification
Basic Data Binding to Produce the XFA Form DOM
182
values can be taken from the XFA Data DOM or they can be obtained via connections to web services. This
process is controlled by two properties,
setProperty
and
bindItems
.
The setProperty property
This property is used to explicitly copy a particular data value node or a value returned by a web service to
a property of the containing field, draw, exclusion group, or subform. This can be used to make captions,
assists, and other portions of the form data-driven even though they are not modifiable through the user
interface.
A field, draw, exclusion group, or subform may have any number of
setProperty
children. Each
setProperty
child affects one property of its parent.
The
setProperty
element takes a
ref
attribute, plus an optional
connection
attribute, which
together define the source of the data to be copied. A mandatory
target
attribute identifies the property
to copy into.
The
ref
attribute takes as its value a SOM expression with one special restriction: the expression may not
use the ".." syntax. The SOM expression may be a relative expression. When there is no
connect
attribute
the expression is evaluated in the context of its parent (which is its container). When there is a
connect
attribute the 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 target must be a property (or subproperty) of the parent object. It cannot be a property of an object
contained by the parent. For example, within a subform the target may be specified as
assist.tooltip
(a subproperty of the subform itself) but it may not be specified as
#field.rotate
(a property of a field
object contained within the subform). You have to put the
setProperty
on the object to which the
target belongs. For example, the following template fragment copies data from the XFA Data DOM into
several properties of a subform and other data into properties of a field contained within the subform.
<subform name="Customer" ...>
<setProperty ref="$data.Tips.Customers" target="assist.toolTip"/>
<setProperty ref="$data.Style.Background" target="fill.color.value"/>
<field name="LastName" ...>
<setProperty ref="$data.Style.NameFont" target="font.typeface"/>
<setProperty ref="$data.Style.NameSize" target="font.size"/>
</field>
</subform>
The target can be almost any property of the containing object. The following restrictions apply.
●
●
It is not legal for the target to be the
setProperty
property itself or any of its subproperties.
It is not legal for the target to be a
bindItems
property or any of its children. Both
setProperty
and
bindItems
are processed during a single phase of the data merge process and their respective order
of evaluation is not guaranteed.
Some targets are legal but not recommended.
●
It is legal for the target to be the
relevant
,
use
or
usehref
property but it is not recommended.
These properties are processed early and changing them afterward has no effect.
It is legal for the target to be a bind-related property (such as the
name
property or any
bind
or
occur
subproperties) but it is not recommended. Specifying a bind-related property as the target is unlikely
to yield a useful result. Processing of
setProperty
is done near the end of the merge operation when
●