XFA Specification
Chapter 3, Object Models in XFA
Scripting Object Model
100
Using SOM Expressions in Bind References
An XFA SOM expression used as a bind reference is not in a scripting context, so it is not FormCalc or any
other scripting language. It is evaluated as a raw SOM expression. Any valid SOM expression constructed
according to the rules in this section (“Basic
can be used, however it must
always resolve to a single node of the appropriate type in the Data DOM. See
“Basic Data Binding to
Produce the XFA Form DOM” on page 154
Relative References
Whenever a script is activated it resides somewhere in the Form DOM. It originated in the Template DOM,
from which it was copied, but the copy in the Template DOM is never activated. Scripts do not reside in any
other DOMs. The node containing the script provides a context for the script. Scripts can employ SOM
expressions that reference nodes in the Form DOM relative to the node which contains the script. This
facility is extended with scoping rules which allow the relative reference to succeed even if it does not
exactly match the hierarchy of nodes in the Form DOM.
When data is merged with a template to create the Form DOM, some parts of the Template DOM
(including scripts) may be replicated more than once in the Form DOM. This allows a template to
dynamically adapt to the number and arrangement of records in the data. But this imposes upon scripting
the requirement that a script be able to work unchanged even when it is not in the same position in the
Form DOM that it was originally in the Template DOM. In other words, it must be possible to write scripts
that are relocatable. This can be accomplished using relative references and scoping.
The Current Container
Within the Form DOM there is a concept of a container. A container is an object that holds data or values.
Simple containers include field (interactive element on the form), draw (static) and contentArea (layout
region) elements. All other containers are capable of containing other containers as well as other
non-container objects. For more information about containers see
“Container Elements” on page 26.
The following objects can directly contain scripts:
●
●
●
●
field
exclGroup
subform
subformSet
In XFA SOM, the default current object for a script is the container that is the most immediate ancestor of
the script element. Most often such containers are field objects. In addition exclGroup, subform, and
subformSet objects can be the current object for scripts. The other containers cannot contain scripts
except inside contained field, exclGroup, subform, or subformSet objects.
The current object can be explicitly referenced using the dollar sign,
"$"
. This serves the same purpose as
this
in ECMAScript or
Me
in VBScript. In the following example of an XFA SOM expression embedded in a
script, the current object is the
Receipt
subform, the most immediate ancestor that is a container. This
script uses
"$"
to make a relative reference to the value of the
Tax
field, highlighted in bold.
<xdp …>
<template …>
<subform name="Receipt"…>
<field name="Tax"…> … </field>
…