Related Items Grid Block – related records as a table¶
The related items grid shows the records on the other side of a relationship as a table, laid out by a grid definition. It can show a preview form of the selected row next to the table and offers built-in buttons to link, unlink, add and delete records.
This page is part of the form block reference.
1. At a glance¶
| Purpose | Related records as a table, with optional preview, quick filters and built-in buttons |
| Typical use | Tasks of a project, devices of a customer, many records that are compared along the same columns |
| Related | Grids, Related Items List Block, Related Items Block |
The block is only offered in forms that belong to an entity.
2. Settings¶
| Setting | Meaning | Default / required |
|---|---|---|
| "Relationship" | The relationship whose records are shown | Required. Without it the block shows nothing. |
| "Grid" | Grid of the related entity: columns, sorting, toolbar | the default grid of the related entity |
| "Filter" | Condition evaluated per related record; only records for which it is true are shown. Always active, users cannot change it. | all related records |
| "Quick Filters" | A filter definition whose filter badges and sort options are offered above the table. Only expression filters are offered. | none |
| "Row Click" | Action run when a row is clicked, against the related record of that row | none |
| "Preview Form" | Form of the related entity shown for the selected row | none |
| "Preview Form Location" | Where the preview is shown: None, Top, Bottom, Left, Right | None – no preview is shown |
| "Density" | Row height of the table: Inherit (from the theme), Compact, Default, Comfortable | Inherit |
| "Link Button" | Adds a "Link" button that offers records to link to the relationship | off |
| "Unlink Button" | Adds an "Unlink" button that offers the linked records to unlink | off |
| "Add Button" | Adds an "Add" button that creates a new record in the relationship and selects it | off |
| "Delete Button" | Adds a "Delete" button that deletes the selected related record after a confirmation | off |
In addition, the block has the settings every block has, except "Flush". Padding, border and background apply to the table itself.
3. Behaviour¶
- Selected row: a click on a row makes it the current record of the relationship – which is what the preview form shows. The marked row always shows that record; the rows have no check boxes, and the mark cannot be removed – the relationship keeps its current record. "Row Click" additionally runs an action; with it, opening a row in a new tab is not available.
- Filter and quick filters: the filter is applied first. The quick filters narrow what the filter left over and show the number of records behind each badge. Quick filters must be expression filters, because the related records are already loaded and may include records that were created in the form and are not saved yet – a query would not see them. A query filter selected here is not shown.
- Built-in buttons are placed in front of the items of the grid's toolbar and appear even when the grid has no toolbar. They work on the record of the form; after they ran, the form is drawn again. Inside a disabled related items block they are disabled.
- Records that were created in the form and are not saved yet are shown as well.
4. Examples¶
Tasks of a project with preview. "Relationship" = "Project → Tasks", "Grid" = "Tasks Compact", "Preview Form" = "Task Detail", "Preview Form Location" = Right, "Add Button" and "Delete Button" on. A new task appears in the table and opens in the preview at once.
Only open tasks. A second grid over the same relationship with "Filter" = Status <> "Done".