XFA Specification
Chapter 9, Automation Objects
Calculations
298
Activation
This section describes the stimuli that cause the processing application to activate
calculate
elements.
Many of those stimuli also trigger the processing application to activate the other automation elements,
event
and
validate
. In cases where a single stimuli triggers multiple automation elements, the order of
activation is as follows: (1)
event
elements, (2)
calculate
elements, and (3)
validate
elements. (See
“Order of Precedence for Automation Objects Activated by the Same Trigger” on page 316.)
The processing application activates
calculate
elements when the value of the field, subform, or
exclusion group changes. Those values can change as a result of any of the following actions:
●
Data-binding.
As a final phase of data-binding, the processing application activates all
calculate
elements. It also re-activates
calculate
elements, as described in
Cascading value changes.
During the initial data-binding (data merge), the only data present in the Form DOM are default values
supplied by the Template DOM. During subsequent data-bindings (data re-merges), the values from
calculation scripts reflect the current data in the Data DOM and, where needed, default field values
from the Template DOM.
●
Interactive data entry.
A processing application allows users to enter data, without repeating the
data-binding process. Such entries simultaneously change values in the form and Data DOM. When a
user enters data, the processing application activates
calculate
elements that are dependent on
that container’s value. It may also re-activate other
calculate
elements, as described in
Cascading
Cascading value changes.
In some cases, multiple
calculate
elements may depend on one another,
in a
cascading
relationship. In other words, a change to the value of one
field
can influence the
calculated values of many others. In such cascading calculations, the processing application
re-activates
calculate
elements, as the values on which they depend change.
References to named script objects are not considered in determining dependencies. That is, if a
calculation includes a reference to a property or method of a named script object and the properties of
that object are changed by another calculation, the calculation under consideration is not re-activated
(“Variables
If the calculation of an element references its own value, either directly or indirectly, a circular reference
is said to exist. The following points address responsibilities related to circular references:
❚
●
XFA form creators.
It is the responsibility of XFA form creators to prevent circular references from
being specified in calculate scripts. Such checks should be done concurrently with form creation,
rather than through the addition of validation scripts.
Processing application.
It is recommended that the processing application provide some means of
identifying and terminating the execution of seemingly infinite loops.
❚
Note:
Scripts do not manage calculation dependencies; rather, the processing application is
responsible for managing calculation dependency on behalf of the form. (See