Repeater Block – the same widgets once per list element¶
The repeater draws its widgets once for every element of a JSON array. The array comes from an expression – a field, a global value, the answer of a web service. It is the only way to build a dashboard whose number of widgets is not known in advance.
This page is part of the widget reference.
1. At a glance¶
| Purpose | Repeats its widgets for every element of a JSON array |
| Typical use | One card per region from a list of regions; one badge per tag; tiles from the answer of an external service |
| Related | Catalog and Query Results for records of a query |
2. Settings¶
In addition, the widget has the settings every widget has, except "Auto Refresh".
| Setting | Meaning | Default |
|---|---|---|
| "JSON Array" | The array the widgets are repeated for, for example ["North", "South", "West"] or a list of objects |
none – required |
| "Sort By" | A value the elements are put in order by, evaluated per element. Numbers are ordered as numbers, everything else alphabetically. | the order of the array |
| "Sort Descending" | Reverses the order | off |
| "Max Iterations" | How many elements are drawn at most | 250 (at most 2,000) |
| "Iteration Variables" | Read only: the names of the variables the widgets inside can read | – |
| "Horizontal" | Lays the repetitions out next to each other instead of below each other | off |
| "Gap", "Align Items", "Justify Content", "Is Container", "Container Id" | Layout of the repetitions, as for a stack | none, Default, Default, off, none |
3. Behaviour¶
- Every repetition is handed its element. The widgets inside read it through a variable named after the repeater, for example "Regions". Next to it are "Regions (Index)" – the position, counted from 1 – and "Regions (Count)" – how many elements are drawn.
- An element that is an object arrives as its JSON text. Read values inside it with an expression that extracts a JSON property.
- A widget inside a second repeater sees the variables of both repeaters.
- Anything that is not a JSON array leaves the repeater empty.
- While "Sort By" is evaluated, the index variable still holds the position in the unsorted array.
- The repeater does not refresh itself.
Renaming the repeater renames its variables. Check the expressions of the widgets inside.
4. Example¶
One card per region. A repeater "Regions" with "JSON Array" ["North", "South", "West"],
"Horizontal" on and "Gap" 16. Inside, a card whose query has a condition "Region = variable
Regions" and whose title shows the variable. The dashboard shows three cards, one per region.
5. Limitations¶
- At most 2,000 repetitions; elements beyond "Max Iterations" are left out.
- For records of a query, a Catalog, a Query Results widget or a grid is the better choice – they load the records directly.