CnDashboardPage
Top-level dashboard page component — the dashboard equivalent of CnIndexPage. Assembles a complete dashboard from a widgets definition array and a layout array. Supports custom widgets via scoped slots, Nextcloud Dashboard API widgets, tile widgets, and an optional drag-and-drop edit mode.
Wraps: CnDashboardGrid, CnWidgetWrapper, CnWidgetRenderer, CnTileWidget
Try it
Widget types
| Type | How to use |
|---|---|
| Tile | Widget def has type: 'tile' — renders as a quick-access link tile |
| Custom | Provide a #widget-{widgetId} scoped slot (escape hatch — beats every built-in branch when a slot exists) |
| Chart | Widget def has type: 'chart' — declarative apexcharts mount via CnChartWidget; chart inputs ride widgetDef.props |
| NC Dashboard API | Widget def has itemApiVersions — auto-rendered via CnWidgetRenderer |
The dispatcher resolves widgets in that order. The custom-slot branch beats the chart branch so apps that need bespoke apexcharts behaviour outside the manifest contract can fall back to #widget-{id} without losing the rest of the manifest.
How content reaches a registry widget
A widget resolved through the registry (cnRegistry, the dashboard catalog or a built-in) gets its whole content as the content prop. Of the individual content keys, it gets only the ones its renderer declares as props, so a key the widget does not know can never land on its root component and override what the widget computes there. A widget that declares neither the key nor content would not see it at all, so outside production the page warns once per widget type and key in that case.
A renderer with inheritAttrs: false forwards its attributes itself and keeps receiving every key. For a custom widget, read the configuration from content, or declare a key as a prop to receive it directly.
Chart widget
const WIDGETS = [{
id: 'sla-trend',
title: 'SLA trend',
type: 'chart',
props: {
chartKind: 'line', // line | bar | donut | area | pie | radialBar
series: [{ name: 'SLA %', data: [82, 88, 91, 93] }],
categories: ['Q1', 'Q2', 'Q3', 'Q4'],
options: { stroke: { width: 3 } }, // deep-merged with CnChartWidget defaults
height: 280,
// Reserved for a future cycle — not read at render time today:
// dataSource: { url: '/index.php/apps/myapp/api/charts/sla' }
// dataSource: { register: 'cases', schema: 'case', groupBy: 'caseType', aggregate: 'count' }
},
}]
Forwarded props keys (everything else is ignored): chartKind (→ type), series, categories, labels, options, colors, toolbar, legend, height, width, unavailableLabel.
Usage
<template>
<CnDashboardPage
title="Dashboard"
:widgets="WIDGETS"
:layout="layout"
:loading="loading"
:allow-edit="true"
@layout-change="saveLayout"
@edit-toggle="onEditToggle">
<!-- Custom widgets -->
<template #widget-kpis="{ item }">
<CnKpiGrid :items="kpiData" />
</template>
<template #widget-cases-chart="{ item }">
<CnChartWidget type="pie" :series="chartSeries" :labels="chartLabels" />
</template>
<!-- Per-widget header actions -->
<template #widget-kpis-actions="{ item }">
<NcButton type="tertiary" @click="refreshKpis">Refresh</NcButton>
</template>
<template #header-actions>
<NcButton @click="addWidget">Add widget</NcButton>
</template>
</CnDashboardPage>
</template>
<script>
const WIDGETS = [
{ id: 'kpis', title: 'Key Metrics', type: 'custom' },
{ id: 'cases-chart', title: 'Cases by status', type: 'custom', iconClass: 'icon-chart' },
]
const DEFAULT_LAYOUT = [
{ id: 1, widgetId: 'kpis', gridX: 0, gridY: 0, gridWidth: 12, gridHeight: 2, showTitle: false },
{ id: 2, widgetId: 'cases-chart', gridX: 0, gridY: 2, gridWidth: 6, gridHeight: 4 },
]
</script>
Use the useDashboardView composable to manage widget state and layout persistence:
import { useDashboardView } from '@conduction/nextcloud-vue'
const { widgets, layout, loading, onLayoutChange } = useDashboardView({
widgets: WIDGETS,
defaultLayout: DEFAULT_LAYOUT,
loadLayout: () => loadFromConfig('dashboard_layout'),
saveLayout: (l) => saveToConfig('dashboard_layout', l),
})
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | String | '' | Page title |
description | String | '' | Description shown below the title |
breadcrumb | Object | Array | null | A breadcrumb under the title (manifest config.breadcrumb): one crumb { label, route?, params?, href?, icon?, separator? } or a list; the title follows as the current crumb. Drawn as the detail header's breadcrumb row. |
headerMeta | String | '' | A note after the breadcrumb and a middle dot (manifest config.headerMeta). |
widgets | Array | [] | Widget definition objects (see Widget definition below) |
layout | Array | [] | Grid placement objects (see Layout item below) |
loading | Boolean | false | Show loading spinner instead of the grid |
allowEdit | Boolean | false | Show the Edit/Done toggle button |
columns | Number | 12 | Number of grid columns |
cellHeight | Number | 80 | Grid cell height in pixels |
gridMargin | Number | 12 | Gap between grid items in pixels |
editLabel | String | 'Edit' | Label for the edit button. A manifest label goes through the app's translate ("Edit layout" reads "Indeling aanpassen" where the app has it), as does doneLabel. |
doneLabel | String | 'Done' | Label for the done button |
emptyLabel | String | 'No widgets configured' | Empty state message |
unavailableLabel | String | 'Widget not available' | Fallback for unknown widget IDs |
headerActions | Array | [] | Declarative header actions (manifest config.headerActions) rendered as buttons through CnActionButtons. An entry with href is a link button, never dispatched: an absolute http(s), mailto:, tel: or //host/... URL as written, an instance path through generateUrl(), in a new tab with target: "_blank". On a dashboard the href may carry @workspace.<key> tokens, filled URL-encoded from the page filters, so a download asks for what the page shows (/apps/dossiq/api/report?format=csv&from=@workspace.dateFrom) — see CnIndexPage. |
headerActionsViewport | String | '' | "wide" keeps the header actions and the buildiq square off a phone (under 640px, the breakpoint a widget's viewport uses), "narrow" off a wider window. Empty draws them everywhere. PqMobiel's My work header holds only the title. |
dateRange | Object | null | Optional date-range header descriptor — see Date-range header |
pageFilters | Array | [] | Optional page-level filter controls rendered in the header — see Page filters. Each entry \{ key, label?, type?: 'select', options: [\{ value, label \}], default? \}. The selection is written into the reactive workspace context, so widgets can read it via a @page.<key> / @workspace.<key> token. |
A widget definition's own headerActions ([{ label, icon?, variant?, visibleWhen?, action }]) draw as buttons in its card's title row. Under CnPageRenderer a click goes through the page's dispatcher (cnDispatchAction), as on a detail page, so action: { "type": "open-modal", "target": "<RegistryDialog>" } opens that app dialog (DqCatalogus "Importeren" on the Uit de Store card); outside the renderer it dispatches with the page's router.
Widget definition
| Field | Type | Description |
|---|---|---|
id | String | Unique widget identifier |
title | String | Widget title shown in the wrapper header |
type | String | 'custom' (default), 'tile', or 'chart'. 'chart' mounts CnChartWidget; chart inputs ride props |
props | Object | Free-form widget-specific props. For chart widgets: { chartKind, series, categories, labels, options, colors, toolbar, legend, height, width, unavailableLabel, dataSource? } |
iconUrl | String | Header icon image URL |
iconClass | String | Header icon CSS class |
titleIconPosition | String | Position of the widget-{id}-title-icon slot: 'left' (before title) or 'right' (after actions, default) |
titleIconColor | String | CSS color applied to the title-icon slot container (e.g. '#e74c3c') |
buttons | Array | Footer buttons: [{ text, link }] |
itemApiVersions | Number[] | NC Dashboard API versions — triggers auto-rendering |
reloadInterval | Number | Auto-refresh interval in seconds (NC widgets) |
Layout item
| Field | Type | Description |
|---|---|---|
id | String | Number | Unique placement ID |
widgetId | String | References a widget id from the widgets array |
gridX | Number | Column start (0-based) |
gridY | Number | Row start (0-based) |
gridWidth | Number | Width in grid columns |
gridHeight | Number | Height in grid rows |
showTitle | Boolean | Whether to show the wrapper header (default true) |
flush | Boolean | Whether the widget body renders flush — edge-to-edge with no wrapper content padding. Default true for dashboard content widgets (tables, KPIs, charts, custom/integration), so a borderless table or KPI meets the card edges. Set flush: false to restore the padded box for content that needs breathing room. |
dateChip | Boolean | Show the per-widget date-range chip (see Per-card date chip) |
showActions | Boolean | Forwarded to CnWidgetWrapper — set false to drop the header overflow menu on compact tiles |
styleConfig | Object | Style overrides passed to CnWidgetWrapper |
Events
| Event | Payload | Description |
|---|---|---|
layout-change | layout[] | Emitted when the user drags or resizes a widget; payload is the full updated layout array |
edit-toggle | boolean | Emitted when the Edit/Done button is clicked; payload is the new editing state |
date-range-change | { from, to, preset } | Emitted on every range change AND on mount when the date-range feature is enabled. Tracks the picker's current value. |
page-filter-change | { key, value } | Emitted when a page filter selection changes. The value is also written into the reactive workspace context. |
Slots
| Slot | Scope | Description |
|---|---|---|
header-actions | — | Extra buttons in the page header (right side) |
title-meta | — | Content on the title's row, right of the title, such as a page-wide picker. A manifest fills it with page.slots: { "title-meta": "<RegistryName>" } |
widget-{widgetId} | { item, widget } | Custom content for a specific widget |
widget-{widgetId}-actions | { item, widget } | Header action buttons for a specific widget |
widget-{widgetId}-title-icon | { item, widget } | Extra icon in the widget header; position and color controlled by titleIconPosition / titleIconColor on the widget definition |
empty | — | Custom empty state when no layout items exist |
Date-range header
When the dateRange prop is set with enabled: true, the dashboard renders a CnDateRangePicker between the page header and the widget grid. The selected range is:
- emitted on every change via
@date-range-change, - optionally persisted to
localStorage(whenpersistKeyis set), - provided to every descendant widget through the
cnDashboardDateRangeinjection key as a reactive Vue ref, - published into the page-level workspace context as
dateFrom/dateTo/datePreset, so any declarative widget can scope itself to the active window via the optional filter tokens@workspace.dateFrom?/@workspace.dateTo?(see Re-scoping KPI counts).
<CnDashboardPage
title="Dashboard"
:widgets="WIDGETS"
:layout="layout"
:date-range="{
enabled: true,
persistKey: 'myapp.dashboard.range',
default: { preset: 'last-7' },
}"
@date-range-change="onRangeChange" />
dateRange shape
| Field | Type | Description |
|---|---|---|
enabled | Boolean | When true, renders the picker row. When false / omitted, no row appears. |
control | String (opt.) | Header control style: 'picker' (default — CnDateRangePicker: a preset select + two date inputs) or 'pills' (a compact segmented toggle-button row). |
placement | String (opt.) | 'description' puts the segmented period group at the end of the description line, after a middle dot ("Week 41 · alle teams · [Deze week | Dit kwartaal]"), instead of in a row of its own. Ignored with a custom range, which keeps its row. |
default | Object (opt.) | Initial { from, to, preset? } when no persisted state is found. |
persistKey | String (opt.) | When set, the chosen range is persisted to localStorage[persistKey]. |
presets | Array (opt.) | Override the preset list. See DEFAULT_DATE_RANGE_PRESETS. A preset with no numeric days / hours (other than the manual custom entry) — e.g. { id: 'all', label: 'All', days: null } — or one with clear: true is an "All" / clear option that removes the window. |
The resolution order is: explicit default → rehydrated localStorage (when persistKey set) → last-7 preset (now − 7d → now).
Re-scoping KPI counts by the active window
The chosen range is published into the page-level workspace context as
dateFrom / dateTo / datePreset. A declarative widget (e.g. a stat
KPI tile) scopes its query to the window by referencing the OPTIONAL tokens in
its source.filter on whichever date field it tracks:
{
"type": "stat",
"content": {
"label": "Decisions",
"route": { "name": "Decisions" },
"source": {
"register": "decidesk", "schema": "decision", "metric": "count",
"filter": {
"decisionDate": { "gte": "@workspace.dateFrom?", "lte": "@workspace.dateTo?" }
}
}
}
}
The trailing ? marks each token OPTIONAL: when the "All" preset clears the
window (empty bounds) the token stays unresolved and is dropped, so the date
filter is omitted and the tile shows its unfiltered count.
Per-card date chip (layout[].dateChip)
Instead of (or alongside) the page-level header control, a KPI card can carry
its own period selector. Set dateChip: true on the widget's layout entry.
When the card shows its header (showTitle not false) the chip sits in the
header next to the title; on a flush card (showTitle: false) it floats in
the top-right corner over the content — so a compact KPI tile keeps its clean
look and still gets a date selector. This works for the registered card widgets
(stat / gauge / delta) and any custom-slot widget. The chip opens the same preset popover and drives the same shared
dashboard range, so every card stays in sync. Its label shows the active
preset (e.g. 7d / 30d / All) and it stays clickable even on the
unbounded "All" range. Pair with dateRange.showHeaderPicker: false to drop
the page-level control and rely solely on the per-card chips:
{
"config": {
"dateRange": {
"enabled": true,
"showHeaderPicker": false,
"default": { "preset": "all" },
"presets": [
{ "id": "last-7", "label": "7d", "days": 7 },
{ "id": "last-30", "label": "30d", "days": 30 },
{ "id": "all", "label": "All", "days": null }
]
},
"layout": [
{ "id": "1", "widgetId": "decisions-kpi", "gridX": 0, "gridY": 0, "gridWidth": 3, "gridHeight": 2, "showTitle": true, "dateChip": true }
]
}
}
A preset with no numeric days / hours (other than custom) — e.g.
{ id: "all", days: null } — or one flagged clear: true clears the window.
Pills control (control: 'pills')
control: 'pills' replaces the bulky select + two date inputs with a compact
segmented toggle row — one pill per preset, rendered as role="group" with
aria-pressed on the active pill (WCAG-friendly toggle group). A
de-emphasised "Custom range" pill (dashed outline) opens a small from/to
popover, so the arbitrary-window affordance stays without two bare date inputs
sitting in the header. The active pill drives the same shared dashboard range
as the default picker — no other wiring changes.
<CnDashboardPage
:date-range="{
enabled: true,
control: 'pills',
default: { preset: 'last-30' },
presets: [
{ id: 'last-7', label: 'Last 7 days', days: 7 },
{ id: 'last-30', label: 'Last 30 days', days: 30 },
{ id: 'last-90', label: 'Last 90 days', days: 90 },
{ id: 'custom', label: 'Custom range', days: null },
],
}" />
cnDashboardDateRange provide / inject
CnDashboardPage always provides cnDashboardDateRange — even when the feature is off — so descendants can inject without a fallback dance:
import { inject, ref } from 'vue'
export default {
setup() {
const range = inject('cnDashboardDateRange', ref(null))
// range.value is `{ from, to, preset }` when the feature is on,
// and `null` when it's off.
return { range }
},
}
CnChartWidget consumes this injection automatically — see its bucket data-source documentation.
Page filters
The pageFilters prop renders page-level select controls in the dashboard header. Each selection is written into the reactive workspace context (the same cnWorkspaceContext provide widgets read), so any widget can react to it through a @page.<key> / @workspace.<key> token. This is how a single period selector drives every endpoint-bound KPI on the page.
<CnDashboardPage
title="Analytics"
:widgets="WIDGETS"
:layout="layout"
:page-filters="[
{
key: 'period',
label: 'Period',
type: 'select',
default: 'last-30',
options: [
{ value: 'last-7', label: 'Last 7 days' },
{ value: 'last-30', label: 'Last 30 days' },
],
},
]"
@page-filter-change="onPeriodChange" />
A widget then binds its data to the selected value. With an endpoint-bound stat widget:
{
"id": "leads", "type": "stat",
"content": {
"label": "Leads",
"source": { "kind": "endpoint", "url": "/api/analytics/summary", "path": "totalLeads", "params": { "period": "@page.period" } }
}
}
Each entry: key (the context key written on change), optional label, type (only 'select' today), options ([{ value, label }]), and an optional default (else the first option seeds the context on mount). Omitting pageFilters renders nothing and leaves the context untouched (backwards-compatible). The label and the option labels go through the app's translate.
With placement: "description" a filter sits on the header's description line instead of in the filter row: a select as a compact select, one with control: "segmented" as a segmented group. They stand in the order the page declares them (DqProcesanalyse: "Gemiddeld | Mediaan", then "Laatste 12 maanden" and "Alle zaaktypen"), before a dateRange period group on the same line. A select is set off by a middle dot from a segmented group that follows it, not from another select.
Options read from a source (optionsFrom)
A filter can read its options instead of listing them, as the case-type filter of a reporting dashboard does:
{ "key": "caseType", "label": "Filter by case type", "clearable": true, "placeholder": "All case types",
"optionsFrom": { "register": "dossiq", "schema": "caseType", "filter": { "hasSla": true } } }
optionsFrom is { register, schema, filter? } (OpenRegister objects; tokens in filter resolve) or { url, params?, responsePath? } (an app endpoint). valueField and labelField pick the option's value and label (default the id or uuid, and title or name). clearable: true lets the reader clear the select back to all: the context key becomes null and nothing is seeded on mount, and placeholder says what an empty select means. A filter that is not clearable is seeded with the first option read.
A quarter filter (type: "quarter")
{ "key": "quarter", "label": "Quarter", "type": "quarter", "count": 8 }
The filter generates its own options: the current quarter first, then the count - 1 quarters before it (default 8 in all). Each is valued YYYY-Qn, the form a quarterly report endpoint reads, and labelled "Q2 2026". The current quarter is seeded on mount, so a widget reading @workspace.quarter has a value on its first read. type: "year" does the same for years: the current year first, count years in all (default 5), valued YYYY.
Built-in page-level Actions menu
The dashboard header carries the shared CnActionsMenu overflow … — Refresh, Documentation, and Request a feature — next to the edit toggle. This is the page-level menu, distinct from each widget's own menu (the per-widget ones emit @widget-refresh / @widget-request-feature).
- Refresh emits
@refreshand, unless suppressed viaevent.preventDefault(), fires thecn:page:refreshevent-bus channel with{ widgetId, title }. - Documentation renders only when
documentationUrlis set, opening it in a new tab. - Request a feature opens the forge's feature-request issue form with the
dashboard:<id>surface as its English headline, when mounted underCnAppRoot.
Refresh and Request-a-feature are on by default for the page-level menu; opt out with :show-refresh="false" / :show-request-feature="false". Set :page-id for a stable id/surface.
Per-widget Refresh
Each widget's own overflow menu shows Refresh based on widgetShowRefresh (tri-state, default null = auto). For custom-slot widgets, auto shows Refresh only when the app attached a @widget-refresh listener that will handle it — so a dashboard that refreshes centrally by another route (e.g. a header button bumping a shared signal) gets no dead per-widget buttons. Force all custom widgets on/off with :widget-show-refresh="true"/false. Built-in chart / NC / integration widgets always show Refresh (they refresh via the cn:widget:refresh bus or their renderer).
:show-refresh="false" (or config.showRefresh: false in a manifest) also drops the Refresh item from every widget's own overflow menu — handy for a read-only dashboard whose widgets have no refetch wired (Request-a-feature stays). A widget can override this individually with showRefresh / hideRefresh on its widgets[] definition or layout[] entry:
// page Refresh off, but this one widget keeps it
widgets: [{ id: 'live-feed', type: 'custom', showRefresh: true }]
// page Refresh on, but drop it from a static section
widgets: [{ id: 'revenue-over-time', type: 'custom', hideRefresh: true }]
Each per-widget menu also surfaces a Documentation item. Its URL resolves to the widget def's own documentationUrl when set, otherwise it inherits the page-level documentationUrl — so a documented dashboard shows Documentation on every widget without per-widget config.
In-body sections (bodyWidgets)
The bodyWidgets prop hosts registered host-app section components alongside the widget grid — the dashboard equivalent of CnDetailPage's bodyWidgets. This is how a bespoke analytics dashboard (a custom funnel / time-series / channel-bar chart that reads its own REST endpoint) becomes a type: "dashboard" page without rewriting the charts — the chart stays a registered component and surfaces as an in-body section.
Each section resolves its component from the v2 cnRegistry (any entry exposing a .component) first, then the legacy cnCustomComponents map — the same resolver type: "custom" pages use. No sidebar tab is required (unlike integration widgets). A name in neither registry renders an inline error; the page never breaks. Reuses CnBodySections.
{
"type": "dashboard",
"config": {
"bodyWidgets": [
{ "id": "funnel", "component": "ConversionFunnel", "title": "Funnel",
"placement": "before-grid",
"props": { "period": "@workspace.period", "currency": "@config.currency" } },
{ "id": "channels", "component": "ChannelBarChart", "placement": "after-grid", "colSpan": 6 }
]
}
}
placement—before-grid(above the grid, renders even when there are no grid widgets),after-grid(below it), orend(the default; the last body content). Each section renders exactly once.props— token-resolved against the page context:@workspace.<key>/@page.<key>(page-level workspace state, e.g. apageFiltersselection),@config.<key>(app config, see below), plus the time /@me/@objectIdtokens. An unresolved optional token (@workspace.<key>?) is dropped so the child seesundefined.colSpan— 1–12 grid span when sections at one placement share a row.
The section context ({ register, schema, objectId, workspace, config }) is also provided on cnSectionContext, so a section component can inject('cnSectionContext') instead of taking explicit props. The optional object scoping (register / schema / objectId) comes from integrationContext.
App config tokens (@config.<key>)
The appConfig prop is a page-level config map exposed to declarative widget / section config via the @config.<key> token, and provided to descendants on cnAppConfig. Its primary use is making a setup-wizard-captured value (e.g. the reporting currency) actually format the dashboards instead of a hard-coded EUR:
{
"id": "revenue", "type": "stat",
"content": {
"label": "Revenue",
"source": { "kind": "endpoint", "url": "/api/finance/revenue", "path": "total" },
"format": { "style": "currency", "currency": "@config.currency", "decimals": 0 }
}
}
<CnDashboardPage :widgets="WIDGETS" :layout="layout" :app-config="appConfig" />
A manifest renderer typically seeds appConfig from loadState(appId, 'config', {}). @config.<key> also interpolates into an endpoint source's URL / params and into OpenRegister filter values. It is backwards-compatible: a literal "EUR" still works, and a required @config.<key> that is unset falls back to the format's default (EUR for currency, empty for prefix/suffix) rather than rendering the raw token. A trailing ? marks the token optional (dropped from filters when unset). The page merges its own appConfig over a config an ancestor provides on cnAppConfig (an app root's settings), key by key, so an app can provide its settings once. A registry widget's content takes the token too, at any depth: { "type": "kb-search", "content": { "space": "@config.xwiki_default_space?" } } searches the admin's default space, and an unset optional token becomes empty.
Each per-widget menu also surfaces a Documentation item. Its URL resolves to the widget def's own documentationUrl when set, otherwise it inherits the page-level documentationUrl — so a documented dashboard shows Documentation on every widget without per-widget config.
In-body sections (bodyWidgets)
The bodyWidgets prop hosts registered host-app section components alongside the widget grid — the dashboard equivalent of CnDetailPage's bodyWidgets. This is how a bespoke analytics dashboard (a custom funnel / time-series / channel-bar chart that reads its own REST endpoint) becomes a type: "dashboard" page without rewriting the charts — the chart stays a registered component and surfaces as an in-body section.
Each section resolves its component from the v2 cnRegistry (any entry exposing a .component) first, then the legacy cnCustomComponents map — the same resolver type: "custom" pages use. No sidebar tab is required (unlike integration widgets). A name in neither registry renders an inline error; the page never breaks. Reuses CnBodySections.
{
"type": "dashboard",
"config": {
"bodyWidgets": [
{ "id": "funnel", "component": "ConversionFunnel", "title": "Funnel",
"placement": "before-grid",
"props": { "period": "@workspace.period", "currency": "@config.currency" } },
{ "id": "channels", "component": "ChannelBarChart", "placement": "after-grid", "colSpan": 6 }
]
}
}
placement—before-grid(above the grid, renders even when there are no grid widgets),after-grid(below it), orend(the default; the last body content). Each section renders exactly once.props— token-resolved against the page context:@workspace.<key>/@page.<key>(page-level workspace state, e.g. apageFiltersselection),@config.<key>(app config, see below), plus the time /@me/@objectIdtokens. An unresolved optional token (@workspace.<key>?) is dropped so the child seesundefined.colSpan— 1–12 grid span when sections at one placement share a row.
The section context ({ register, schema, objectId, workspace, config }) is also provided on cnSectionContext, so a section component can inject('cnSectionContext') instead of taking explicit props. The optional object scoping (register / schema / objectId) comes from integrationContext.
App config tokens (@config.<key>)
The appConfig prop is a page-level config map exposed to declarative widget / section config via the @config.<key> token, and provided to descendants on cnAppConfig. Its primary use is making a setup-wizard-captured value (e.g. the reporting currency) actually format the dashboards instead of a hard-coded EUR:
{
"id": "revenue", "type": "stat",
"content": {
"label": "Revenue",
"source": { "kind": "endpoint", "url": "/api/finance/revenue", "path": "total" },
"format": { "style": "currency", "currency": "@config.currency", "decimals": 0 }
}
}
<CnDashboardPage :widgets="WIDGETS" :layout="layout" :app-config="appConfig" />
A manifest renderer typically seeds appConfig from loadState(appId, 'config', {}). @config.<key> also interpolates into an endpoint source's URL / params and into OpenRegister filter values. It is backwards-compatible: a literal "EUR" still works, and a required @config.<key> that is unset falls back to the format's default (EUR for currency, empty for prefix/suffix) rather than rendering the raw token. A trailing ? marks the token optional (dropped from filters when unset). The page merges its own appConfig over a config an ancestor provides on cnAppConfig (an app root's settings), key by key, so an app can provide its settings once. A registry widget's content takes the token too, at any depth: { "type": "kb-search", "content": { "space": "@config.xwiki_default_space?" } } searches the admin's default space, and an unset optional token becomes empty.
Reference (auto-generated)
The tables below are generated from the SFC source via vue-docgen-cli. They reflect what's actually in CnDashboardPage.vue and update automatically whenever the component changes.
OpenRegister reliance
heavy: this component cannot work without OpenRegister. 4 direct references, 229 files reached through imports.
Through: CnActionButtons, CnActionDialog, CnActionsMenu, CnAnalyticsReportPicker, CnAssignDialog, CnAuditTrailCard, CnBannerWidget, CnBookmarkPicker, CnBuildiqEditButton, CnBulkJobProgress, CnCalendarEventCreate, CnCalendarEventPicker, CnCellRenderer, CnChartWidget, CnChartWidgetForm, CnChecklistRunWidget, CnChildRecordsField, CnCollectivePageCreate, CnCollectivePagePicker, CnConflictResolveCard, CnContactPicker, CnCospendCreate, CnCospendPicker, CnCreateFormWidget, CnDataTable, CnDeckCardCreate, CnDeckCardPicker, CnDeltaWidgetForm, CnDetailWidgetHost, CnEmailPicker, CnEventsCard, CnExportsWidget, CnFactsWidget, CnFieldListWidget, CnFilesBrowser, CnFilesCard, CnFilesWidget, CnFkResolveCell, CnFlowDetail, CnFlowOperationPicker, CnFlowRunsWidget, CnFlowRunsWidgetForm, CnFormDialog, CnGaugeWidgetForm, CnGraphCanvas, CnIndexPage, CnIndexSidebar, CnIntegrationWidget, CnInteractionFormWidget, CnKbSearchWidget, CnMacrosWidget, CnMapPoiPicker, CnMapWidget, CnMapWidgetForm, CnMenuWidget, CnNavCardGrid, CnNoteComposer, CnNotesCard, CnObjectDataWidget, CnObjectFilesWidget, CnObjectGeoWidget, CnObjectLinksWidget, CnObjectListWidget, CnObjectListWidgetForm, CnObjectMetadataWidget, CnObjectPartiesWidget, CnObjectSidebar, CnOpenProjectCreate, CnOpenProjectPicker, CnPartyPicker, CnPhotoAlbumPicker, CnPlanWidget, CnPollPicker, CnRecordListWidget, CnRecordNotesWidget, CnRegisterSchemaSelect, CnRelatedFieldFilters, CnRelatedObjectsWidget, CnResourceSelect, CnRetentionWidget, CnSchemaFormDialog, CnSchemaRulesWidget, CnSettingsFormWidget, CnSlotGrid, CnStackedBarWidgetForm, CnStagesWidget, CnStagesWidgetForm, CnStatWidget, CnStatWidgetForm, CnStatsBlockWidget, CnStatsBlockWidgetForm, CnTabsWidget, CnTagsCard, CnTalkRoomPicker, CnTaskFormDialog, CnTasksCard, CnTasksWidget, CnTemplateSelect, CnTimeTrackerCreate, CnTimeTrackerPicker, CnTimelineWidget, CnTranslatedBadge, CnVersionHistory, CnWeekStripWidget, CnWeekStripWidgetForm, CnWidgetObjectTable, CnWidgetRefItem, CnWorkingCalendarWidget, CnWorkspaceFilterWidget, CnXwikiPageCreate, CnXwikiPagePicker.
See the reliance overview for the filterable list.
Props
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
views | Array<{id: string, label: string, title?: string, icon?: string, widgets?: Array<object>, layout?: Array<object>, emptyText?: string}> | [] | Views of this page, each its own widget grid behind one segmented control. Each is { id, label, icon?, widgets, layout, emptyText? }: widgets and layout have the same shape as the page's own. The chosen view renders in a region below the page's own grid. Empty (the default) draws no switch and no region. A view's title is the page title while that view is open (on a dashboard). | |
defaultView | string | '' | The id of the view chosen when neither the address nor the browser store names one. Empty chooses the first view. | |
viewsLabel | string | '' | Accessible name of the view switch (through the host translate function). Empty reads "View". | |
title | string | '' | Page title | |
breadcrumb | union | null | A breadcrumb under the title (manifest config.breadcrumb): one crumb { label, route?, params?, href?, icon?, separator? } or a list; the title follows as the current crumb. Drawn as the detail header's breadcrumb row. Null (the default) draws none. | |
headerMeta | string | '' | A note after the breadcrumb and a middle dot (manifest config.headerMeta). | |
headerPills | Array<{label: string, variant?: string, when?: object}> | [] | Pills at the start of the line under the title (manifest config.headerPills): [{ label, variant?, when? }], when a workspace condition; a pill without one always shows. | |
titleWhen | Array<{when: object, title: string}> | [] | Titles that replace title while a page control's value holds (manifest config.titleWhen): [{ when, title }], when a workspace condition ({ workspace, op?, value? }) and title a template whose {workspace.<key>} reads the page's workspace ("Gesprek met {workspace.selectedClientName}" while a call is on, PqWerkplekKlant). The first entry whose condition holds and whose tokens all fill wins. | |
layoutWhen | Array<{when: object, layout: Array<object>, gridColumnWeights?: Array<object>}> | [] | Layouts that replace layout while a page control's value holds (manifest config.layoutWhen): [{ when, layout }], when a workspace condition ({ workspace, op?, value? }) as in titleWhen. The first entry whose condition holds draws its own arrangement of the page's widgets (PqWerkplekKlant: three columns while a call is on). Editing the page shows the page's own layout. | |
description | string | '' | Page description (shown below title) | |
descriptionSource | {url: string, path?: string}|null | null | The description read from an app endpoint (manifest config.descriptionSource): { url, path? }, the text at path (default text) of the answer replaces description once it arrives (PqMijnWerk "negen items liggen bij jou: ..."). An unreadable answer keeps description. | |
showHeader | boolean | true | Whether the header row renders: title, description, header actions and the edit toggle. false (manifest config.showHeader: false) drops it for a page whose first widget is its heading; the title then renders visually hidden so the page keeps an accessible name. | |
kpiRow | Array<string> | [] | The ids of the widgets that form the KPI row above the grid (manifest config.kpiRow). They render in an auto-fit CnKpiGrid and are left out of the GridStack grid and of the emitted layout. An id that names no widget is skipped with a development warning. | |
kpiColumns | union | 'auto' | The columns of the KPI row (manifest config.kpiColumns): 2, 3 or 4 at full width (PqLoyaliteit draws eight tiles in two rows of four), or "auto" for as many 200px columns as fit. | |
greeting | union | false | Greet the reader in the header subtitle (manifest config.greeting): true (or "first") writes "Good afternoon, Pieter · Monday 5 October 2026", "full" uses the whole display name. The page description, when set, follows after another middle dot. Off by default: the subtitle is the description alone, as before. "date" leads with the date alone, and { label } puts the translated label where the greeting would be ("Customer contact · Wednesday 7 October 2026 · ..."). | |
viewLinks | Array<object> | [] | Links drawn as small pills on the switch row under the header (manifest config.viewLinks), as DqMijnWerk's "Uw wachtrij / Aan mij toegewezen / Dag afsluiten". Each { label, icon?, route?, href? }: route is a route name or a { name, params?, query? } location, href a plain URL; label goes through the host translate function. An entry without a label or a target is skipped. | |
showActionsMenu | boolean | true | Whether the header draws the page Actions menu (manifest config.showActionsMenu). false removes it, for a board page whose header carries only the buildiq square and the primary. | |
showWidgetActions | boolean | true | Whether a widget draws its overflow Actions menu when neither its placement nor its definition says (showActions). false (manifest config.showWidgetActions: false) drops the menu from every such widget, for a dashboard whose widgets carry a header link and nothing else. A widget that sets showActions: true keeps its menu. Card widgets have no menu either way. | |
gridFloat | boolean | true | GridStack's float for this dashboard (manifest config.gridFloat). True (the default) keeps every widget on its row. False packs widgets upward, so a size-to-content widget that shrinks closes the gap under it instead of leaving an empty band. | |
gridSideColumn | object | null | A side column of a fixed width for the page's own grid (manifest config.gridSideColumn): { width, from? }, see CnDashboardGrid's sideColumn. A view declares its own gridSideColumn, because two views of one page can split differently (DqMijnWerk 320px beside the main column, DqMijnTeam two halves). | |
gridColumnWeights | array | null | Weights for groups of the grid's twelve columns (manifest config.gridColumnWeights): [{ span, weight }], see CnDashboardGrid's columnWeights. A layoutWhen entry can carry its own gridColumnWeights for the layout it draws (PqWerkplekKlant in a call: 332 / 415 / 332). | |
widgets | Array<{ id: string, title: string, type: string, iconUrl: string, iconClass: string, buttons: Array, itemApiVersions: number[], reloadInterval: number, props: object }> | [] | Widget definitions array. Each widget defines metadata for rendering. Custom widgets: { id: 'my-widget', title: 'My Widget', type: 'custom' } NC API widgets: { id: 'calendar', title: 'Calendar', itemApiVersions: [1,2], ... } Tile widgets: { id: 'tile-files', type: 'tile', title: 'Files', icon: 'M12...', iconType: 'svg', backgroundColor: '#0082c9', textColor: '#fff', linkType: 'app', linkValue: 'files' } Chart widgets: { id: 'sla', type: 'chart', title: 'SLA trend', props: { chartKind: 'line', series: [{ name: 'SLA %', data: [82, 88, 91] }], categories: ['Q1', 'Q2', 'Q3'], options: { stroke: { width: 3 } } } } | |
layout | union | [] | Layout array defining widget positions in the grid. Each item: { id: 'unique-id', widgetId: 'my-widget', gridX: 0, gridY: 0, gridWidth: 4, gridHeight: 3 } Additional properties (showTitle, styleConfig, tile config) are passed through. | |
content | Array<{ type: string, ref: string }> | [] | Declarative content items. Each item is a widget-ref entry from the manifest's pages[].config.content[] array: { type: 'widget-ref', ref: 'openregister://widget/<schemaSlug>/<widgetSlug>' } CnDashboardPage renders each widget-ref item as a CnWidgetRefItem which resolves the widget from OR's registry at runtime and renders the resolved component. Only widget-ref entries are processed; unknown type values are skipped with a console.warn. When both content (widget-ref items) and widgets+layout (classic GridStack layout) are present, content items are rendered above the grid in a stacked list. | |
bodyWidgets | Array<{id?: string, component: string, title?: string, props?: object, placement?: string, colSpan?: number}> | [] | Declarative IN-BODY sections (host-app section components) rendered ALONGSIDE the widget grid — the dashboard equivalent of CnDetailPage's bodyWidgets. Each entry: { id?, component, title?, props?, placement?, colSpan? } - component — registry name resolved from the v2 cnRegistry first, then the legacy cnCustomComponents map (the SAME resolver type:"custom" pages use). A bespoke funnel / time-series / channel chart that reads a custom REST endpoint stays a registered component and surfaces here without a rewrite. - props — token-resolved against the page context: @workspace.<key> / @page.<key> (page-level workspace state), @config.<key> (app config), and the time / @me tokens. An unresolved optional token is dropped so the child sees undefined. - placement — before-grid (above the widget grid) | after-grid (below it) | end (the default; same as after-grid). before-grid renders even when the dashboard has no grid widgets. - colSpan — 1–12 grid span when sections at one placement share a row. Empty / omitted (default []) renders nothing — the current behaviour. The section context ({ register, schema, objectId, workspace, config }) is also provided on cnSectionContext so a section component can inject it instead of taking explicit props. See CnBodySections. | |
appConfig | object | \{\} | Page-level app config map exposed to declarative widget / section config via the @config.<key> token (e.g. the reporting currency the setup wizard captures). Provided to descendants on cnAppConfig, so a stat widget's format: { style: 'currency', currency: '@config.currency' } formats with the configured value (falling back to the literal default — EUR — when unset) and an endpoint KPI's URL can interpolate @config.<key>. A manifest renderer typically seeds this from loadState(appId, 'config', {}). Empty (default) leaves every @config.<key> token to fall back to its literal default. | |
loading | boolean | false | Whether the dashboard is loading | |
allowEdit | boolean | false | Whether to show the edit toggle button | |
columns | number | 12 | Number of grid columns | |
cellHeight | number | 80 | Grid cell height in pixels | |
gridMargin | number | 12 | Grid margin in pixels | |
editLabel | string | () => t('nextcloud-vue', 'Edit') | Label for the edit button | |
doneLabel | string | () => t('nextcloud-vue', 'Done') | Label for the done button (when editing) | |
emptyLabel | string | () => t('nextcloud-vue', 'No widgets configured') | Label for the empty state | |
unavailableLabel | string | () => t('nextcloud-vue', 'Widget not available') | Label for unavailable widgets | |
surface | string | 'app-dashboard' | Rendering surface forwarded to integration widgets (widgets whose type === 'integration'). Drives the AD-19 surface fallback on resolveWidget(integrationId, surface). | |
integrationContext | union | null | Object context forwarded to integration widgets: { register, schema, objectId }. Optional — most dashboards aren't object-scoped, but CnDetailPage passes one through so CnFilesCard / CnTagsCard / CnAuditTrailCard know which object's sub-resources to fetch. | |
appStatuses | union | null | Optional per-app install/enable status map used by the requiresApp widget gate. Shape: { [appId]: { installed: boolean, enabled: boolean, category?: string } } — typically the dependency_statuses initial state a consuming app injects. When a widget definition carries requiresApp (a string or array of app ids) and a required app is not enabled here, that widget renders an "Install …" call-to-action instead of its normal content. When this prop is null the gate falls back to the isAppInstalled() runtime check (OC.appswebroots → capabilities), so the gate works with or without injected data. | |
dateRange | union | null | Optional date-range header descriptor. When enabled: true the dashboard renders a CnDateRangePicker between the header and the widget grid, persists the chosen range to localStorage (when persistKey is set), emits @date-range-change on every change, AND provides a reactive cnDashboardDateRange ref to every descendant widget. When the prop is null (default), false, or { enabled: false }, the header row is NOT rendered and the existing dashboard layout stays unchanged. The provide is still installed (always) but its value stays null so descendant chart widgets fall back to their dataSource.bucket.staticRange (or skip the query entirely). Shape: ts { enabled: boolean, control?: 'picker' | 'pills', default?: { from: string, to: string, preset?: string }, persistKey?: string, presets?: Array<{ id: string, label: string, days: number|null }>, } control selects the header control style: the default 'picker' renders the CnDateRangePicker (a preset select + two date inputs); 'pills' renders a compact segmented toggle-button row (one pill per preset, plus a de-emphasised "Custom range" popover pill). Both drive the same shared range. A preset with no numeric days / hours (other than the manual custom entry) — e.g. { id: 'all', label: 'All', days: null } — is an "All" / CLEAR preset: picking it removes the window so date-bound widgets show their unfiltered count. An explicit clear: true forces the same behaviour. The active window is published into the page-level workspace context as dateFrom / dateTo / datePreset, so any declarative widget can scope itself to it via the optional filter tokens @workspace.dateFrom? / @workspace.dateTo? (an empty bound, i.e. the "All" range, drops the token so the filter is omitted). Default preset when no explicit default and no persisted state is found: last-7 (now − 7d → now). Per-widget surfacing: chart widgets with a dataSource.bucket get an in-header date chip automatically; CUSTOM and registered card widgets (stat / gauge / delta KPI tiles) opt in via layout[].dateChip: true (same popover, writes the same shared range — so an abstract KPI card carries its own period selector). The chip needs the widget header (showTitle !== false) and shows the active preset's label (e.g. 7d / All), staying clickable even on an unbounded ("All") range. Set showHeaderPicker: false to rely solely on the per-widget chips. | |
actionsPlacement | string | 'end' | Where the page's own actions component (actionsComponent, the #actions slot) sits in the board-look header row: end (default, rightmost) or start (first, before the secondary actions and the buildiq square), as PqDashboard draws its availability toggle. | |
headerActions | Array<object> | [] | Optional declarative header actions (#91 Wave 3) rendered as buttons in the dashboard header via CnActionButtons — open-form (schema create dialog), api-call (POST/PUT + toast + refresh), toggle (two-way state button), navigate / open-modal / refresh, each with an optional visibleWhen predicate. An entry with href is a link button, never dispatched: an absolute http(s), mailto:, tel: or //host/... URL as written, an instance path (leading /) through generateUrl(), in a new tab with target: '_blank'. Empty (the default) renders nothing; the #header-actions slot still works alongside it for bespoke buttons. | |
headerActionsViewport | string | '' | Where the header actions and the buildiq square draw: "wide" keeps them off a phone (under 640px, PqMobiel's My work header holds only the title), "narrow" off a wider window. Empty draws them always. | |
pageFilters | union | [] | Optional page-level filter controls rendered in the dashboard header. Each selection is written into the reactive page-level workspace context (the same bag cnWorkspaceContext provides), so any widget can read it via a @page.<key> / @workspace.<key> token — e.g. a period selector that every endpoint-bound KPI's URL interpolates. Each entry: { key, label?, type?: 'select', control?, placement?, options: [{ value, label }], default? }. key is the workspace-context key written on change; default (or the first option) seeds it on mount. The control is a select, or with control: 'segmented' a compact segmented group; placement: 'description' puts a segmented group on the header's description line, after the period group (DqProcesanalyse "Gemiddeld | Mediaan"), and a select before it (DqDoorlooptijd "alle zaaktypen"). An endpoint widget can read the value in its responsePath too (phaseDays.@workspace.measure). optionsFrom reads the options instead of listing them: { url, params?, responsePath?, valueField?, labelField? } from an app endpoint, or { register, schema, filter?, valueField?, labelField? } from OpenRegister objects (value id, label title or name by default; tokens resolve). clearable: true lets the reader clear the select back to "all" (placeholder, e.g. "All case types"), which writes null and seeds nothing. type: 'quarter' generates its options: the current quarter first, then count - 1 (default 7) before it, valued YYYY-Qn and seeded with the current one; type: 'year' does the same for years (default 5, valued YYYY). Empty (the default) renders no controls and leaves the context untouched. control: 'none' seeds its value like any page filter but draws no control: a fixed period the widgets read and the description names ({filter.<key>}). | |
showRefresh | boolean | true | Show the built-in Refresh item in the page-level overflow Actions menu. On by default. The default handler emits @refresh and, unless suppressed, fires the cn:page:refresh event-bus channel — which the built-in data widgets subscribe to, so the action works with no host wiring at all. A @refresh listener that calls preventDefault() replaces that default rather than adding to it. This is ALSO the default for each widget's own overflow menu: when false, the Refresh item is dropped from every widget too (handy for a read-only dashboard whose widgets have no refetch wired — Request-a-feature stays). A widget can still opt back in (or out) individually via showRefresh / hideRefresh on its definition or layout entry. | |
widgetShowRefresh | union | null | Show the built-in Refresh item on each custom-slot widget (distinct from the page-level showRefresh). Tri-state: - true / false — force it on or off for all custom widgets. - null (the default) — auto: show it only when the app using CnDashboardPage attached a @widget-refresh listener (i.e. it will actually handle the refresh). Apps that refresh widgets centrally by another route (e.g. a header button bumping a shared signal) leave it unset and get no dead per-widget buttons. Built-in chart / NC / integration widgets always show Refresh (they refresh via the cn:widget:refresh bus or their renderer). | |
showRequestFeature | boolean | true | Show the built-in Request-a-feature item in the page-level overflow Actions menu. On by default; opens the forge's feature-request issue form when mounted under CnAppRoot. | |
showReportBug | boolean | true | Show the built-in "Report a bug" item in the page-level overflow Actions menu. On by default — the trio Request a feature / Report a bug / Documentation is the contract for every Conduction surface. | |
showDocumentation | boolean | true | Show the built-in Documentation item in the page-level overflow Actions menu. On by default; the shared menu resolves the target itself, so leaving it on costs the host nothing. | |
documentationUrl | string | '' | Explicit documentation link for this dashboard, opened in a new tab. Usually unnecessary: the page-level menu builds one from the app-wide documentation base and the page id. | |
documentationLabel | string | () => t('nextcloud-vue', 'Documentation') | Pre-translated label for the Documentation action. Defaults to "Documentation". | |
pageId | string | '' | Stable id for this dashboard, used in the @refresh / @request-feature payloads and the surface: "dashboard:<id>" field on the feature-request modal. Falls back to a slugified title when unset. | |
userLayout | boolean | false | Whether this page keeps a per-user layout. Off by default and opted into with one manifest key, config.userLayout: true. A page without it makes NO layout request and renders exactly as it did before this existed, which is the property that makes shipping it safe on every dashboard at once. Deprecated: layout belongs to Buildiq. Kept working for one release. | |
appId | string | '' | The Nextcloud app id the user layout is stored under. Required for userLayout to do anything: a preference has to be addressed to an app, and storing one under an empty app id writes a record nothing ever reads back. | |
userLayoutStore | union | null | Reads and writes the current user's layout record. Injected so the component needs no store of its own and a test needs no HTTP: pass { load, save, reset }, or leave it and the page falls back to the dashboardLayoutsPlugin shape over user preferences. | |
specRef | string | '' | Optional specRef slug. Accepted for backward compatibility with hosts that bound it for the removed in-product suggestion modal; no longer forwarded anywhere (the forge issue form asks for its own context). | |
refreshing | boolean | false | Whether a page-level refresh is in flight (disables the Refresh item and shows its spinner). | |
refreshLabel | string | () => t('nextcloud-vue', 'Refresh') | Pre-translated label for the Refresh action. | |
requestFeatureLabel | string | () => t('nextcloud-vue', 'Request a feature') | Pre-translated label for the Request-a-feature action. | |
actionsMenuLabel | string | () => t('nextcloud-vue', 'Actions') | Pre-translated aria-label / tooltip for the overflow menu trigger. |
Events
| Name | Payload | Description |
|---|---|---|
page-filter-change | — | Emitted when a page-level filter selection changes. |
view-layout-change | — | Emitted when a widget in a view's grid is dragged or resized. |
view-layout-reset | — | Emitted when the user drops their arrangement of a view and it returns to the manifest layout. |
date-range-change | — | Fired whenever the dashboard's effective date range changes (initial resolve, picker change, or persisted-range restore). Payload: { from, to, preset }. |
edit-toggle | — | Emitted when the user toggles edit mode. Payload: true when entering edit mode, false when leaving. |
layout-change | — | Emitted when the user finishes dragging/resizing a widget. Payload: the updated layout array [{ widgetId, x, y, w, h }, ...]. |
user-layout-reset | — | Emitted when the user drops their own arrangement and the page returns to the manifest layout. |
refresh | undefined | User clicked Refresh in the page-level overflow Actions menu. Payload: { widgetId, title }. Handlers may call the second arg's preventDefault() to suppress the built-in default (event-bus emit on cn:page:refresh). |
request-feature | undefined | User clicked Request a feature in the page-level overflow Actions menu. Payload: { widgetId, title }. Handlers may call the second arg's preventDefault() to suppress the built-in default (opening the forge's feature-request issue form). |
widget-refresh | — | User clicked Refresh in a widget's overflow action menu. Payload: the layout item descriptor. |
widget-remove | undefined | Emitted when a widget is removed via the in-place editor. |
widget-request-feature | — | User clicked Request a feature in a widget's overflow action menu. Payload: the layout item descriptor. |
Slots
| Name | Bindings | Description |
|---|---|---|
title-meta | — | title-meta Content on the title's row, right of the title (e.g. a page-wide picker). Fill it from a manifest with page.slots: { "title-meta": "<RegistryName>" }. |
actions | — | actions Back-compat alias for #header-actions. Prefer #header-actions in new code. |
header-actions | — | header-actions Inline buttons rendered in the dashboard header next to the edit toggle. Used by every existing consumer (decidesk, launchpad, opencatalogi, pipelinq, procest). |
action-items | — | |
empty | — | empty Replaces the default empty state shown when the dashboard has no widgets. Defaults to an NcEmptyContent block. |
'widget-' + item.widgetId | name, item, widget | widget-{widgetId} Per-widget body content (e.g. #widget-my-work). Apps inject custom widget rendering here. Scope: { item, widget }. |
'widget-' + item.widgetId + '-title-icon' | name, item, widget | |
'widget-' + item.widgetId + '-actions' | name, item, widget |
Hiding the header row (showHeader)
| Prop | Type | Default | Description |
|---|---|---|---|
showHeader | Boolean | true | false (manifest config.showHeader: false) drops the header row: title, description, header actions and the edit toggle, for a page that opens with its own heading such as a greeting widget. The title stays as a visually hidden heading so the page keeps an accessible name. |
A widget definition or layout entry can carry headerLink ({ label, route?, params?, query?, href? }); the page forwards it to CnWidgetWrapper, which draws it as a text link in the widget header. A registry widget that reports its own header (the header event of record-list and facts: the link with the total filled in, a note such as "3 in totaal", one action) gets it on its dashboard card as on a detail page; a headerLink on the placement or the definition still wins over the reported link.
Views behind a switch (views)
A dashboard can offer a few views of its content, such as "My work | My team". Each view is its own widget grid. A segmented control picks one, and the chosen view renders in a region below the page's own grid.
| Prop | Type | Default | Description |
|---|---|---|---|
views | Array | [] | The views. Empty draws no switch and no region. |
defaultView | String | '' | The view that opens when the address and the stored choice name none. Empty opens the first. |
viewsLabel | String | '' | The accessible name of the switch. Empty reads "View". |
- Each view is
{ id, label, icon?, emptyText?, widgets, layout }.widgetsandlayouthave the same shape as the page's own and render with the same grid. - The page's own
widgetsandlayoutstay above the region. Choosing a view swaps only the region. - The chosen view is in the address (
?view=<id>, so a link opens it) and in the user's preferences (the app's preferences endpoint, mirrored in the browser). The address wins, then the stored choice, thendefaultView, then the first view. - The switch is a radio group named by
viewsLabel(default "View"). Every option carriesaria-controlspointing at the region, aregionlandmark named after the chosen view. Arrow keys, Home and End move the choice and focus stays on the switch. - A view with nothing to draw shows its
emptyText, else "This view has no widgets yet.", never a blank area.
The switch sits in the page header. With showHeader: false it gets a row of its own above the grids. When a greeting header widget in the page's own widgets has options with view, the greeting draws the switch and the page draws none. This is the layout of the design board: greeting with the switch, an attention card, then the view.
{
"id": "Dashboard", "type": "dashboard", "route": "/",
"config": {
"showHeader": false,
"widgets": [
{ "id": "greeting", "type": "header", "content": { "greeting": true, "showDate": true, "ground": true,
"views": { "ariaLabel": "Whose work", "options": [{ "label": "My work", "view": "mine" }, { "label": "My team", "view": "team" }] } } },
{ "id": "first-today", "type": "banner", "content": { "layout": "attention", "title": "Cases past their deadline" } }
],
"layout": [
{ "id": "1", "widgetId": "greeting", "gridX": 0, "gridY": 0, "gridWidth": 12, "gridHeight": 2 },
{ "id": "2", "widgetId": "first-today", "gridX": 0, "gridY": 2, "gridWidth": 12, "gridHeight": 2 }
],
"defaultView": "mine",
"views": [
{ "id": "mine", "label": "My work",
"widgets": [{ "id": "my-open", "type": "stat", "title": "My open cases", "content": { "source": { "register": "dossiq", "schema": "case", "metric": "count", "filter": { "assignee": "@me" } } } }],
"layout": [{ "id": "m1", "widgetId": "my-open", "gridX": 0, "gridY": 0, "gridWidth": 3, "gridHeight": 2 }] },
{ "id": "team", "label": "My team", "emptyText": "Your team has no open cases.",
"widgets": [{ "id": "team-open", "type": "stat", "title": "Team open cases", "content": { "source": { "register": "dossiq", "schema": "case", "metric": "count" } } }],
"layout": [{ "id": "t1", "widgetId": "team-open", "gridX": 0, "gridY": 0, "gridWidth": 3, "gridHeight": 2 }] }
]
}
}
A drag or resize in a view's grid while editing is written back into that view's layout, and the page emits view-layout-change with { view, layout }.
Each view arranged per user (userLayout)
Deprecated: layout belongs to Buildiq. Arranging a page is Buildiq's job (Ruben, 18 Oct 2026): its Indeling aanpassen edits the layout everybody sees.
userLayoutstill works for this release and will be removed after it. While Buildiq edits the page (cnEditingBody), the grid shows the manifest layout, and a drag or resize goes into the manifest Buildiq saves, also on a page withuserLayout. A user arrangement made outside an in-page edit session is saved at once, because no Done follows to save it.
With config.userLayout: true a user arranges each view for themselves, exactly as they arrange the page's own grid:
- In edit mode the view grid is draggable too. A drag moves the user's copy of the view, never the manifest
layout. - Leaving edit mode stores every view the user moved, once, as a user preference under
dashboard-layout.<page>.view.<view>(the server, mirrored in the browser, through the samedashboardLayoutsPlugincalls as the page's own grid). The next visit opens with it. - The manifest decides which widgets a view has; the record only moves them.
- Edit mode shows Reset layout. It returns the page's own grid and the chosen view to the manifest and emits
user-layout-resetandview-layout-resetwith{ view }. Other views keep the user's arrangement.
{ "id": "Dashboard", "type": "dashboard", "config": { "userLayout": true, "views": [ ... ] } }
The page needs an app id to store under: its appId prop, else the one CnAppRoot provides.
Dropping the widget menus (showWidgetActions)
| Prop | Type | Default | Description |
|---|---|---|---|
showWidgetActions | Boolean | true | false (manifest config.showWidgetActions: false) drops the overflow Actions menu from every widget that does not set showActions itself, for a dashboard whose widget headers carry a headerLink and nothing else. A widget with showActions: true keeps its menu. |
In the board look showWidgetActions: false also drops the Add footer of the list widgets (table, object-list): they receive allowCreate: false unless their content sets allowCreate itself. This holds on a config.widgets dashboard too, where the catalog widgets (banner, table, stat and the rest) mount through the widget registry next to tile, chart and stats-block widgets.
A header widget whose content sets ground: true is drawn without a card; see CnHeaderWidget.
gridFloat, showButtons and stacked stats blocks (zuiddrecht-pixel-gaps-3)
gridFloat(manifestconfig.gridFloat, defaulttrue):falsepacks widgets upward, so a size-to-content widget that shrinks closes the gap under it.gridSideColumn(manifestconfig.gridSideColumn, and per viewviews[].gridSideColumn):{ width, from? }draws the layout entries withtrack: "side"at a fixed width and those withtrack: "main"in the rest (DqMijnWerk: side cards 320px); entries without a track keep the twelve shares. A view without one keeps the twelve shares (DqMijnTeam's two halves).- A placement or widget definition with
showButtons: falserenders without its footer links. - A
stats-blockdefinition withcontent.layout: "stacked"(orprops.layout) renders its blocks in the stacked board look.
The board look (look: "board")
With the app in the board look (cnLook, from screens-chrome-parity) the page
draws the dashboard of the screens (canon sections 2 and 7). Without it nothing
below changes.
- Header. The title is an
h1of 28px/700 and the description a 15px grey line under it. The buttons are 40px high with a 10px gap, in this order: view switch, Edit layout, Actions, the buildiq square, then the manifest'sheaderActions(and the#header-actionsslot) with the primary rightmost. - Period as a segmented group.
dateRange.control: "segmented"renders the presets as one compactCnSegmentedControlnamed "Period", each segment witharia-pressed, in a row of its own under the header. Acustompreset becomes the last segment and opens the from/to popover. It runs the same range change as a pill (persistence,date-range-change,cnDashboardDateRange). WithdateRange.placement: "description"the group ends the description line instead ("Week 41 · alle teams · [Deze week | Dit kwartaal | Dit jaar]"). - Widget subtitle. A widget definition's
subtitleis a muted line under the card's title ("Dit kwartaal, beslist binnen de termijn"), the counterpart ofeyebrowabove it. - KPI row.
config.kpiRowlists widget ids that render above the grid, in that order, in aCnKpiGridwithcolumns="auto"(repeat(auto-fit, minmax(200px, 1fr)), gap 16). They are not GridStack items and are not part of the emitted layout; in edit mode the row stays fixed. An id that names no widget is skipped with a development warning.
{
"config": {
"kpiRow": ["kpi-new", "kpi-waiting", "kpi-deadline", "kpi-published"],
"dateRange": { "enabled": true, "control": "segmented", "presets": [
{ "id": "last-7", "label": "7 days" }, { "id": "quarter", "label": "Quarter" }
] }
}
}
The KPI tile in this look is described in the CnStatWidget docs.
Greeting, switch row and the Actions menu (screens-dashboard-greeting-header)
| Prop | Type | Default | Description |
|---|---|---|---|
greeting | Boolean | String | Object | false | true or "first" (manifest config.greeting) writes the header subtitle as "Good afternoon, Pieter · Monday 5 October 2026", followed by the description after another middle dot. "full" uses the whole display name. "date" leads with the date alone, capitalised ("Tuesday 7 October 2026 · ..."), and { "label": "Customer contact" } puts the translated label where the greeting would be ("Customer contact · Wednesday 7 October 2026 · ..."), since manifest schema 2.111.0. |
viewLinks | Array | [] | Small pills on a row under the header (manifest config.viewLinks): each { label, icon?, route?, href? }, route a route name or a location. The label is an i18n key. An entry without a label or a target is skipped. |
showActionsMenu | Boolean | true | false removes the page Actions menu from the header. |
In the board look the page view switch (views) sits on the same row, left of the pills, instead of among the header actions.
{ "greeting": true, "showActionsMenu": false, "allowEdit": false, "viewLinks": [{ "label": "Your queue", "icon": "TrayFull", "route": "Queue" }] }
On a phone
Under the board look, below 640px, the grid reflows to one column in reading order (top to bottom, then left to right) and the page does not scroll sideways. A widget that grows when its content wraps, such as a bar of chips, sets sizeToContent: true in its layout item. The compact chips wrap and are 44px high, the bar's switch and select are 44px, and record-list rows, KPI tiles and the widget Actions button are at least 44px. Without the board look the grid keeps its fixed columns.
A widget definition's borderless drops its card: true everywhere, "narrow" on a phone only, "wide" on a wider window only. It applies when the layout placement sets no borderless of its own, and it is the only way for a kpiRow widget, which has no placement (PqMobiel's filter bar).
A title per view (views[].title)
A view can carry a title: while that view is open, the page heading reads it instead of the page's own title
(board DqMijnTeam: "Mijn werk" becomes "Mijn team"; manifest schema 2.119.0). It goes through the app's translate. A view without one keeps the
page title.
{ "views": [{ "id": "mine", "label": "My work" }, { "id": "team", "label": "My team", "title": "My team" }] }