Comment on page
Grid

What it does
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]
Appearance
Full repeat appearance
Menu
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
Single-line
Full appearance / single-line
Multi-line
Full appearance / multi-line
Minimal repeat appearance
[SINCE Orbeon Forms 2016.1]
Minimal appearance / single-line
Minimal appearance / multi-line
Basic usage
Format of rows and cells
Starting Orbeon Forms 2017.2
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.
Until Orbeon Forms 2017.1
<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
Non-repeated mode
General information
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.
Starting Orbeon Forms 2017.2
<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>
Until Orbeon Forms 2017.1
<fr:grid id="note-grid">
    <xh:tr>
        <xh:td>
            <!-- A form control will be placed here -->
        </xh:td>
    </xh:tr>
</fr:grid>
Repeated mode
General information
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
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 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
Starting Orbeon Forms 2017.2
<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>
Until Orbeon Forms 2017.1
<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>
Data format
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>
Relevance and readonly behavior
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.
Events
[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
See also
​Section component​
​Form data format​
​Form Builder: Repeated Grids​
Example of use outside of Form Runner: gist​
​Evaluation of initial values upon insert​
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
Error summary
Handwritten signature
Last modified 1yr ago