Orbeon Forms
Search…
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

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

1
<fr:grid id="note-grid">
2
<fr:c y="1" x="1" w="12">
3
<!-- A form control will be placed here -->
4
</fr:c>
5
</fr:grid>
Copied!
Example with multiple cells spanning rows and columns:
1
<fr:grid id="grid-1-grid">
2
<fr:c y="1" x="1" w="6">
3
<!-- A form control will be placed here -->
4
</fr:c>
5
<fr:c y="1" x="7" w="6" h="2">
6
<!-- A form control will be placed here -->
7
</fr:c>
8
<fr:c x="1" y="2" w="3">
9
<!-- A form control will be placed here -->
10
</fr:c>
11
<fr:c x="4" y="2" w="3">
12
<!-- A form control will be placed here -->
13
</fr:c>
14
</fr:grid>
Copied!

Until Orbeon Forms 2017.1

1
<fr:grid id="note-grid">
2
<xh:tr>
3
<xh:td>
4
<!-- A form control will be placed here -->
5
</xh:td>
6
</xh:tr>
7
</fr:grid>
Copied!

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
    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
    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

1
<fr:grid
2
id="note-grid"
3
repeat="content"
4
bind="note-bind"
5
template="instance('note-template')"
6
min="0">
7
<fr:c y="1" x="1" w="12">
8
<!-- A form control will be placed here -->
9
</fr:c>
10
</fr:grid>
Copied!

Until Orbeon Forms 2017.1

1
<fr:grid
2
id="note-grid"
3
repeat="content"
4
bind="note-bind"
5
template="instance('note-template')"
6
min="0">
7
<xh:tr>
8
<xh:td>
9
<!-- A form control will be placed here -->
10
</xh:td>
11
</xh:tr>
12
</fr:grid>
Copied!

Data format

With repeat="content":
    An enclosing element is present.
    Nested elements, typically suffixed with -iteration, enclose each repetition.
1
<note>
2
<note-iteration>
3
<note-text/>
4
</note-iteration>
5
<note-iteration>
6
<note-text/>
7
</note-iteration>
8
</note>
Copied!
With legacy repeat="true":
    No enclosing element is present.
    Elements are repeated at the top-level.
1
<note>
2
<note-text/>
3
</note>
4
<note>
5
<note-text/>
6
</note>
Copied!
A template instance contains the XML data to insert for a new iteration:
1
<xf:instance id="note-template">
2
<note-iteration xmlns="">
3
<note-text/>
4
</note-iteration>
5
</xf:instance>
Copied!

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

Last modified 1yr ago