Grids – showing records as a table¶
A grid shows the records of an entity as a table: which columns appear, how the rows are sorted and grouped at first, and which toolbar sits above them. This chapter describes how you configure a grid in the grid editor and what users can do with it.
It is intended for administrators who design the screens of an application.
1. Grids at a glance¶
A grid belongs to exactly one entity. Every column reads the records of that entity. A grid does not choose its records: a query, a relationship or an action hands them over. The same grid can therefore show "all open tickets" in one place and "the tickets of this customer" in another.
| Where a grid is used | What supplies the records |
|---|---|
| "Default Grid" of an entity | Used whenever records of the entity are listed without a grid of their own – for example when a query result is opened by a link or from the AI assistant |
| Query result page | A query, opened by an action, an app bar entry or a link (section 8) |
| Related items grid block in a form | The records linked to the record of the form (see Forms) |
| "Query Result Grid Block" on a dashboard | A query (see Query Result Grid) |
| Link and unlink dialogs | The records that can be linked or unlinked through a relationship |
| Data Inspector | The records of the inspected entity |
Grids are managed in the Admin Studio under Design → Grids, or under the entity in the area Entities. The permissions are "Open Grid Manager", "Add Grid", "Edit Grid" and "Delete Grid" (see Roles and permissions).
Summary¶
- A grid consists of columns. There are four kinds: field, HTML, badge and toolbar columns.
- Only field columns can be sorted, grouped and filtered by the user.
- Users can rearrange, resize, hide, sort, group and filter the columns. nexxcite remembers the layout per user and grid.
- Records are loaded page by page. An export to Excel, CSV, JSON or XML is available to users with the permission "Export Query Results".
- Values cannot be edited in the grid itself. A click on a row opens the record.
2. Creating a grid¶
- Open Admin Studio → Entities, select the entity and open Grids – or open Design → Grids.
- Create a new grid. The grid belongs to the entity selected when it is created.
- On the tab "Columns", add the columns with the + button and choose the kind of column.
- On the tab "General", set the initial sort order, grouping, toolbar and filter.
- Save the grid with "Save & Close".
To make the grid the standard list of the entity, select it as "Default Grid" in the entity editor. Every new entity should have one.
The editor has two tabs:
| Tab | Content |
|---|---|
| "General" | Name, description, tags, icon, "CSS Styles", "Toolbar", "Filter", "Sort By", "Group By", "Disable export" |
| "Columns" | A preview of the table and one card per column |
The preview¶
Above the columns the editor draws a picture of the table: the column headings and four invented records. It shows the order, the widths, the alignment, the sort column (ASC/DESC) and the grouping. Below the picture, notes list what the picture cannot show – columns that start hidden, columns that disappear on narrow screens, and how the record looks as a card on a phone. The values are invented and do not come from your data. The preview changes with every setting you change.
3. Settings of the grid¶
| Setting | Meaning | Default |
|---|---|---|
| "Toolbar" | An app bar shown above the grid, with buttons for the grid as a whole – for example "New ticket" or an action on the selected rows (section 7) | none |
| "Filter" | A filter definition whose quick filters are offered above the grid as chips. Only query filters of the same entity are offered. | none |
| "Sort By" | The initial sort order: one or more field columns, each ascending (ASC) or descending (DESC). Replaces the order of the query that supplies the records. | the order of the query |
| "Group By" | Field columns the rows are grouped by at first, outermost first | no grouping |
| "Disable export" | When on, nobody can export the records of this grid, not even users with the permission "Export Query Results" | off |
| "CSS Styles" | Inline CSS styles for the rows, computed per record (see below) | none |
"Sort By" and "Group By" only offer field columns, and only after they have been added on the tab "Columns".
CSS styles of the grid: the expression returns CSS declarations for the row, for example
background: #fef2f2 for overdue tickets. It is evaluated for each record, so the styles can depend
on the fields of the record. The styles apply to every row and, when the grid shows cards, to the
card. Write declarations only, without selectors or curly braces. A background colour set here
replaces the highlight of a row under the mouse pointer or of a selected row; a selected row keeps
its marker at the left edge. For the styles of a single column use the "CSS Styles" of the column
(section 4).
4. Columns¶
Kinds of columns¶
| Kind | Shows | Sort, group, filter by the user |
|---|---|---|
| "Field Column" | The value of a field of the record | yes |
| "HTML Column" | HTML computed per record by an expression – for example a progress bar or a value of a related record | no |
| "Badge Column" | A coloured chip per record – a status, a priority | no |
| "Toolbar Column" | The buttons of an app bar in every row; they run against the record of the row | no |
The cards of the columns can be moved up and down and removed. The order of the cards is the order of the columns from left to right.
Settings of every column¶
| Setting | Meaning | Default |
|---|---|---|
| "Column Name" | The heading of the column. It is not taken from the field – empty leaves the heading blank. | empty |
| "Display Name" | The name of the column in the editor | "New … Column" |
| "Width" | Width in pixels, written as 200 or 200px |
automatic (see below) |
| "Allow Resizing" | Users may drag the column wider or narrower | on |
| "Initially Hidden" | The column is not shown until the user switches it on in "Columns" | off |
| "Allow Hiding" | Users may hide the column and show it again | off |
| "Priority" | What happens on a narrow grid: "1 - always shown", "2 - hidden below 860 px", "3 - hidden below 1000 px" | 1 |
| "Mobile Role" | Where the value goes when the grid shows cards (section 6): Detail, Title, Subtitle, Badge, Hidden | Detail (Badge for badge columns) |
| "CSS Styles" | Inline CSS styles for the cells of the column, computed per record (see below) | none |
Width without a value: the first text column without a width gets 200 pixels, every other column 150 pixels – a badge column 140, a toolbar column 120. If the grid is wider than its columns, the last visible column without a width takes the remaining room, so the grid ends flush with its right edge. The order the user sees counts: after hiding or moving columns, the column without a width that is now the last one takes the room. If every column has a width, the remaining room stays empty. Values in percent or other units are ignored, even though the tooltip of the setting mentions percent.
CSS styles of a column: the expression returns CSS declarations, for example
color: #b91c1c; font-weight: 600. It is evaluated for each record, so the styles can depend on the
fields of the record – for example a red text for overdue tickets only. The styles apply to the cell
of every row and, when the grid shows cards, to the value in the card. Write declarations only, without
selectors or curly braces. Styles that change the size of a cell, such as a width, do not change the
width of the column; use "Width" for that.
Field column¶
| Setting | Meaning |
|---|---|
| "Field" | The field of the entity shown in the column. Without a field the column stays empty. |
Only fields of the grid's own entity can be shown. To show a value of a related record, use an HTML column.
HTML column¶
| Setting | Meaning |
|---|---|
| "Content" | An expression that computes the HTML of the cell. It is evaluated for each record and can read the fields of the record and its related records. |
Badge column¶
The badge column has the same look as the badge block of a form. A badge needs a text, an icon or both.
| Setting | Meaning | Default |
|---|---|---|
| "Content" | The text inside the badge, computed per record. Keep it to one or two words – a badge does not wrap. | none |
| "Icon" | An icon in front of the text, computed per record | none |
| "Click Action" | An action run against the record of the row when the badge is clicked. The rows are reloaded afterwards. | none – the badge cannot be clicked |
| "Text Color", "Background Color", "Border Color" | Colours computed per record | built-in colours |
| "Border Width" | Border width as a CSS length, for example 1px. Without it no border is drawn. |
none |
| "Border Radius", "Font Size", "Font Weight" | Shape and text of the badge | Default (pill shape, small, semi-bold) |
Toolbar column¶
| Setting | Meaning |
|---|---|
| "Toolbar" | The app bar whose buttons appear in every row. An action of a button runs against the record of its row, independently of the rows the user has selected. |
5. Working with a grid¶
Sorting¶
| Gesture | Effect |
|---|---|
| Click on a column heading | Sorts ascending, then descending, then not at all. Replaces the previous sort order. |
| Shift+click on a heading, or "Add as sort level" in the column menu | Adds the column as a further sort level |
| "Sort ascending", "Sort descending", "Clear sorting" | In the column menu (the button in the heading) |
Sorting always runs over all records, not only the page that is shown.
Grouping¶
Drag a column heading onto the bar "Drag a column here to group", or use "Group by …" in the column menu. Several levels are possible. Each group starts with a group row that can be collapsed. The group row shows how many records of the page belong to it and – where nexxcite can count them – how many there are in the whole result, for example "97 of 2,936". The total is not counted for date columns and for groups with an empty value; there the group row shows the count of the page.
Filtering¶
"Filter..." in the column menu opens a filter for the column. Which filter appears depends on the data type of the column:
| Data type | Filter |
|---|---|
| Text (and every other type) | "contains", "does not contain", "is", "is not", "is empty", "is not empty" |
| Number | "is", "is not", "greater than", "at least", "less than", "at most", "is empty", "is not empty" |
| Date, date and time | "From" and "To" |
| Yes/No | "Yes" or "No" |
Active filters are shown as chips above the grid and can be removed there. If no row matches, the grid says "No row matches the search or the filters." and offers "Clear filters".
The grid editor does not offer the data type of a column. Columns created in the editor are treated as text: they get the text filter and are aligned left, even when the field holds numbers or dates (see section 10).
Quick filters¶
If the grid has a "Filter", its quick filters appear as chips in the toolbar of the grid, next to the column filters. A click switches a quick filter on or off. The filter definitions themselves are described in Filters.
Columns, widths and order¶
- Rearrange a column by dragging its heading onto another heading.
- Resize it with the handle at the right edge of the heading; a double click restores the default width. The other columns keep their widths; only the column that takes the remaining room (see "Width without a value") becomes narrower or wider to make up for it.
- "Columns" in the toolbar lists all columns. Columns with "Allow Hiding" or "Initially Hidden" can be switched on and off there; the others are greyed out. "Reset order and widths" restores the order, the widths and the visible columns of the definition.
Paging and selection¶
- The grid loads 100 rows per page at first. "Per page" in the footer offers 25, 50, 100 and
- The footer shows "Rows 1–100 of 2,936" and the page buttons.
- The check boxes at the start of the rows select records. Shift+click selects a range, Ctrl+click adds a single row. The header check box selects all visible rows. The footer shows "3 selected" and "Clear selection".
- A grid that shows a query result allows several selected rows. A grid inside a form that shows related records follows exactly one record at a time: it has no check boxes, and only a click on a row changes the selected record.
Opening records¶
| Gesture | Effect |
|---|---|
| Click on a row | Opens the record with the default form of its entity. The record header then offers to go back to the list and to the previous and next record. |
| Middle click on a row | Opens the record in a new browser tab |
| Arrow keys, Page up/down, Home/End, Enter | Move the focus between rows; Enter opens the focused row |
Inside a form, a related items grid block can define its own row click (see Forms).
What nexxcite remembers¶
nexxcite stores the layout per user and per grid: hidden columns, column order, widths, sort order, grouping and page size. It applies wherever this grid is shown – on the query result page, on a dashboard and in a form – and on every device the user signs in with. Only what the user actually changed is stored; everything else keeps following the definition, even when an administrator changes it later. Filters are not remembered: a reopened grid starts without column filters.
6. Narrow screens¶
A grid adapts to the width it has, not to the width of the browser window. A grid in a narrow column of a form therefore behaves like a grid on a phone.
| Width of the grid | Effect |
|---|---|
| below about 1,000 pixels | Columns with "Priority" 3 are hidden |
| below about 860 pixels | Columns with "Priority" 2 are hidden as well |
| below about 720 pixels | Every record is shown as a card instead of a row |
A hidden column stays available through "Columns". A card is built from the "Mobile Role" of the columns:
| Mobile role | Place in the card |
|---|---|
| Title | The heading of the card. Only the first column with this role; further ones go to the subtitle line. |
| Subtitle | The line below the heading |
| Badge | A chip next to the heading – for a status or a priority |
| Detail | Listed with its heading. Empty values are left out. |
| Hidden | Not shown in the card |
Without a title column, the first text column without a width is the heading of the card.
Recommendation: give the column users read first the role Title, a status the role Badge, and set "Priority" 2 or 3 on columns that are not needed on a small screen.
7. Toolbars and actions¶
The "Toolbar" of a grid is an app bar (see App bars). Its buttons behave like this:
| Button | Behaviour |
|---|---|
| Action of the same entity as the grid, grid shows a query result | The action runs once for all selected rows. While no row is selected, the button is disabled. Afterwards the rows are reloaded. |
| Action of the same entity, grid inside a form (related records) | The action runs against the record of the form |
| Any other action | The action runs without a record – for example "New ticket" |
How an action runs against several records – pre-commands once, commands per record, post-commands once – is described in Actions.
The buttons of a toolbar column always run against the record of their own row.
8. The query result page¶
When an action, an app bar entry or a link opens the result of a query, nexxcite shows it on a page of its own:
- the title (the name of the query) with the entity and the grid below it, for example "Tickets · Ticket overview",
- the buttons of the grid's toolbar to the right of the title,
- "Edit Query" – opens the conditions of the query. "Search" runs it again with the changed conditions. The change applies to this page only; the stored query is not changed.
- "Save query" – keeps the conditions as they are on this page in a collection of the user, see Collections. Shown to users with the permission "Save queries to collections".
- the grid below, filling the rest of the page.
The page has its own address, /query/stored/<query id>?gridId=<grid id>, so it can be bookmarked or
sent to a colleague. Without gridId the "Default Grid" of the entity is used. Clicking a search
result of the AI assistant opens the same page with the default grid.
Additional styles for this page can be set in the global settings under "Search Result Styles" (see Global settings).
9. Exporting records¶
"Export" in the toolbar of the grid offers "Excel (XLSX)", "CSV", "JSON" and "XML".
| Question | Answer |
|---|---|
| Who sees the button? | Users with the permission "Export Query Results" (granted by "System Administrator"), unless the grid has "Disable export" switched on |
| Which records? | All records of the result, not only the current page – with the filters and the sort order the user has set |
| Which columns? | The visible columns in the order the user arranged them, with the value the cell shows. HTML columns are reduced to their text, badge columns deliver their text, toolbar columns are left out. |
| Anything to note? | Excel limits a cell to 32,767 characters; longer values are shortened and end with "...". CSV, JSON and XML keep the full value. CSV files carry a marker so that Excel recognises the characters correctly. |
While the export runs, the button shows "Exporting..." and accepts no further click.
10. Limitations¶
- No editing in the grid. Values are changed in the form of the record, not in a cell.
- Data type of a column: the grid editor does not offer it. Columns created in the editor are treated as text – text filter, left-aligned, sorting as the database sorts the field. The AI assistant can set the data type of a column.
- Fields of related records cannot be shown in a field column. Use an HTML column.
- Search: the grid itself has no full-text search box. Users narrow the rows with filters, quick filters or the query editor of the query result page.
- Widths are pixels only; percentages are ignored.
- Group totals are not counted over the whole result for date columns and empty values.
11. Frequently asked questions¶
Why can a user not sort by a column? Only field columns can be sorted, grouped and filtered. HTML, badge and toolbar columns cannot.
A user has hidden a column and cannot find it again. "Columns" in the toolbar lists every column. "Reset order and widths" restores the layout of the definition.
I changed the sort order of the grid, but a user still sees the old one. The user has sorted the grid themselves; their choice is remembered and wins. It only overrides what the user changed – the user can clear it with "Clear sorting" in the column menu.
Does a grid respect the read limits of a role? Yes. The records come from a query or relationship, and the read limits of the user apply there (see Roles and permissions).
Can I export without the export button? An action can export a query result with a command of its own (see Actions). The button itself only appears with the permission "Export Query Results".