Ga naar hoofdinhoud

CnStatsBlockWidget

Manifest-driven dashboard widget that pulls a count from OpenRegister's GraphQL endpoint and forwards it to CnStatsBlock for rendering. Mounted automatically by CnDashboardPage when a widget definition has type: 'stats-block'.

Since ADR-049 (list-widget-enrichment) the widget also supports a multi-entry mode: an entries[] prop renders N related KPIs inside the one widget card, each entry self-fetching its own token-resolved count over OpenRegister's REST /value aggregation. Exactly one of dataSource / entries must be provided — the single-dataSource path is unchanged.

Manifest example​

{
"id": "minutes-in-review",
"type": "stats-block",
"title": "Notulen ter goedkeuring",
"iconClass": "icon-file",
"props": { "countLabel": "notulen", "variant": "warning" },
"dataSource": {
"register": "decidesk",
"schema": "minutes",
"filter": { "lifecycle": "review" },
"aggregate": "count"
}
}

Multi-entry example (v2 widgets[])​

A grouped-KPI card — three related counts declared as manifest config, no custom component:

{
"widgetKey": "stats-block",
"slot": "body",
"gridX": 0, "gridY": 0, "gridWidth": 4, "gridHeight": 6,
"props": {
"entries": [
{ "title": "Expiring soon", "register": "docudesk", "schema": "document",
"filter": { "retention": { "lt": "@today+30d" } }, "variant": "warning",
"route": { "name": "documents" }, "hideWhenZero": true },
{ "title": "Review required", "register": "docudesk", "schema": "document",
"filter": { "status": "review" }, "hideWhenZero": true },
{ "title": "Archived", "register": "docudesk", "schema": "document",
"filter": { "status": "archived" } }
]
}
}

Each entry carries the same source contract as a type: "stat" widget (register, schema, metric, field, token-resolved filter with @today / @me / @workspace.* and ?-optional clauses), plus per-entry presentation (title, variant, countLabel), an optional route deep link, and hideWhenZero (the entry is omitted from the card when its resolved count is 0).

Money in its own currency (format, currencyField, currency)​

An entry shows its value formatted when it declares format, the same shape as a type: "stat" widget's content.format: a style name ("number", "currency", "percent", "decimal", "duration-hours") or { style, currency, currencyField, decimals, prefix, suffix }. Without one, the plain count shows, as before.

A money value takes its currency, in order, from:

  1. currencyField: the field of the detail page's object that holds it, for example a contract's own currency (dot-paths work).
  2. currency: a code such as "USD", or a token such as "@config.currency" or "@object.currency".
  3. The app's reporting currency: currency in the page's app config.
  4. EUR.

A step without a three-letter code is skipped. currencyField and currency may sit on the entry itself and then imply format: "currency". The amount is formatted with Intl in the user's Nextcloud locale.

{
"id": "contract-value",
"type": "stats-block",
"title": "Contract value",
"content": {
"entries": [
{ "title": "Contract value", "register": "pipelinq", "schema": "salesContract",
"metric": "sum", "field": "value", "filter": { "id": "@objectId" },
"currencyField": "currency", "format": { "style": "currency", "decimals": 2 } }
]
}
}

Drop a countLabel that spelled the currency ("EUR"): the formatted value carries the symbol. The single-KPI mode takes the same shape as its format prop.

Stat tiles in a grid (layout: "grid", stats, columns)​

One card with several figures of any kind a stat widget computes: each entry of stats is a stat tile's content (label, caption, format, source with ratio, elapsed, computed, weighted or endpoint), drawn in columns columns (default 2, 1 to 4), in one card. The card's title is the widget wrapper's: set showTitle: true on the widget. The board's "Je week tot nu toe" card:

{
"id": "my-week",
"type": "stats-block",
"title": "Your week so far",
"showTitle": true,
"content": {
"layout": "grid",
"columns": 2,
"stats": [
{ "label": "Answered", "caption": "this week", "source": { "register": "pipelinq", "schema": "ticket", "metric": "count", "filter": { "assignee": "@me", "status": "resolved", "resolvedAt[gte]": "@today-7d" } } },
{ "label": "Average answer time", "format": { "style": "decimal", "decimals": 1, "suffix": " days" }, "source": { "kind": "elapsed", "register": "pipelinq", "schema": "ticket", "from": "occurredAt", "to": "resolvedAt" } }
]
}
}

By default the tiles are parts of the card, without a box of their own. Set "tiles": "box" to draw each tile on a grey ground with a 10px radius and 14px 16px padding, 12px apart, as board DcRapportages draws "Vergaderingen en efficiëntie":

{ "id": "efficiency", "type": "stats-block", "title": "Meetings and efficiency", "showTitle": true,
"content": { "layout": "grid", "columns": 4, "tiles": "box", "stats": [ ... ] } }

Props​

PropTypeDefaultDescription
dataSourceobjectnullManifest dataSource block (single-KPI mode). See useDataSource. Exactly one of dataSource / entries must be provided.
entriesarray[]Multi-entry declarative sources — one KPI per entry: { title, register, schema, metric, field, filter, route, variant, countLabel, hideWhenZero, format, currency, currencyField }. Mutually exclusive with dataSource.
formatstring|object|nullnullHow the single-KPI value is shown: a style name or { style, currency, currencyField, decimals, prefix, suffix }. See Money in its own currency.
titlestring''Block title (single-KPI mode).
countLabelstring''Label next to the count (single-KPI mode).
variant'default'|'primary'|'success'|'warning'|'error''default'Color variant (single-KPI mode).
showZeroCountbooleantrueShow 0 instead of the empty-label fallback.
horizontalbooleanfalseDeprecated since 2.25.0 — horizontal is the canonical card's own layout, so this prop no longer changes anything.
verticalbooleanfalseStack the icon above a centred number instead of beside it.
filledbooleanfalseDraw each tile's own grey box. Off by default — the widget renders inside a CnWidgetWrapper that already draws a card.
routeobject|nullnullVue-router location; when set, the inner card becomes a <router-link> (single-KPI mode).
iconClassstring''Optional NC core icon class (icon-link, icon-mail, …) applied to the wrapping <div>.
statsarray[]The tiles of layout: "grid": each a stat tile's content, any source kind. See Stat tiles in a grid.
columnsnumber2Columns of layout: "grid" (1 to 4).
tilesstringnull"box": each tile of layout: "grid" on a surface of its own (grey ground, 10px radius, 14px 16px padding). Empty: the tiles are parts of the card, without a box.

Refresh wiring​

The tile subscribes to cn:page:refresh — the channel the page-level Refresh action broadcasts on — and re-runs all three count paths: the REST /value aggregation, the per-entry counts of multi-entry mode, and the dataSource GraphQL query. There is no widget id to match on: a page refresh refreshes everything on the page.

This is the tile's only refresh affordance. CnDashboardPage renders it without CnWidgetWrapper (CnStatsBlock brings its own card chrome), so unlike the other data widgets it has no per-widget Refresh item in an overflow menu.

A ref-callable refresh() is also exposed, for parity with CnChartWidget.

Notes​

  • Designed only for the manifest path. If you already have a count number in JS, mount CnStatsBlock directly.
  • Errors from the underlying GraphQL request fall back to count = 0. The dashboard never blanks on a transport failure.