Dashboards – overview pages built from widgets¶
A dashboard is a page made of widgets: key figures, charts, tables of records, buttons, texts and pictures, arranged in rows, columns and tabs. Users typically land on a dashboard after signing in and start their work from there. This chapter describes how dashboards are built, opened, refreshed and protected, and lists all widget types.
It is intended for administrators who design the entry pages of an application.
1. Dashboards at a glance¶
| Item | Meaning |
|---|---|
| Dashboard | A page of widgets. It is not bound to a record: its widgets show the results of queries, texts, pictures and buttons. |
| Widget | One building block of the dashboard – a layout widget that holds other widgets, or a content widget such as a card, a chart or a grid |
| Dashboard editor | The editor in which the widgets are arranged and configured. It works like the form editor. |
| Opening a dashboard | Through an action, an app bar entry, the "Home Action" of a role or its address |
Dashboards are managed in the Admin Studio under Design → Dashboards. The permissions are "Open Dashboard Manager", "Add Dashboard", "Edit Dashboard" and "Delete Dashboard" (see Roles and permissions).
Summary¶
- A dashboard is a vertical stack of widgets. Rows, columns, grids and tabs are made with layout widgets.
- Widgets that show data run their own queries. The read limits of the viewing user apply, so two users can see different numbers on the same dashboard.
- A widget can refresh itself on a clock of its own. The dashboard as a whole is not reloaded.
- Opening a dashboard requires no permission of its own. What a user may see is decided by the data behind the widgets.
2. Creating a dashboard¶
- Open Admin Studio → Design → Dashboards and create a dashboard.
- Add widgets with "Add Widget Block". The first level of widgets is placed one below the other.
- Select a widget in the block tree or in the preview and set its properties on the right.
- Save with "Save & Close" (or "To Sketch & Close" while a sketch is open).
The dashboard editor has the same parts as the form editor – palette, block tree, preview, property panel, clipboard, undo and redo. They are described in Forms. The preview runs the real queries, so it shows real numbers.
Dashboard properties¶
"Dashboard Properties" holds what belongs to the dashboard as a whole:
| Setting | Meaning |
|---|---|
| "Display Name", "Description", tags, "Icon" | Name and description of the dashboard. The page title is the name followed by "(Dashboard)". |
| "Parameters" | Values the dashboard takes when it is embedded in another dashboard as a stored block (section 7) |
| "Stylesheet" | CSS for this dashboard only, computed by an expression |
| "CSS Classes" | CSS classes for the root of the dashboard |
3. Opening a dashboard¶
| Way | How |
|---|---|
| App bar | An item whose action navigates to the dashboard (see App bars) |
| After signing in | The "Home Action" of the user's role navigates to the dashboard |
| Action | The navigation command of an action, target "Dashboard" (see Actions) |
| Address | /dashboards/<dashboard id> – can be bookmarked and sent |
| Admin Studio | "Open" in the dashboard management view |
An address of a dashboard that does not exist leads to the "not found" page.
4. Layout¶
The dashboard itself is a vertical stack: its widgets are placed one below the other. For anything else, use layout widgets:
| Layout | Widget |
|---|---|
| Widgets side by side, wrapping on narrow screens or in columns per screen width | Horizontal Stack |
| A column of widgets, optionally foldable | Vertical Stack |
| A grid with columns and rows, widgets spanning several cells | Grid Layout |
| One line that scrolls instead of wrapping | Scroll Strip |
| Several views in the same space | Tab |
| The same widgets once per element of a list | Repeater |
Typical structure: a horizontal stack with four cards (key figures) at the top, below it a horizontal stack with two charts, below that a query result grid with the records to work on.
The columns per screen width, container queries and folding work as in forms; details and recommendations are in Forms.
5. Settings every widget has¶
Besides its own settings, every widget has these. They are the same as for form blocks.
| Setting | Category | Meaning |
|---|---|---|
| "Display Name" | – | The name of the widget in the editor. It also names the variables of a repeater. |
| "Visible" | – | Condition under which the widget is shown |
| "CSS Styles", "CSS Classes" | – | Inline styles and CSS classes, computed by expressions |
| "Show Background" | Appearance | Draws the widget on a card-like background |
| "Auto Refresh", "Refresh Interval (s)" | – | The widget loads itself again on a clock (section 6). Not offered on layout widgets. |
| "Tooltip" | Appearance | Text shown when the pointer rests on the widget |
| "Size" | Size | Width, height, minimum and maximum, each as a CSS length or an expression |
| "Padding", "Margin" | Spacing | Inner and outer spacing |
| "Flush" | Spacing | Only on label, button and search field: drops the default spacing of 8 pixels around the widget |
| "Border", "Border Color" | Border | Border widths, style, radius and colour |
| "Font Size", "Font Weight", "Text Align", "Text Color" | Typography | The text of the widget |
| "Text Decoration", "Text Transform" | Typography | Underline, overline or line-through; letter case for display (Uppercase, Lowercase, Capitalize). Only the display changes, the stored value stays as it is. |
| "Background Color", "Shadow", "Opacity" | Appearance | The surface of the widget |
| "Align Self", "Column Span", "Row Span" | Layout | Position inside the parent stack or grid layout |
Colours can be picked as fixed values or as colour tokens that follow the theme (see Themes).
6. Refreshing¶
When a dashboard loads its data¶
A dashboard loads all its widgets when it is opened. Afterwards nothing changes on its own – unless a widget has "Auto Refresh" switched on. Reloading the page in the browser loads the whole dashboard again.
Auto refresh¶
| Setting | Meaning | Default |
|---|---|---|
| "Auto Refresh" | The widget loads itself again at regular intervals while the dashboard is open | off |
| "Refresh Interval (s)" | Seconds between two refreshes. A value below 1 switches the refresh off. | 30 |
Only the widget itself is loaded and redrawn; the rest of the dashboard stays as it is.
| Widget | What a refresh does |
|---|---|
| Card, chart, accumulation chart | Calculates its values again |
| Query result grid, query result list | Loads its rows again. Sort order, filters and selection are kept. |
| Query results, catalog | Searches again with the text the user typed |
| Embedded page | Reloads the page |
| Label, HTML, image, badge, button, app bar, search field | Evaluates its expressions again |
| Vertical and horizontal stack, grid layout, scroll strip, repeater, tab, skeleton, AI assistant | Not refreshed – set the refresh on the widgets inside a container |
If a refresh fails, the widget keeps the last values and tries again at the next interval.
Pick the coarsest interval that is good enough. Every refresh runs the queries of the widget again – once for every user who has the dashboard open. A wallboard that 50 people keep open with four widgets every 10 seconds runs 20 queries per second.
Drilling down¶
A click on the number of a card, on a point of a chart or on a slice of an accumulation chart opens the records behind it in a dialog, shown with the default grid of the entity.
7. Reusing dashboards¶
A stored dashboard can be placed inside another dashboard as a block, the same way stored blocks are reused in forms (see Forms). With "Parameters" in the dashboard properties, the embedded dashboard takes values from the dashboard that embeds it – for example a region or a team – and its widgets read them like variables. When such a dashboard is opened on its own, its parameters take their default values.
A dashboard cannot contain itself, directly or through other dashboards; such a block is left out.
8. Data and permissions¶
- Opening a dashboard requires no permission. Everybody who has the address or a menu entry can open it. Control who sees the entry with the "Visible" condition of the app bar item or with the roles' app bars.
- Every widget that shows records runs its query with the read limits of the viewing user. Records a user may not read are neither shown nor counted.
- Buttons and app bars run their actions with the permissions of the user, like everywhere else.
- A dashboard has no record of its own. Expressions of widgets cannot read fields of a "current record"; they work with queries, global values, the current user and the parameters of the dashboard.
A widget that cannot be drawn – for example because a referenced query was deleted – is left out; the rest of the dashboard is shown.
9. Widget types¶
The widgets as they are named in the palette "Add Widget Block":
Layout¶
| Widget | Purpose |
|---|---|
| Vertical Stack Block | Widgets one below the other |
| Horizontal Stack Block | Widgets side by side, in columns per screen width |
| Grid Layout Block | Widgets in a grid with column and row spans |
| Repeater Block | Its widgets once per element of a JSON array |
| Scroll Strip Block | One line that scrolls |
| Tab Block and Tab Item Block | Tabs or an accordion |
| Element Block | Not drawn at present |
Data¶
| Widget | Purpose |
|---|---|
| Card Block | One key figure: a count, a sum, an average, a duration |
| Chart Block | Lines, bars or columns over an x axis |
| Accumulation Chart Block | A doughnut chart: records per value of a field |
| Query Result Grid Block | The records of a query as a grid |
| Query Result List Block | The records of a query as a list |
| Query Results Block | One form per record, optionally with full-text search |
| Catalog Block | Tiles with search, filter chips and groups |
Content and interaction¶
| Widget | Purpose |
|---|---|
| Label Block | A text |
| HTML Block | HTML computed by an expression |
| Image Block | A picture or an icon |
| Badge Block | A short value as a coloured chip |
| Button Block | A button that runs an action |
| App-Bar Block | The buttons of an app bar |
| Search Field Block | A search input that hands its text to an action |
| Embedded Page Block | An external web page |
| AI Assistant Block | A chat with an AI assistant |
| Skeleton Block | A placeholder while content is loading |
A calendar widget exists in the data model but is neither offered in the editor nor drawn.
10. Limitations¶
- A dashboard has no record context; for pages about one record, use a form.
- The "Element Block" is offered in the palette but not drawn on dashboards. Use a stack instead.
- Charts draw lines, bars and columns only (see Chart Block).
- There is no button that reloads the whole dashboard; use "Auto Refresh" on the widgets or reload the page.
- Opening a dashboard cannot be restricted by a permission of its own.
11. Frequently asked questions¶
Two users see different numbers on the same card. Is that an error? No. Every widget queries with the read limits of the viewing user (see Roles and permissions).
How do I make a dashboard the start page? Create an action that navigates to the dashboard and select it as "Home Action" of the role.
Can a dashboard show the records of the signed-in user only? Yes. Use a query whose condition compares a field with the current user (see Queries).
Why does my new tab widget show nothing? Its "Display Style" is not set yet. Choose "Tab" or "Accordion" (see Tab Block).
Does auto refresh keep running when the browser tab is in the background? It runs as long as the dashboard is open and the connection to nexxcite exists. Browsers may slow down or suspend background tabs; what they do is decided by the browser.