# Section

## What it does

The `fr:section` component organizes [grids](https://doc.orbeon.com/form-runner/component/grid) under a header or title. Features:

* collapsible section content
* 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

## Appearance

### Non-repeated appearance

An open, collapsible section shows a "collapse" icon at the left of the heading.

![Open section](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEkBiSDvlXs3VWiO0Zu%2F-LL5f7RgoXiXvVKRMgo4%2F-LL5fFrp3zrt2iQRL6qn%2Fxbl-section-open.png?generation=1535562815480459\&alt=media)

The same section when closed just shows the heading.

![Closed or collapsed section](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEkBiSDvlXs3VWiO0Zu%2F-LL5f7RgoXiXvVKRMgo4%2F-LL5fFrrTxnUUNZqnZpy%2Fxbl-section-closed.png?generation=1535562815098586\&alt=media)

### 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 section menu](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEkBiSDvlXs3VWiO0Zu%2F-LxNZd9pylI96dTuT4G-%2F-LxNZnu6lBwB2OfvmEeT%2Fxbl-grid-menu.png?generation=1577739044203862\&alt=media)

#### Appearance

![Full appearance](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEkBiSDvlXs3VWiO0Zu%2F-LL5gPVZwk84cOQApInB%2F-LL5fFrtIwfQ0-rpmSI4%2Fxbl-section-repeat-full.png?generation=1535563155219681\&alt=media)

### Minimal repeat appearance

\[SINCE Orbeon Forms 2016.1]

![Minimal appearance](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEkBiSDvlXs3VWiO0Zu%2F-LL5f7RgoXiXvVKRMgo4%2F-LL5fFrvj4uF_KpKdUED%2Fxbl-section-repeat-minimal.png?generation=1535562815420972\&alt=media)

## Basic usage

### Non-repeated mode

These attributes are supported when the section is in non-repeated mode.

* `open`
  * whether the section is initially open
  * `true` (default)
    * section is initially open
  * `false`
    * section is initially closed
  * *NOTE: When the Form Runner mode is readonly ("view" mode, "pdf" mode, etc.), `open` is forced to `true`.*
* `animate`
  * whether the section animates when collapsing/expanding
  * `true` (default)
    * section animates
  * `false`
    * section does not animate
* `collapsible` \[SINCE Orbeon Forms 2016.1]
  * whether the section can be collapsed and expanded by clicking on its title
  * `true` (default)
    * allow section to be collapsed
  * `false`
    * don't allow section to be collapsed
  * *NOTE: If the section is initially closed and `collapsible` is `false`, the user won't be able to open the section.*
* `level` \[SINCE Orbeon Forms 2016.3]
  * level of the section, from `1` to `6`
  * default: `2`
  * alongside `base-level`, this value translates into an HTML heading `h1` to `h6`
* `base-level` \[SINCE Orbeon Forms 2016.3]
  * base level of the section, from `0` to `5`
  * default: `0`
  * when set to a non-zero value, this value is added to the value of `level` to produce the actual section level

### Repeated mode

These attributes are supported in addition to the non-repeated mode attributes when the section is in repeated mode:

* `freeze`
  * optional number of rows at the top which cannot be removed or moved
  * can be an AVT \[SINCE Orbeon Forms 2016.3]
* `readonly`
  * whether to disallow the user to add/remove iteration with the menu or the "-" button (depending on appearance)
  * `false` (default)
    * show the iteration menu and buttons, unless the section binds to a readonly node or unless the Form Runner

      mode is readonly ("view" mode, "pdf" mode, etc.)
  * `true` (default)
    * don't show the iteration menu and buttons
* `appearance` \[SINCE Orbeon Forms 2016.1]
  * `full`
    * the default appearance, as with Orbeon Forms 4.10 and earlier
    * iteration menu
      * reordering of iterations
      * insertion of iterations at specific points
      * removing of specific iterations
  * `minimal`
    * does not show the "+" button at the top left
    * does not show the iteration menu and associated features
    * instead just provides "Add another" and "Remove" links at the bottom and a "-" button to the right
* `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

You move, insert, and remove iterations using the left menu:

![Menu](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEkBiSDvlXs3VWiO0Zu%2F-LL5f7RgoXiXvVKRMgo4%2F-LL5fFsA63T9kFXWkDGy%2Fxbl-section-repeat-menu.png?generation=1535562815284997\&alt=media)

## Data format

See [Form data format](https://doc.orbeon.com/api/data-formats/form-data#repeated-sections).

## Events

### Events supported

| Event name    | Description          |
| ------------- | -------------------- |
| `fr-expand`   | Expand the section   |
| `fr-collapse` | Collapse the section |

### Events dispatched

\[SINCE Orbeon Forms 2016.1]

The following events are dispatched to the `fr:section` 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.

## See also

* [Grid component](https://doc.orbeon.com/form-runner/component/grid)
* [Form data format](https://doc.orbeon.com/form-runner/api/data-formats/form-data)