XFA Specification
Chapter 3, Object Models in XFA
Scripting Object Model
99
Obtaining the value of an expression
ECMAScript, unlike FormCalc, is oriented towards objects rather than strings. It does not automatically try
to resolve a node reference into a value. Hence to make reference to the value property of a field or other
object in ECMAScript you must explicitly invoke the
value
property of the node. For example, to
reference the value of the
Tax
field in the receipt example on
page 96,
you must use the SOM expression
$data.Receipt.Detail.Tax.value
or
$form...Receipt.Detail.Tax.rawValue
In contrast, when FormCalc evaluates the expression
$data.Receipt.Detail.Tax
, it returns the value,
without having to be told the value is desired.
SOM expressions that use special characters
ECMAScript is rather restrictive in its handling of object names. In particular, expressions for object names
may not include any of
"["
,
"]"
,
"*"
, and
".."
. Consequently many valid SOM expressions cannot be
used directly in ECMAScript expressions. For example, the following expressions result in an error when
interpreted by ECMAScript:
$data..Total_Price // ECMAScript does not support ".."
$data.Receipt.Detail.Total_Price[0] // ECMAScript does not support "[" or "]".
To address this limitation, ECMAScript scripts must pass such SOM expressions as strings to a
resolveNode()
method.
resolveNode()
returns the objected specified in the SOM expression.
Every node in any of the XFA DOMs has a
resolveNode()
method. Furthermore, for the types of SOM
expressions described under
“Basic Object References” on page 85,
the
resolveNode()
method of any
node can be used. However for the advanced expressions described in
“Relative References” on page 100
you must use the methods of the
$form
object or the
this
object. It is recommended to use the methods
of
$form
at all times.
For example, the following line of code is valid:
$data.Receipt.Tax.value = 11.34;
// this is valid ECMAScript
Whereas the following line of code is
not
valid because the square brackets are not allowed:
$data.Receipt.Detail[1].Units = 3;
// this is NOT valid ECMAScript
Instead you must pass the SOM expression to
resolveNode()
:
// A valid ECMAScript expression
$form.resolveNode("$data.Receipt.Detail[1].Units").value = 3;
Sometimes an operation expects or requires a list of objects, rather than a single object. For these cases
the script must use the
resolveNodes()
method instead of the
resolveNode()
method. The
resolveNodes()
method returns a list of zero or more objects. For example, the following expression
creates a variable containing a list of zero or more
dataValues
corresponding to
Units
elements of
receipt detail records.
// A valid ECMAScript expression
var aList = $form.resolveNodes("$data.Receipt.Detail[*].Units");
As with the
resolveNode()
method, there is a
resolveNodes()
method on every node in any XFA
SOM, but the methods on different nodes do not all handle every type of SOM expression. It is
recommended to use
$form.resolveNodes()
at all times.