Dashboards
This page documents dashboard architecture, panel types and the shared filter bar. The Build group doesn't currently carry a dedicated Dashboards subsection — this page is the canonical entry point for the topic.
A dashboard is a single page that groups KPIs, charts and tables over a common context — typically the current period + a chosen scope (a company, a region, a team). Defined from Settings → Dashboards with a drag-and-drop layout grid; each panel picks a data source (a connector query or a saved chart), a panel type (stat / chart / table) and renders accordingly.
The dashboard is the natural surface for executive views ("how are we doing today?") and for operational overviews ("which jobs are running, which screens have the most rejections"). Each panel can drill down to a screen pre-filtered to the underlying rows.
At a glance
The mockup shows the runtime view; the builder behind it is documented below.
Settings → Dashboards
The catalogue lists every dashboard on the install.
Click + New dashboard or any row to open the dashboard builder.
The dashboard builder
A two-pane editor: layout grid on the left (drag-and-drop), panel editor on the right (configures the selected panel).
General fields (top of the editor)
| Field | Effect |
|---|---|
| Id | Identifier — surfaces in the URL (/dashboards/<id>), the menu picker and the permission code (dashboard:<id>). |
| Title | Localised display title. |
| App | App namespace. Drives the workspace the dashboard appears in. |
| Description | Free text. Surfaces on the menu picker. |
| Shared filter bar | Optional list of parameters exposed at the top of the dashboard at runtime. Every panel that references the same parameter inherits the value. |
| Default page | Optional — the dashboard's home page in the same app. Sets a "home" icon on the menu entry. |
Layout grid
A responsive 12-column grid. Each cell is a panel that can span 1–12 columns wide and 1–6 rows tall. The operator drags from a palette of panel types onto the grid:
| Control | Effect |
|---|---|
| Drag from palette | Adds a new panel at the end of the grid. |
| Resize handles | Drag a panel's edge to resize. Snaps to columns. |
| Group label | Optional. Adds a section header before a row of panels — e.g. Sales overview, Operational health. |
| Click a panel | Opens the panel editor on the right. |
| ✕ on a panel | Removes it from the layout. |
| Preview | Renders the full dashboard with live data — useful before saving. |
Panel types
Stat (KPI)
A single number with optional delta vs a previous period.
| Field | Effect |
|---|---|
| Title | Shown above the number. |
| Connector / Query | The source. The query must return at least one row with one numeric column. |
| Value column | Column whose first-row value is rendered as the headline number. |
| Format | Number format ("1 234", "1.2 K", "€ 12 345,00"). |
| Delta column | Optional. A signed number rendered below the value as a coloured ▲ / ▼ chip. |
| Delta direction | Higher is better / Lower is better — drives the colour. |
| Trend sparkline | Optional. Points at a query returning a small time series; rendered as a 10-point sparkline. |
Chart
Wraps a chart definition.
| Field | Effect |
|---|---|
| Chart | Dropdown of charts defined under Settings → Charts. |
| Override parameters | Optional per-panel overrides of the chart's fixed values. |
| Drill-down screen | Optional. Clicking a data point opens the named screen pre-filtered. |
Table
A small, read-only grid (typically 5–20 rows). Useful for "top N" / "recent" lists.
| Field | Effect |
|---|---|
| Connector / Query | The source. |
| Columns | Sortable list of columns to show, with widths and per-column formats. |
| Row limit | Default 20. |
| Click action | Open dialog (uses the linked screen's dialog) / Open screen filtered / None. |
Markdown
Static text block, useful for annotations or contextual explanations between panels.
| Field | Effect |
|---|---|
| Content | Markdown source. |
| Background | None / Subtle (default) / Accent. |
Grid (planned)
Inline screen-style grid with the full filter toolbar. On the roadmap.
The shared filter bar
The top of a dashboard shows a row of inputs derived from the Shared filter bar declared at the top of the builder. Each entry:
| Field | Effect |
|---|---|
| Name | Internal parameter name — panels reference it via ${dashboard.<name>} in their parameter overrides. |
| Label | Shown above the input. |
| Type | string / date / daterange / lookup / enum. Drives the widget. |
| Default | Initial value. Date tokens (${today}, ${month.first}) are accepted. |
| Lookup | When Type is lookup, points at a dictionary lookup. |
Operators set the filter once at the top of the dashboard; every panel inheriting the parameter re-runs with the new value. This is what makes dashboards feel coherent — one input, many panels updated.
Drill-down
Each panel can declare a drill-down screen — clicking the panel (or a specific data point on charts / tables) opens the named screen pre-filtered to the underlying rows. The framework handles the parameter pass automatically: the panel knows what it queried, the screen accepts the same parameter names.
For finer control, the drill-down field accepts a URL pattern with :name placeholders that the framework fills from the click context.
Permissions
A dashboard is gated by dashboard:<id>. Each panel inherits the underlying connector query's permission — a user without sql:billing:monthly-invoice-counts doesn't see the chart panel referencing it. The framework prunes the panel silently rather than rendering an error placeholder, so dashboards remain coherent even when the caller lacks every permission.
The Dashboards builder tab is gated by settings:dashboards.
Tips & best practices
- Lead with stats. The first row of a dashboard should be 3–4 stat panels — the operator's eye lands there first.
- Group with section headers. Two visual rows separated by a Group label read much better than six panels in a wall.
- Keep panels under 12 per dashboard. Past that, the page scrolls and the value of "everything in one place" evaporates. Split into multiple dashboards.
- Use the shared filter bar for time. Most dashboards revolve around a period; expose the date range there once and every panel inherits it.
- Wire drill-downs. A stat that's an island is half the value of a stat that opens the relevant screen.
- Use the Preview button. Catches "this panel has no data on a fresh install" before saving.
Under the hood
Dashboard definitions are stored in liberty-apps/config/dashboards.toml and the underlying charts in charts.toml. Operators do not edit these files by hand in normal operation; the Dashboards builder is the canonical interface, with the Raw TOML tab as the escape hatch for the rare edit a builder gap blocks.
What's next
- Charts — the chart definitions a Chart panel references.
- Screens — the screens a drill-down opens.
- Parameter binding — how the shared filter bar feeds every panel.
- Menus — wire the dashboard into the sidebar.