10
Scripting
This chapter describes the role of scripting objects in templates. It describes how scripting langauges are
selected and how their environments must be set up. It also describes exception handling
Purpose of Scripting
It is important to understand that scripting is optional. The template author can take advantage of
scripting to provide a richer user experience, but all of the features described so far operate without the
use of scripts. Script creation is part of the template authoring process.
XFA supports scripting in ECMAScript [ECMAScript], but it also defines its own script language, FormCalc,
which is described in
“FormCalc Specification” on page 801.
Often, the scripts attached to a form are
similar to those attached to a spread-sheet. FormCalc has been designed as an expression-oriented
language, with simple syntax for dealing with groups of values in aggregate operations.
Both ECMAScript and FormCalc expose the same object model. Scripting almost always works with data
values, so these are easily referenced (though you can script against any XFA DOM element present).
Indeed, XFA defines a complete Scripting Object Model (XFA-SOM). A key feature of XFA-SOM is that it
manages relative references. For example, when defining an invoice detail line the creator of a form sets up
fields named unitPrice, quantity and amount. The calculation for amount is simply unitPrice*quantity. The
form contains multiple detail records using the same field names, but XFA-SOM automatically manages
the scope to select the unitPrice and quantity data that corresponds to the same detail record. It can do
this in two ways: by selecting fields that are in the same or related subforms; or by selecting from among
multiple fields with the same name within the same subform. For more information about XFA-SOM see
“About SOM Expressions” on page 82.
Because of the declarative nature of XFA-Template, the largest use of scripting is for field calculations. A
field with such a script typically is protected against data entry, and instead gets its value from an
expression involving other fields. A field's calculation automatically fires whenever any field on which it
depends changes (those fields may, in turn, also have calculated values dependent on other fields, and so
on).
See “Calculations” on page 297.
Similar to calculation, a field can have a validation script applied that validates the field's value, possibly
against built-in rules, other field values or database look-ups. Validations typically fire before significant
user-initiated events (e.g., saving the data).
See “Validations” on page 299.
Finally, scripts can be assigned to events, for example,
onEnter
,
onExit
,
onClick
, and so on.
See
“Events” on page 304.
321