XFA Specification
Chapter 8, Dynamic Forms
Layout for Dynamic Forms
283
Break on Entry
A subform may specify default behavior explicitly via a
breakBefore
element with a
targetType
attribute having a value of
auto
. Alternatively, it may specify that it must be placed inside an instance of a
particular
contentArea
or
pageArea
. If the breakBefore element has a
targetType
property with a
value of
pageArea
or
contentArea
, the layout processor gets a target specification from the value of
the element's
target
property. If the target specification starts with the character ‘#’ it is evaluated as a
reference to an XML ID; otherwise it is evaluated as a SOM expression. If there is an object of the correct
type matching the target specification the layout processor first checks whether the current container is
within a
contentArea
or
pageArea
that is an instance of the one specified. If it is not, the layout
processor breaks to the specified target. If the target is a
pageArea
then the layout processor traverses to
the first unused (empty) child
contentArea
, as it would when flowing from one
contentArea
to the
next. For example, a template contains the following declarations:
<subform name="X">
<breakBefore targetType="pageArea" target="#E_ID"/>
<pageSet name="A">
<pageArea name="B">
<contentArea name="C" … />
<contentArea name="D" … />
</pageArea>
<pageArea name="E" ID="E_ID">
<contentArea name="F" … />
</pageArea>
</pageSet>
<field name="Y">
</subform>
The Form DOM contains the following content:
[subform (X)]
[field (Y) = "some user-supplied data"]
At startup the layout processor would by default descend into the first
contentArea
(C) of the first
pageArea
(B) of the first
pageSet
(A) of the root subform (X). Another way of looking at this is that by
default there is an implied break to the first
pageArea
of the root subform. However, subform X asserts an
explicit break to the
pageArea
with ID
E_ID
. This happens to be
pageArea
E. The layout processor
traverses the tree of
pageArea
and
contentArea
nodes until it reaches the specified
pageArea
. Then it
descends into the first
contentArea
there to place the layout content. The resulting Layout DOM is:
[root]
[pageArea (E)]
[contentArea (F)]
[subform (X)]
[field (Y) = "some user-supplied data"]
➤
Error Condition: Invalid break target
A conforming template must not supply a target specification for the
breakBefore
element that does
not resolve to exactly one
pageArea
or
contentArea
. However it is anticipated that layout processors
will encounter some templates that are not conforming in this way. It is recommended that in such a case
the layout processor emit a warning and go to the next available
pageArea
or
contentArea
.