Skip to main content

CnWidgetObjectTable

CnWidgetObjectTable is the built-in v2 widget that exposes CnDataTable to the manifest layer. All data props and listeners are forwarded; since ADR-049 (list-widget-enrichment) it additionally carries a declarative self-fetching source, the compact list surface, and declarative row/widget actions[] — so a fleet dashboard list can be expressed entirely as a manifest widget entry with no bespoke component.

Import​

import { CnWidgetObjectTable } from '@conduction/nextcloud-vue'

Manifest usage​

Referenced via widgetKey: "object-table" in a v2 manifest page's widgets[] array:

{
"id": "my-cases",
"slot": "body",
"widgetKey": "object-table",
"gridX": 0, "gridY": 0, "gridWidth": 6, "gridHeight": 6,
"props": {
"source": {
"register": "@resolve:tenant_register",
"schema": "case",
"filter": { "assignee": "@me", "status": "@workspace.openStatus?" },
"order": { "dueDate": "asc" },
"limit": 5
},
"columns": [
{ "key": "title", "label": "Case" },
{ "key": "dueDate", "label": "Due", "formatter": "daysUntil" }
],
"hideHeader": true,
"rowRoute": "case-detail",
"viewAllRoute": { "name": "cases" },
"emptyText": "No open cases",
"actions": [
{ "id": "accept", "label": "Accept", "type": "object-op", "op": "patch", "values": { "status": "accepted" } },
{ "id": "remove", "label": "Remove", "type": "object-op", "op": "delete" },
{ "id": "add", "label": "New case", "type": "object-op", "op": "create", "values": { "status": "open" } }
]
}
}

When CnPageRenderer mounts the page, CnWidgetGrid resolves the object-table key against BUILT_IN_WIDGETS, instantiates this wrapper, and passes the props map through.

Declarative source (self-fetch)​

