Chapter 4, Exchanging Data Between an External Application
and a Basic XFA Form
XFA Specification
Basic Data Binding to Produce the XFA Form DOM
184
For example, the author of a form wishes to populate a choicelist with a set of credit cards. The set of credit
cards is to be taken from the data file. The data contains the following structure.
<ccs>
<cc uiname="Mastercard" token="MC"/>
<cc uiname="American Express" token="AMEX"/>
...
</ccs>
The author accomplishes his goal using the following template fragment.
<field ...>
<bindItems ref="$data.ccs.cc[*]" labelRef="uiname" valueRef="token"/>
<ui>
<choiceList/>
</ui>
</field>
Calculations and Validations (Step 6)
The last thing that the data binding process does for any given record is to trigger the execution of certain
scripts.
Fields in the template may have calculation and validation scripts attached to them. A calculation script
returns a value which becomes the new value for the field. A validation script returns a status value which,
if false, causes actions to be taken such as displaying an error message. Calculation and validation scripts
must not make alterations to the structure of any of the DOMs, such as adding, deleting, or moving nodes.
In addition validation scripts must not alter any values. Calculation and validation scripts may be triggered
under various other circumstances, not only upon completion of data binding.
Note that calculations are performed even for fields that were supplied with data in the course of data
binding. The calculation may thereby update the supplied value. Similarly validations are applied even to
values that are supplied by the template to an empty merge as default values. Hence a validation may
declare a failure or warning in response to a default value.
For more information about these and other scripts and events see the chapter
“Automation Objects” on
page 291.
Form Ready Event (Step 7)
After all records have been successfully processed the data binding process triggers the
ready
event on
the
$form
object. Scripts attached to this event can execute confident in the knowledge that data binding
has successfully concluded and all data has validated.
For more information about events see
“Events” on page 304.
Remerge and Incremental Merge (Step 8)
It is possible for scripts to modify the Data DOM after a merge operation has already taken place. Deleting
a data object may leave a form object unbound but otherwise does not alter the Form DOM. Inserting a
data object does not in itself alter the Form DOM at all; the newly inserted data object is unbound.
However it may be desired to update the bindings between data and form objects. There are two
approaches to doing this, known as
remerge
and
incremental merge.