XFA Specification
Chapter 6, Template Features for Designing Forms with Repeating Sections
Forms with Repeated Fields or Subforms
209
Nested subforms and subform sets can have multiple occurrences at each level of nesting. The result is to
compound the occurrences. For example, suppose a template has a subform
Member
which is set to occur
three times, and
Member
contains a subform
Name
which is set to occur twice. This is exactly equivalent to
a template containing three subforms called
Member
, each of which contains two subforms called
Name
.
Note that fields do not have
occur
properties, hence can not automatically repeat. It is common to wrap a
field in a subform simply to provide a way to associate an
occur
property indirectly with the field. In such
cases it may be convenient to leave the subform nameless so it does not alter the SOM expression used to
refer to the field in scripts. Alternatively, setting its
scope
property to
none
causes it to appear in SOM
expressions but to be transparent to the data binding process so it has no effect on the data hierarchy.
The
occur
property is more capabilities that are not depicted here. It can be used to make the form adapt
itself to the data, repeating subforms as necessary. See the chapter
“Dynamic Forms” on page 259
description of this capability.
Record Mode
XFA processors can operate in two modes, record mode and non-record mode. The choice of mode is
determined by option settings described in
“The record Element” on page 386
and
“The range Element”
on page 385.
In record mode, the data document is treated as a sequence of records. In the simplest case,
each record in turn is loaded, processed, and unloaded before the next record is loaded. Record mode is
provided purely as a way to reduce resource consumption (memory and CPU cycles) by XFA processors
when dealing with large data documents. Anything that can be done in record mode can also be done in
non-record mode providing sufficient resources are available.
In non-record data binding proceeds as described under
Forms With Uniquely Named Fields and
Subforms.
In record mode, for each record, all of the same processing steps except the last (issuing the
form ready event) are executed in the same order before moving on to the next record. The last step,
issuing the form ready event, occurs only after all records have been processed. Hence the cycle can be
described as:
For each data record in document order
{
Create a new Form DOM
Load globals before the current record into the Data DOM
Load the current record into the Data DOM
Create form nodes as copies of template nodes
Match non-attribute data nodes to form nodes
Match attributes to unmatched form nodes
Renormalize the Form DOM
Perform calculations and validations
Pass the Form DOM to the layout process
Delete the Form DOM
Unload the record from the Data DOM (but keep the globals)
}
Issue the form ready event
A record is by definition a subtree of the Data DOM contained by a data group. All records are contained by
data groups which are at the same level in the hierarchy of the Data DOM. These data groups may all be
peers but they don't have to be – they could have different ancestors. They may optionally be restricted to
having the same names, so that data groups at the same level with different names are discarded.
Alternatively records can be defined by level alone without any limitation by name.