source ({ register, schema, filter, order, limit, extend }, default null) drives CnDataTable's existing self-fetch — the widget does not re-implement fetching:

  • filter is token-resolved with the shared resolveFilterTokens grammar just before fetching: @me, @today, @workspace.<key>, @objectId / @object.<field> (on detail pages). A ?-suffixed optional token that resolves to empty drops its clause (dropOptionalUnresolved) instead of failing the fetch; an unresolved required token skips the fetch entirely. Since Wave 3 the @objectId / @object.<field> tokens resolve from either detail surface: CnDetailPage's cnObjectContext ref (which wins per field) or CnPageRenderer's v2 cnDetailObjectContext holder (which backfills), so a ZGW-style sidebar tab widget works without a CnDetailPage ancestor.
  • register MAY carry an @resolve: sentinel — the widget passes it through unexpanded (resolution is the host loader's job).
  • order becomes _order[field]=asc|desc fetch params; limit caps the rendered rows (the widget fetches limit + 1 so the "View all" footer can detect that more rows exist).
  • extend (Wave 3, #91) — an array of OpenRegister _extend[] values (e.g. ["calculations"]) forwarded on the fetch, so virtual / declarative calc fields (procest daysOverdue / daysUntilDeadline) ride along and render as ordinary columns.
  • Externally supplied rows always win — passing rows/columns without a source behaves exactly as before.

Endpoint binding (Wave 2, #91)​

endpointSource ({ url, method?, params?, responsePath? }, default null) is the alternative to the OpenRegister source for rows an app REST endpoint computes (e.g. a per-source performance report):

{
"props": {
"endpointSource": {
"url": "/apps/pipelinq/api/reports/source-performance",
"params": { "from": "@workspace.dateFrom?", "to": "@workspace.dateTo?" },
"responsePath": "report.sources"
},
"columns": [
{ "key": "source", "label": "Source" },
{ "key": "conversionRate", "label": "Conversion %" }
],
"rowRoute": "lead-detail"
}
}
  • Rows come from the payload at responsePath (dot-path; the plucked value must be an array — anything else renders as empty).
  • params use the shared filter-token grammar and re-resolve + refetch when the page context changes; fetching goes through the shared useEndpointSource engine (request dedup + short-TTL cache, cn:page:refresh / cn:widget:refresh wiring on the widget's widgetId).
  • Exactly one of source | endpointSource (validator-enforced); external rows still win over both (and suppress the request).
  • columns / formatters / rowRoute / actions apply unchanged on top of endpoint rows.

A heading the endpoint names (labelPath)​

A column with labelPath takes its heading from the endpoint's whole response (before responsePath), so the endpoint can say what the column measures: a report that sends labels.workingHours as "Working hours (working days x 8)" heads its column with it. label stays the heading until the response names one.

{ "key": "workingHours", "label": "Working hours", "labelPath": "labels.workingHours" }

Reading only when asked (loadOn: "request")​

An endpoint whose every read is recorded (an audit trail per read, say) should not be read because somebody opened the page. With loadOn: "request" in the endpointSource block the widget reads nothing on mount: it shows a button (requestLabel, default "Show") with an optional requestHint sentence above it, and reads only when the reader presses it. When the request changes (another period from the page filters), the last answer is dropped and the widget waits for the next press. Page and widget refreshes do not read a widget that is waiting. Each press is a fresh read, past the shared cache.

"endpointSource": {
"url": "/apps/dossiq/api/woo/reports/throughput",
"params": { "from": "@workspace.from", "to": "@workspace.to" },
"responsePath": "rows",
"loadOn": "request",
"requestLabel": "Show",
"requestHint": "Every time you open this report, it is recorded."
}

CnWidgetObjectTable, CnChartWidget and CnStatWidget all honour it; the labels go through the app's translate.

Refused, failed and short answers​

An endpoint read that is refused (401/403) shows the server's message as a warning and no table; a failed read shows its message as an error. A table is never drawn empty for a read that did not answer, so "no rows" keeps meaning no rows. A response body with a top-level truncated: true keeps the table and adds a note that the figures may be incomplete. endpointSource.truncatedText replaces the default truncation sentence with one that says what to do ("Choose a shorter period."). All three come from CnEndpointNotice.

Declarative actions​

actions[] (default []) takes the unified manifest action shape (handler | open-modal | open-page | navigate | object-op):

  • Non-mutating types and object-op patch / delete render per row through CnRowActions (delete styled destructive).
  • object-op create renders as a widget-scoped footer affordance (there is no row to mutate) and creates against the widget source.
  • delete is always confirm-gated through CnConfirmDialog; patch / create confirm only when the action sets confirm: true.
  • Mutations dispatch via the shared object store (dispatchAction — object-op). The manifest declares intent only: authorization-shaped fields have no effect, OpenRegister RBAC is the authority, and a rejected write surfaces an inline error with no local mutation. After a successful mutation the self-fetch refreshes and an object-op event is emitted (so hosts feeding external rows can refetch).

Props​

PropTypeDescription
sourceObjectDeclarative self-fetch source { register, schema, filter, order, limit } (default null).
endpointSourceObjectEndpoint-bound rows { url, method, params, responsePath } (default null) — see Endpoint binding. Exactly one of source | endpointSource.
actionsArrayDeclarative actions (unified action shape incl. object-op, default []).
registerStringRegister slug for self-fetch mode (legacy direct prop).
schemaStringSchema slug for self-fetch mode (legacy direct prop).
columnsArrayColumn definitions — bare string keys or the object form ({ key, label, sortable, width, cellClass, formatter, widget, format, aggregate }).
rowsArrayPre-fetched rows — always win over source (disables self-fetch).
loadingBooleanLoading flag forwarded to CnDataTable's skeleton state.
hideHeaderBooleanHide the column-header row (compact list surface, default false).
borderlessBooleanDrop CnDataTable's card chrome (default false).
fitWidthBooleanFit the table to the tile (default true): the title column (a column's grow: true, else title or name, else the first) shrinks and ends in an ellipsis, so trailing columns such as a date stay visible. Pass false for the table's own auto layout.
exportCsvBooleanShow an "Export CSV" button under the table that downloads the rows it holds, one column per table column headed by its label. Values are the row values, not the formatted cell text. Default false.
exportFileNameStringThe downloaded file's name without .csv. Defaults to the title, slugged, else export.
exportIdStringA name a page header export action uses to download this table as CSV: { "type": "export", "exportId": "object-types" } in the page's headerActions makes the header's Download download this table's rows (board DqCatalogus). Default '' (no header download).
rowRouteStringRoute NAME for row-click navigation — mapped to CnDataTable's rowClickRoute with { params: { id } }.
rowIdFieldStringThe row field (a dot-path) holding the id rowRoute opens, for a row that links to another record (a payment row opening its case: "rowIdField": "case"). Empty uses the row's own id; a row whose field is empty does not link.
viewAllRouteObjectvue-router location for the "View all" footer link (default null).
pageSizeNumberRows per page: the board's pager under the table ("4 of 7", page buttons, Next), forwarded to CnDataTable. It pages the rows the widget holds; with a source, source.limit sets how many are read. 0 (default) shows no pager.
viewAllLabelStringPre-translated "View all" label (CnDataTable default when unset).
emptyTextStringEmpty-state text (CnDataTable default when unset).
lensReasonTextsObjectApp wording for an unavailable personal lens, keyed <lens>.<reason> or <reason>. A source.filter._recent tile whose response reports @self.lenses.recent.available: false (openregister#4514) says why it is empty, for example "This server does not keep track of what you open.", instead of emptyText.
rowIconString | FunctionLeading per-row icon: MDI name or (row) => iconName (default null).
rowClassFunction | ArrayPer-row CSS class binding (default null) — a host-supplied (row) => string function (pass-through), or a declarative rules[] array compiled here into that function. See Declarative rowClass.
sortableBoolean | ArrayColumn heads that sort, as the index table's: true for every column, or the keys that do. A column's own sortable wins. The sort goes out with the source fetch and replaces source.order while it is set; an endpointSource table sorts its rows in the browser (default false).
filterableBooleanColumn heads with the index table's filter button. A header filter goes out with the source fetch as the index page's parameters; an endpointSource table filters its rows in the browser (default false).
footnoteStringA muted line under the table, 12px under it in 13px text, through the host translate (DqTermijnen Ingebrekestellingen). Not drawn while a refused or failed read shows no table (default '').
titleStringWidget title shown in the chrome header (default 'Table').
documentation-urlStringDocumentation link for the overflow Actions menu (default '').
widget-idStringStable id forwarded to the widget chrome (default '').
hideWrapperBooleanRender content-only, without the widget's own CnWidgetWrapper chrome (default false). Set by hosts that already provide the card chrome — CnDashboardPage's registry branch mounts the widget this way to avoid a double card.

All other props are forwarded to CnDataTable — see the CnDataTable docs for the full surface.

Declarative rowClass (#91)​

rowClass gives a declarative way to highlight rows from the manifest — overdue / at-risk rows get a CSS class without a bespoke render function. It accepts two forms:

  • a host-supplied function (row) => string, passed straight through to CnDataTable's own rowClass (the pre-existing contract), or
  • an array of rules [{ when: { field, op?, value }, class }], compiled here into that function. Each rule adds its class to a row when the shared visibleWhen predicate (LOCAL form) holds against the row: field is a dot-path into the row, op is eq | neq | gt | gte | lt | lte (default eq), value is the literal right-hand side. Rules evaluate in order and every matching class is space-joined.
{
"props": {
"source": { "register": "procest", "schema": "case" },
"columns": [{ "key": "title", "label": "Case" }],
"rowClass": [
{ "when": { "field": "status", "op": "eq", "value": "overdue" }, "class": "row--overdue" },
{ "when": { "field": "daysUntilDeadline", "op": "lt", "value": 3 }, "class": "row--at-risk" }
]
}
}

The app styles .row--overdue / .row--at-risk in its own stylesheet.

Dashboard registration (type: "object-table")​

Besides the v2 grid (widgetKey: "object-table"), the widget is registered in the shared dashboardWidgetRegistry so a CnDashboardPage widget definition with type: "object-table" renders it — including through the in-app "Add widget…" picker (the config form is the shared object-list form: register / schema / filters / sort / limit / columns). The registered renderer is a chrome-aware adapter: it mounts the widget with hideWrapper: true inside the dashboard's own CnWidgetWrapper, and normalises the stored content blob onto the widget's props. Three blob shapes are accepted:

Stored contentResult
Flat form shape ({ register, schema, filter, sort, limit, columns }) — what the config form writesFolded into source; sort becomes order: { field: dir } and limit becomes source.limit
v2 prop shape ({ source, columns, actions, … })Passed through as-is
Neither — no source and no register/schema, e.g. an endpointSource blobPassed through with limit left as a top-level prop, since there is no source to fold it into

In every shape limit is kept only when it is a positive finite number — the widget's prop is type: Number, so a stored "3" is dropped rather than forwarded. That top-level limit is what viewAllRoute needs: the footer's View-all link shows only while the table's row cap hides rows (total > shown).

Slots​

Every host-supplied CnDataTable scoped slot is forwarded verbatim — notably #footer ({ total, shown }), #empty, and #column-<key>. The #row-actions slot is withheld while the widget renders its own declarative actions[] menu.

Events​

All listeners are forwarded to CnDataTable (@row-click, @sort, etc.). The widget itself emits:

EventPayloadDescription
object-op{ action, row, result }After a successful declarative mutation — hosts feeding external rows refetch on it.

Spec​

  • REQ-MVR-006 (manifest-v2-renderer) — built-in widget: object-table
  • list-widget-enrichment (ADR-049 Decision 2) — declarative source, actions, object-op, compact list surface

Page controls​

source.pageControls (flat dashboard content: pageControls) has the same shape as on the record list: sort.map replaces source.order, and toggle.removes drops filter keys while the page's switch is on. A sort entry with rank (the record list's sort by an enum's rank) is ignored here and the table keeps source.order. See the workspace filter page for the controls.