Lists – showing records as a list of small forms¶
A list shows the records of an entity one below the other, each drawn with a form instead of table columns. This chapter describes how you configure a list and where it is used.
It is intended for administrators who design the screens of an application. Lists share most of their behaviour with grids; this chapter names what is different.
1. Lists at a glance¶
A list belongs to exactly one entity. For every record it draws the "Preview Form" – a compact form of the same entity. Like a grid, a list does not choose its records: a query or a relationship hands them over.
| Grid | List | |
|---|---|---|
| A record is shown as | a row of columns | a small form |
| Column headings, sorting by heading | yes | no |
| Sort order chosen by the user | column headings | the sort dropdown of the "Filter" |
| Grouping | initial grouping, changeable by the user | initial grouping only |
| Remembered layout per user | yes | no |
| Export | visible columns | the fields the preview form reads |
| Where a list is used | What supplies the records |
|---|---|
| Related items list block in a form | The records linked to the record of the form (see Forms) |
| "Query Result List Block" on a dashboard | A query (see Query Result List) |
Lists are managed in the Admin Studio under Design → Lists, or under the entity in the area Entities. The permissions are "Open List Manager", "Add List", "Edit List" and "Delete List".
When to use a list: when each record needs more than a row – a card with a picture, a status, a few lines of text and buttons. For comparing many records along the same values, a grid is the better choice.
2. Creating a list¶
- First create the form that draws a single item: a form of the same entity, kept compact – it is drawn once for every record on the page.
- Open Admin Studio → Design → Lists (or the entity under Entities) and create a list.
- Select the form as "Preview Form" on the tab "General".
- Optionally set grouping and sort order on the tab "Grouping & Sorting".
- Save with "Save & Close".
3. Settings¶
Tab "General"¶
| Setting | Meaning | Default |
|---|---|---|
| "Preview Form" | The form each record is drawn with. Without it the list cannot draw its items. | none – required |
| "Toolbar" | An app bar above the list, with buttons for the list as a whole | none |
| "Filter" | A filter definition whose quick filters and sort options are offered above the list. Only query filters of the same entity are offered. | none |
| "Disable export" | When on, nobody can export the records of this list, not even users with the permission "Export Query Results" | off |
| "CSS Styles" | Intended for styles per item. Currently without effect – style the preview form instead. | none |
Tab "Grouping & Sorting"¶
| Setting | Meaning | Default |
|---|---|---|
| "Group By Fields" | Fields of the entity the items are grouped by, outermost first | no grouping |
| "Sort By" | The initial sort order: one or more fields of the entity, each ascending (ASC) or descending (DESC). Any field can be used, not only a group field. Replaces the order of the query. | the order of the query |
4. Behaviour¶
- Paging: a list loads its records page by page, like a grid. The footer offers the page size and the page buttons.
- Sorting by the user: a list has no column headings. If the "Filter" defines sort options, a dropdown "Sort by" appears above the list, with "Default order" as the first entry. Without such a filter, the user cannot change the order.
- Quick filters of the "Filter" appear as chips above the list.
- Selection: a check box in front of each item selects it; "Select all visible rows" in the toolbar selects all items of the page. A list of a query result allows several selected items; a list inside a form follows exactly one record.
- Opening a record: a click on an item opens the record with the default form of its entity. The preview form itself may contain buttons that run their own actions.
- Toolbar: the buttons of the "Toolbar" behave as in a grid: an action of the same entity runs once for all selected items and is disabled while nothing is selected (see Grids).
- Read limits of the user apply to the records, as everywhere.
Export¶
"Export" offers XLSX, CSV, JSON and XML to users with the permission "Export Query Results". A list has no columns, so nexxcite writes the fields the preview form reads, in the order of the form: the fields of its inputs and the fields its expressions read, including those of stored blocks inside it. Values of related records are not written. If the list has no preview form, or the form reads no field, all fields of the entity are written. The rest – all records, Excel limit of 32,767 characters per cell – is the same as for a grid.
5. Example¶
Open orders as cards on a dashboard.
- Form "Order card" (entity "Order"): the order number in bold, the customer name, the amount and a badge with the status.
- List "Open orders": "Preview Form" = "Order card", "Sort By" = "Order date DESC", "Group By Fields" = "Status".
- Dashboard: a "Query Result List Block" with the query "Open orders" and the list "Open orders".
6. Limitations¶
- The user cannot regroup a list; only the initial grouping of the definition applies.
- The layout of a list (page size and similar) is not remembered per user.
- Grouping and sorting only use fields of the list's own entity, not fields of related records.
- Every item is a complete form. A long page of items with many blocks each takes noticeably longer to draw than a grid; keep the preview form small.
- "CSS Styles" currently has no effect.