The fr:grid
component organizes contained controls in a grid of rows and columns. Features:
configurable number of rows and columns
optional repetition of its content
configurable min/max number of iterations
can repeat over several heterogeneous rows
built-in icons and menus to add, remove, and move repeated rows
supports relevant
and readonly
MIPs [SINCE Orbeon Forms 4.8]
A menu is available to perform operations on or around a line. Not all operations are always available, depending on the position of the line or the freeze
setting. When the entire grid is made readonly, the menu is not present.
Insert Above
When allowed, insert a new repetition above the current one.
Insert Below
When allowed, insert a new repetition below the current one.
Move Up
When allowed, move the current repetition one level above.
Move Down
When allowed, move the current repetition one level below.
Clear Line
[SINCE Orbeon Forms 2019.2]
Clear or reset all the values in the current repetition.
Remove Line
When allowed, remove the current repetition.
[SINCE Orbeon Forms 2016.1]
With Orbeon Forms 2017.2 and newer, the format for grid rows and cells produced by Form Builder has changed. Instead of using <xh:tr>
and <xh:td>
, it uses <fr:c>
. <xh:tr>
and <xh:td>
are still supported for backward compatibility.
The following attributes are supported on <fr:c>
:
x
:
x position
required
minimum: 1
maximum: 12
y
:
y position
required
minimum: 1
maximum: none
w
:
width of the cell
required
minimum: 1
maximum: 12
h
:
height of the cell
optional, defaults to 1
minimum: 1
maximum: none
The following must hold:
cells must not overlap
cells must not extend beyond column 12
In other words, the grid must be well-formed.
However, the grid may have holes, and not all cells need be present.
<xh:tr>
and <xh:td>
are used to indicate rows and cells, following the HTML tables <tr>
and <td>
scheme.
The following attributes are supported on <xh:td>
:
rowspan
optional, defaults to 1
as in HTML
supported in Form Builder
colspan
optional, defaults to 1
as in HTML
NOT supported in Form Builder
Attributes:
id
: optional grid id. Form Builder always places an id.
repeat
: can be optionally set to false
NOTE: In the future bind
and ref
should be supported.
<fr:grid id="note-grid"><fr:c y="1" x="1" w="12"><!-- A form control will be placed here --></fr:c></fr:grid>
Example with multiple cells spanning rows and columns:
<fr:grid id="grid-1-grid"><fr:c y="1" x="1" w="6"><!-- A form control will be placed here --></fr:c><fr:c y="1" x="7" w="6" h="2"><!-- A form control will be placed here --></fr:c><fr:c x="1" y="2" w="3"><!-- A form control will be placed here --></fr:c><fr:c x="4" y="2" w="3"><!-- A form control will be placed here --></fr:c></fr:grid>
<fr:grid id="note-grid"><xh:tr><xh:td><!-- A form control will be placed here --></xh:td></xh:tr></fr:grid>
Attributes:
id
: optional grid id.
repeat
true
: legacy repeat mode
content
: new repeat mode with an enclosing element [SINCE Orbeon Forms 4.8]
bind
or ref
with repeat="content"
: single item binding which binds to the enclosing element
with repeat="true"
: item sequence binding which binds to the repeated elements
template
XML data template used to insert new data when iterations are inserted
optional when the grid is readonly
min
and max
minimum vs. maximum number of repeat iterations supported
can be an AVT
evaluation context
with repeat="content"
: context of the binding (bind
or ref
)
with repeat="true"
(deprecated): context of the fr:grid
element
are checked when the user attempts to add/remove iterations with the UI
max
can also take the explicit value none
remove-constraint
optional XPath expression
evaluation context
context of the iteration item
if the constraint returns false()
, the current row cannot be removed
freeze
optional number of rows at the top which cannot be removed or moved
can be an AVT [SINCE Orbeon Forms 2016.3]
evaluation context
with repeat="content"
: context of the binding (bind
or ref
)
with repeat="true"
: context of the fr:grid element
readonly
force the grid to be readonly when set to true
this cannot be an AVT
apply-defaults
[SINCE Orbeon Forms 2016.1]
true
: dynamic initial values (via the xxf:default
MIP) apply to new iterations
missing or `false: dynamic initial values do not apply to new iterations
can be an AVT
see also: Evaluation of initial values upon insert​
appearance
[SINCE Orbeon Forms 2016.1]
full
the default appearance, as with Orbeon Forms 4.10 and earlier
row menu
reordering of rows
insertion of rows at specific points
removing of specific rows
minimal
does not show the "+" button at the top left
does not show the row menu and associated features
instead just provides "Add another" and "Remove" links at the bottom
insert
[SINCE Orbeon Forms 2016.2]
index
the "Add Another" or "+" button adds a new repetition after the iteration currently with keyboard focus
this is the default in full
appearance
bottom
the "Add Another" or "+" button adds a new repetition after the last iteration
this is the default in minimal
appearance
<fr:gridid="note-grid"repeat="content"bind="note-bind"template="instance('note-template')"min="0"><fr:c y="1" x="1" w="12"><!-- A form control will be placed here --></fr:c></fr:grid>
<fr:gridid="note-grid"repeat="content"bind="note-bind"template="instance('note-template')"min="0"><xh:tr><xh:td><!-- A form control will be placed here --></xh:td></xh:tr></fr:grid>
With repeat="content"
:
An enclosing element is present.
Nested elements, typically suffixed with -iteration
, enclose each repetition.
<note><note-iteration><note-text/></note-iteration><note-iteration><note-text/></note-iteration></note>
With legacy repeat="true"
:
No enclosing element is present.
Elements are repeated at the top-level.
<note><note-text/></note><note><note-text/></note>
A template instance contains the XML data to insert for a new iteration:
<xf:instance id="note-template"><note-iteration xmlns=""><note-text/></note-iteration></xf:instance>
With repeat="content"
:
if the bound item is non-relevant, the grid is entirely hidden
if the bound item is readonly, the grid is entirely readonly and menus and icons don't show
In either case, fr:grid
contains the rows to repeat as xh:tr
. Each xh:tr
contains xh:td
cells as needed.
[SINCE Orbeon Forms 2016.1]
The following events are dispatched to the fr:grid
element:
Event name | Description |
| Dispatched when the user has just added an iteration |
| Dispatched when the user has just removed an iteration |
These events are not dispatched if the number of iterations changes by other means, for examle if the data is replaced, or inserts/deletes happen outside of the component.
[SINCE Orbeon Forms 2018.2]
Both events take an index
context information:
event('index') as xs:integer
: the index of the row added or removed
​Section component​
​Form data format​
​Form Builder: Repeated Grids ​
Example of use outside of Form Runner: gist​