Comment on page
Grid
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
andreadonly
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.

Repeated grid menu

Full appearance / single-line

Full appearance / multi-line
[SINCE Orbeon Forms 2016.1]

Minimal appearance / single-line

Minimal appearance / multi-line
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 tofalse
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 modecontent
: new repeat mode with an enclosing element [SINCE Orbeon Forms 4.8]
bind
orref
- 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
andmax
- minimum vs. maximum number of repeat iterations supported
- can be an AVT
- evaluation context
- with
repeat="content"
: context of the binding (bind
orref
) - with
repeat="true"
(deprecated): context of thefr:grid
element
- are checked when the user attempts to add/remove iterations with the UI
max
can also take the explicit valuenone
remove-constraint
- optional XPath expression
- evaluation context
- context of the iteration item
- if the constraint returns
false()
, the current row cannot be removed
clear-constraint
- [SINCE Orbeon Forms 2022.1]
- optional XPath expression
- evaluation context
- context of the iteration item
- if the constraint returns
false()
, the "Clear Line" menu item is disabled
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
orref
) - with
repeat="true"
: context of thefr: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 thexxf:default
MIP) apply to new iterations- missing or `false: dynamic initial values do not apply to new iterations
- can be an AVT
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:grid
id="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:grid
id="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 |
---|---|
fr-iteration-added | Dispatched when the user has just added an iteration |
fr-iteration-removed | 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
Last modified 1yr ago