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:
filteris token-resolved with the sharedresolveFilterTokensgrammar 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'scnObjectContextref (which wins per field) or CnPageRenderer's v2cnDetailObjectContextholder (which backfills), so a ZGW-style sidebar tab widget works without a CnDetailPage ancestor.registerMAY carry an@resolve:sentinel — the widget passes it through unexpanded (resolution is the host loader's job).orderbecomes_order[field]=asc|descfetch params;limitcaps the rendered rows (the widget fetcheslimit + 1so 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 (procestdaysOverdue/daysUntilDeadline) ride along and render as ordinary columns.- Externally supplied
rowsalways win — passingrows/columnswithout asourcebehaves 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). paramsuse the shared filter-token grammar and re-resolve + refetch when the page context changes; fetching goes through the shareduseEndpointSourceengine (request dedup + short-TTL cache,cn:page:refresh/cn:widget:refreshwiring on the widget'swidgetId).- Exactly one of
source|endpointSource(validator-enforced); externalrowsstill win over both (and suppress the request). columns/ formatters /rowRoute/actionsapply 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-oppatch/deleterender per row through CnRowActions (deletestyled destructive). object-opcreaterenders as a widget-scoped footer affordance (there is no row to mutate) and creates against the widgetsource.deleteis always confirm-gated through CnConfirmDialog;patch/createconfirm only when the action setsconfirm: 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-opevent is emitted (so hosts feeding externalrowscan refetch).
Props
| Prop | Type | Description |
|---|---|---|
source | Object | Declarative self-fetch source { register, schema, filter, order, limit } (default null). |
endpointSource | Object | Endpoint-bound rows { url, method, params, responsePath } (default null) — see Endpoint binding. Exactly one of source | endpointSource. |
actions | Array | Declarative actions (unified action shape incl. object-op, default []). |
register | String | Register slug for self-fetch mode (legacy direct prop). |
schema | String | Schema slug for self-fetch mode (legacy direct prop). |
columns | Array | Column definitions — bare string keys or the object form ({ key, label, sortable, width, cellClass, formatter, widget, format, aggregate }). |
rows | Array | Pre-fetched rows — always win over source (disables self-fetch). |
loading | Boolean | Loading flag forwarded to CnDataTable's skeleton state. |
hideHeader | Boolean | Hide the column-header row (compact list surface, default false). |
borderless | Boolean | Drop CnDataTable's card chrome (default false). |
fitWidth | Boolean | Fit 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. |
exportCsv | Boolean | Show 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. |
exportFileName | String | The downloaded file's name without .csv. Defaults to the title, slugged, else export. |
exportId | String | A 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). |
rowRoute | String | Route NAME for row-click navigation — mapped to CnDataTable's rowClickRoute with { params: { id } }. |
rowIdField | String | The 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. |
viewAllRoute | Object | vue-router location for the "View all" footer link (default null). |
pageSize | Number | Rows 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. |
viewAllLabel | String | Pre-translated "View all" label (CnDataTable default when unset). |
emptyText | String | Empty-state text (CnDataTable default when unset). |
lensReasonTexts | Object | App 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. |
rowIcon | String | Function | Leading per-row icon: MDI name or (row) => iconName (default null). |
rowClass | Function | Array | Per-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. |
sortable | Boolean | Array | Column 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). |
filterable | Boolean | Column 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). |
footnote | String | A 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 ''). |
title | String | Widget title shown in the chrome header (default 'Table'). |
documentation-url | String | Documentation link for the overflow Actions menu (default ''). |
widget-id | String | Stable id forwarded to the widget chrome (default ''). |
hideWrapper | Boolean | Render 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 ownrowClass(the pre-existing contract), or - an array of rules
[{ when: { field, op?, value }, class }], compiled here into that function. Each rule adds itsclassto a row when the sharedvisibleWhenpredicate (LOCAL form) holds against the row:fieldis a dot-path into the row,opiseq | neq | gt | gte | lt | lte(defaulteq),valueis the literal right-hand side. Rules evaluate in order and every matchingclassis 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 content | Result |
|---|---|
Flat form shape ({ register, schema, filter, sort, limit, columns }) — what the config form writes | Folded 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 blob | Passed 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:
| Event | Payload | Description |
|---|---|---|
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.