XFA Specification
Chapter 8, Dynamic Forms
Data Binding for Dynamic Forms
262
Variable Number of Subforms
What makes a dynamic subform dynamic is that it has different values for its minimum and maximum
occurrences. The
min
attribute of the
occur
property of the subform determines its minimum
occurrences. When the subform is copied into the Form DOM this number of copies are created to start
with. A value of 0 makes the subform optional. If and when all of these copies are bound to data, and more
data remains that could bind to additional copies, the
max
attribute of the
occur
property limits how
many more copies can be added. If the value of
max
is -1 the only limit is the amount of data available. The
occur
property for a subform set works exactly the same way.
The following example shows the dynamic membership list template corresponding to the figure on
page 260,
omitting decorative elements. The attributes that make it dynamic have been highlighted in
bold.
<template ……>
<subform name="Members">
<field name="Date" …> … </field>
<subform name="Member">
<occur min="1" max="20"/>
<field name="First" …> … </field>
<field name="Last" …> … </field>
</subform>
</subform>
</template>
In this example the minimum number of detail lines (member's names) that will be included when
merging with data is one, from the
min
attribute. The maximum is twenty, from the
max
attribute.
Note that when any of the attributes is omitted from the
occur
element, the value of the corresponding
property defaults to 1. In the absence of an
occur
sub-element all of its properties default to 1. Hence the
default behavior is for a subform to be incorporated exactly once into the Form DOM whether or not there
is data, that is, to behave as a static subform.
In the membership list example the minimum occurrence for the
Detail
subform defaults to 1 and the
maximum is 20. The minimum of 1 means that the subform must be copied at least once into the Form
DOM, even if there is none of the data matches it. The maximum of 20 means that it can be copied at most
twenty times into the Form DOM. If the data file contained a twenty-first
Member
data group, it would if
possible bind to some other subform. In this case there would be no other subform for it to bind to, so it
would simply be ignored.
Normally, for the template to be valid, the maximum occurrence value must be an integer greater than or
equal to the minimum occurrence value. However a value of -1 for the maximum occurrence is special. It
means that the number of occurrences is unlimited. When the maximum occurrence is -1 the minimum
occurrence can have any value greater than or equal to zero.
A maximum occurrence of -1 is very commonly used for dynamic subforms. When the form is to be
displayed on a graphics display the unlimited scrolling length of the virtual page suits the unlimited
length of the sequence of subforms. However when printed to paper the sequence of subforms must be
broken up into properly paginated units. This is performed downstream by the layout process, as
described in
“Layout for Dynamic Forms” on page 280
and has no effect on data binding.
Note that the minimum occurrence must be an integer greater than or equal to zero. In addition, it must
be less than or equal to the maximum occurrence value unless the maximum occurrence value is -1. If
either of these conditions is violated the template is invalid.