Repeater Block – the same blocks for every element of a list¶
The repeater draws its child blocks once for every element of a JSON list (an array). The list comes
from an expression – a field, the answer of an HTTP request, anything that produces
["a", "b", "c"] or a list of objects. It is the only way to build a part of a form whose number of
blocks is not known when the form is written.
This page is part of the form block reference.
1. At a glance¶
| Purpose | Repeats its child blocks once per element of a JSON list |
| Typical use | The tags of a record, the positions of an order delivered as JSON, the steps an interface reported |
| Related | Scroll Strip Block, Related Items Block |
2. Settings¶
| Setting | Meaning | Default |
|---|---|---|
| "JSON Array" | The list the children are repeated for, as an expression – for example ["a", "b", "c"] or a field that holds such a list. Anything that is not a list leaves the repeater empty. |
none |
| "Sort By" | Optional value the elements are ordered by, evaluated once per element. Numbers are ordered as numbers, everything else alphabetically. | order of the list |
| "Sort Descending" | Reverses the order. Without "Sort By" it reverses the order of the list. | off |
| "Max Iterations" | How many elements are drawn at most | 250 (2000 at most) |
| "Iteration Variables" | Read-only: the names of the three variables the children can read (see below) | – |
| "Horizontal" (Layout) | Lays the repetitions out side by side instead of under each other | off |
| "Gap", "Align Items", "Justify Content" (Layout) | Spacing and alignment of the repetitions, as on the Vertical Stack Block | none, Default, Default |
| "Is Container", "Container Id" (Layout) | Make the repeater a reference for breakpoints further down | off, none |
In addition, the block has the settings every block has, except "Flush".
The iteration variables¶
Every repetition hands three variables to all blocks below the repeater, at any depth. They are named after the repeater block:
| Variable | Value |
|---|---|
<block name> |
The element this repetition stands for |
<block name> (Index) |
Its position, counted from 1 |
<block name> (Count) |
How many repetitions are drawn |
Every expression setting below the repeater offers them as variables. Name the repeater after one
element – Tag, Position, Step – because that is how the variables are called. Two repeaters
inside each other offer six variables; their names tell them apart.
3. Behaviour¶
- "JSON Array" is evaluated. An element that is text arrives as the text without quotation marks;
a number or a yes/no value as its JSON text (
1.5,true); an element that is an object arrives as its JSON text – read the values inside it with a value modification of the variable. - If "Sort By" is set, it is evaluated once per element. When every result is a number, the
elements are ordered as numbers, otherwise all of them alphabetically – one result that is not a
number turns
10before9. An empty result counts as the smallest value. Elements with the same result keep their order. While "Sort By" runs,(Index)is the position in the unsorted list. - Only the first "Max Iterations" elements of the sorted list are drawn; the rest is left out.
-
The children are drawn once per element.
-
A button inside the repeater starts its action with the variables of its repetition – one row can act on exactly its own element.
- A stored block inside the repeater does not see the variables. Hand the element over as an argument of the stored block (see Stored blocks and parameters).
- In the preview of the editor, a repeater whose list is empty is drawn once with an empty element, so you can see and select the blocks inside it.
4. Examples¶
Tags of a ticket. The text field "Tags" holds ["VPN", "Laptop", "Urgent"]. A repeater named
Tag with "JSON Array" = the field "Tags" and "Horizontal" on contains a badge whose content
is the variable Tag. The ticket shows three badges. Put the repeater into a
Scroll Strip Block so that 30 tags stay on one line.
Positions from an interface. An action stores the answer of an HTTP request as
[{"item": "Monitor", "qty": 2}, {"item": "Dock", "qty": 1}]. A repeater named Position contains a
horizontal stack with two labels: one reads item, one reads qty from the variable Position.
"Sort By" reads qty, "Sort Descending" is on: the position with the highest quantity comes
first.
5. Limitations¶
- The repeater shows values, it does not collect them. An input block inside a repeater binds every repetition to the same field.
- "Max Iterations" is a ceiling, not paging: what is beyond it is not shown. For records, use the related items blocks, which page, sort and filter.
- To repeat a block a fixed number of times, place it that number of times instead.