CnIndexPage
The main list page component. Combines a data table (or card grid), filter bar, pagination, mass actions, CRUD dialogs, and a right-click context menu into a single schema-driven page.
Wraps: NcEmptyContent, NcLoadingIcon (from @nextcloud/vue), CnContextMenu
Try it


Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | String | (required) | Page title |
description | String | '' | Optional subtitle |
pageTabs | Array | null | Tabs to sibling pages above the toolbar (manifest config.pageTabs), each { id?, label, route?, params?, query?, href?, countFrom?, adminOnly?, permission? }; countFrom: { register, schema, filter? } adds that list's count. adminOnly: true draws the tab for an instance admin only, and permission for a user who holds that permission (with no permissions known, the tab shows, as a menu entry does). This only hides the tab. It is not access control: the page the tab points to must still refuse a user who may not see it, on the server, because anyone can type its address. The current route's tab is marked, and a click follows the tab on the app's router. Wins over a named source's page tabs (DqPrivacy, DqContracten). |
notice | Object | null | A note card under the list (manifest config.notice): { text, variant?, placement? } with variant info (default), success or warning; the text goes through the host translate. placement: 'page' draws it under the list card, on the page ground (DqContracten). |
defaultFilters | Object | null | Filters the list opens with (manifest config.defaultFilters), { field: value | [values] }: applied when the address names no filter and no saved view, shown on the Active line and removed with their chip or Clear all like any other filter. An address that names a filter wins (DqContracten). |
heldDefaultFilters | Array | null | The defaultFilters keys that stay while the address names filters of its own (manifest config.heldDefaultFilters). A link to one case type keeps isFinalStatus: false; a link that names the key itself, or a saved view, decides on its own (DqWerkbord). |
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); {total} and {shown} are the list's counts, e.g. "{total} lopend", and {count:<name>} the total of a list named in headerMetaCounts. {rows:<field>} counts the list's rows whose field is set (every row of a sort source's list, else the rows on screen), and a part in square brackets is left out while a count in it is zero: "{total} zaken op uw naam[, waarvan {rows:coveredFor} als waarnemer]" (DqAanMijToegewezen). In the board look a note that carries a count replaces the "{shown} of {total}" line under the title. |
headerMetaCounts | Object | null | The other lists headerMeta counts, by name: { suppliers: { register, schema, filter? } }, for "{total} contracten bij {count:suppliers} leveranciers". While a count loads, or when it fails, the note is left out. |
showTitle | Boolean | false | Show the page header (icon, title, description) inline above the table. When false (default), the title is shown in the sidebar header instead. |
icon | String | '' | MDI icon name for the page header. Defaults to schema.icon when a schema is provided. |
cardAccent | Function | null | (object) => { variant, icon?, label? } | null: a status accent per card in the card view, a colored start border and icon (see CnObjectCard accent). |
schema | Object | String | null | OpenRegister schema for auto-generating columns, filters, and form fields. In self-fetch mode a String is the schema slug — the resolved schema object then drives column generation. |
objects | Array | [] | Row data. Omitting this prop while register + schema are set switches the page into self-fetch mode — it drives the list off the object store itself. |
entitySource | String | '' | Name a registered NON-OBJECT collection to list (e.g. flows), instead of register + schema. The third data mode: a flow definition is deliberately not an OpenRegister object, so an index had nothing to bind to and such lists became bespoke type: "custom" pages. Takes precedence over register/schema and suppresses self-fetch; non-empty objects still wins over both. Sources are registered in indexSources.js; tasks lists the viewer's task inbox from OpenRegister's flow-tasks read, with its own columns, scope tabs, deep-link rows, no Add button and a pager: 20 rows a page (sourceConfig.limit sets another), fetched with limit and offset, and a new tab, filter or page size returns to page 1. A registered source pages the same way when it sets pages: true and supplies total(). flows lists the app's flows with each flow's last run and its runs this week (one GET /api/flow-runs/summary request), a status switch that pauses or starts a flow in place, the quick filters All, Active, Paused and With errors (sourceConfig.state, counted from the loaded list) and a footer note. flowRuns lists this week's runs of the app's flows; a row opens the run on its flow's canvas (/flows/:flowId?run=:uuid). Both draw the page tabs Flows and Runs this week, leading to /flows and /flow-runs (override with sourceConfig.flowsRoute / sourceConfig.runsRoute). A source can supply pageTabs(), tabCounts() and footerNote; a manifest quickFilters or footerNote still wins. endpoint lists rows from an app's own endpoint: set sourceConfig explicitly to { url: '/apps/<app>/api/<path>', rowsPath?: 'results', ...params }; the url is resolved with generateUrl and fetched with the reader's session (the endpoint authorizes), the rows are read at rowsPath (or the body when it is an array), and the other keys plus the active quick filter's filter go along as query parameters. Declare the columns in the manifest. A quick filter with showCount is counted by the same request with that tab's filter: its total at sourceConfig.totalPath (total by default), else the rows in the answer. Without an explicit sourceConfig.url (including CnPageRenderer's fallback that hands over the page config) nothing is requested, the list stays empty and one console error names the page: page-config keys never become query parameters. Three more keys: searchParam sends the page's search term to the endpoint as that parameter (sender), a new term reloading from page 1; notePath with noteText reads a value off the answer and shows it above the rows in that sentence, its one placeholder taking the value ({ notePath: 'filterOrder', noteText: 'Filters run in this order: {order}' }, a list joined by commas); and a load the endpoint refuses with 403 shows the endpoint's message, else refusedText, else "You may not read this list.", in place of the rows, the search and the tabs. Any other failed load shows the error state rather than an empty list. searchFields declares the filters the endpoint takes, as a registered source does ({ messageKind: { param: 'messageKind', single: true } }), so a filterStrip or sidebar field narrows the endpoint's query. facets offers values the endpoint counts in its answer as a picker after the search ([{ field, path, label?, allLabel?, labels? }], the answer holding [{ value, count }] at path, such as dossiq's postvak channels): each value with its count, labels naming a value through the app's translate, and the All choice (allLabel) taking the filter off. A choice is a page filter on field, so searchFields declares it, and a chosen value the narrowed answer no longer counts stays in the picker. search searches one term over several kinds (DqZoekresultaten): sourceConfig: { term?, termQuery?: 'q', kinds: [...] }, each kind { id, label, register, schema, titleField?, subtitleField?, statusField?, statusResolve?, linkedField?, linkedTemplate?, href?, limit? } or { id, label, files: true }; objects are searched with OpenRegister's _search, files with Nextcloud's unified search, the term defaults to the address's ?q=, and the source draws All plus one quick filter per kind with its count. A kind's label goes through the app's translate. statusResolve: { register?, schema, labelField? } shows a referenced status by its label; the status column is a pill coloured by sourceConfig.statusColorMap. linkedField or linkedTemplate fills a "Linked" column (named by sourceConfig.linkedLabel). The page title and countText take {term}, the count line counts the active kind, and Kind and Linked are header filters (with filterMenu, the board's Filter button). Every column header sorts and carries a filter button (the source asks for header filters with headerFilters and for the page to order its rows with sortsRows); a header sort orders the rows already fetched. With sourceConfig.kindAsText: true the Kind column is plain text naming what one row is: each kind's rowLabel (translated; a template on the found object such as "{objectType}"), else the kind's label. Its header filter narrows on that text. users lists the members of a Nextcloud group (DqAfdelingen) with function (profile headline), roles (profile role), e-mail and today (an out-of-office period that runs now, Absent until <date>, else the user status message, present or away); pair it with folderSidebar: { source: 'groups', filterField: 'group', groups?: [{ id, parent? }] }, which lists the groups with their member counts. On All, before a group is picked and without sourceConfig.group, it lists every user the reader may list (all users for an admin, the users of their groups for a sub-admin). Listing a group needs an admin or its sub-admin. organisations lists the OpenRegister organisations the viewer belongs to (name, status, type, created; rows keyed on the uuid, so pair it with rowRoute), and the same name on a CnDetailPage shows one organisation. |
rowRoute | String | '' | Route name a clicked row opens on THIS app's router, overriding a named entitySource's own navigation. A source knows where its rows live and navigates itself, which is right when the detail page belongs to another app: tasks sends a click to OpenRegister's task page. It is wrong for an app that ships its own page for those rows, and the @row-click event cannot recover it, because openRow calls window.location.assign() and the host's push never lands. Set it and the row pushes { name: rowRoute, params: { id } } instead. Ignored when entitySource is not set. |
sourceConfig | Object | null | Config handed to the named entitySource's loader — e.g. { app: 'dossiq' } scopes the flows source to one app's flows; { scope: 'pooled' } scopes the tasks source. On a manifest page CnPageRenderer fills it with the resolved page config when none is set explicitly. Ignored when entitySource is not set. |
filter | Object | null | Self-fetch mode only — a base filter map applied to every fetch as a fixed filter (the user's facet filters can't override it). String values of the form "@route.<name>" or ":<name>" resolve to $route.params[<name>]; other values pass through. Re-resolves when $route.params change. Fed from pages[].config.filter in the manifest path. No effect in consumer-managed mode. |
quickFilters | Array | null | Self-fetch mode only — array of \{ label, filter, default?, icon? \} rendered as a tab strip above the table (see CnQuickFilterBar). The active tab's filter is merged into every fetch after filter (the tab wins on a colliding key) and before the user's activeFilters (which still narrow within the active tab). String values follow the same "@route.<name>" resolution as filter. First entry with default:true (else index 0) is active on mount; switching tabs re-fetches at page 1 and emits @quick-filter-change. Under the board look an entry with activeLabel ("Pipeline: Sales") puts a removable chip with that text on the Active line and counts on the Filter badge while selected; removing it returns to the default tab. Fed from pages[].config.quickFilters. |
quickFiltersFrom | Object | null | Quick filters made from the values a field holds: { field, register?, schema?, labelField?, allLabel? }. One grouped request reads the distinct values of field with their counts (within filter); the page draws "All" (or allLabel) plus one tab per value, the most frequent first, each with its count. With register and schema the values are record ids and each tab shows the record's labelField (else title or name), as for a case type per install (DqTeamwachtrij). Ignored when quickFilters is set. Fed from pages[].config.quickFiltersFrom. |
filterStrip | Object | null | A second filter strip under the toolbar on one field: { field, label?, allLabel?, options?: [{ value, label }], showCount? }. All and one pill per value (options, else the schema enum); a pill filters the list on that value, All clears it; with showCount each pill counts its rows within the active quick filter (manifest: config.filterStrip) |
quickFilterMode | String | 'chips' | How the quick filters render: 'chips' (pill strip) or 'dropdown' (a single NcSelect; the empty-filter "All" tab is dropped). Fed from pages[].config.quickFilterMode. |
quickFilterMultiple | Boolean | false | Allow several quick filters active at once. Selected tabs' filters are OR-ed together into the fetch (same field → array value → field[]= IN query). Fed from pages[].config.quickFilterMultiple. |
viewSwitch | Array | null | Board look only: the segments the view switch draws (table, cards, board, map), always in that order. A listed mode the page cannot open (no board config, no mapConfig) is drawn disabled with the tooltip "not available on this list". Fed from pages[].config.viewSwitch. |
viewSwitchLinks | Object | null | Board look: view switch segments that open another page, by mode (table, cards, board, map): { board: { route, params?, query? } } or { map: { href } }. The segment is a link in its place in the switch, for a board or a map that is a page of its own; a mode the page opens in place stays a button (manifest: config.viewSwitchLinks) |
quickFilterMaxVisible | Number | 0 | Chips mode only: how many quick-filter pills render inline before the rest move behind one more chip — a ⋯ pill that opens a panel of the hidden lenses. 0 renders every tab, which wraps the actions bar onto a second line once a page declares more than a handful. The visible set is the first n entries of quickFilters. Fed from pages[].config.quickFilterMaxVisible. |
filterLabels | Object | {} | How the Active line names a filter: per filter key an optional label (the field) and values (value to text), both through the app's translate, e.g. { isFinalStatus: { label: 'Status', values: { false: 'Ongoing' } } }. Wins over the schema title, the sidebar field title and enumLabels. A range filter ({from, to}, or key[gte]/key[lte]) is one chip, "1 tot en met 31 oktober", with locale dates; with relative: true on its entry a range from today reads "vandaag", "binnen 7 dagen" or "deze week". Several values read as a locale list ("actief en verlopend"). Fed from pages[].config.filterLabels. |
quickFilterPlacement | String | '' | Where the quick-filter chips sit (pages[].config.quickFilterPlacement). 'toolbar' keeps them on one row with the Filter button and the view switch, in whatever width that row has beside a side panel (DqTeamwachtrij): the chips take the room the buttons leave, and those that do not fit move into the overflow chip. The default leaves the layout as it was. 'row' puts them on a row of their own above the toolbar, wrapping onto more lines instead of folding into the overflow chip (DqTeamwachtrij); beside a side panel the row sits in the list column. |
quickFilterPlacementByView | Object | null | The quick-filter placement per view mode (pages[].config.quickFilterPlacementByView): { table?, cards?, board?, map? }, each a quickFilterPlacement value. A view it does not name keeps quickFilterPlacement (dossiq's case list: { board: 'toolbar', map: 'toolbar' } for DqWerkbord and DqZakenKaart, the table and cards views as DqZaken draws them). |
searchPlacement | String | '' | Where the board look's search field sits (pages[].config.searchPlacement). 'toolbar' puts it on row 1, before the Filter button and the view switch, taking the room they leave (DqTeamwachtrij); the default opens row 2 with it. No effect outside the board look. |
pagination | Object | null | Pagination state (\{ currentPage, totalPages, totalItems, pageSize \}) |
loading | Boolean | false | Loading state |
loadingText | String | 'Loading…' | Accessible label for the loading spinner (NcLoadingIcon aria-label) |
selectable | Boolean | true | Enable row selection checkboxes |
hideTableHeader | Boolean | false | Draw the table without its column-header row (manifest config.hideTableHeader), for a list the board draws as plain rows (DqTeamwachtrij). Pair it with selectable: false for no checkboxes. |
rowClickToView | Boolean | false | When true, a row/card click emits row-click (to open/navigate) even while selectable — selection then via the checkbox only. Only takes effect when something can open the row (a row-click listener, or a named source that routes its rows); otherwise the click selects, so it is never dead. With selectable: false a click always emits row-click. Manifest-driven pages set this automatically when a matching detail page, rowRoute or split view exists, and ignore an explicit true when none does. |
selectedIds | Array | [] | Currently selected IDs |
viewMode | String | 'table' | 'table', 'cards', or 'map'. The 'map' mode is only offered when the page opts in — see Map view mode. |
mapConfig | Object | \{\} | Marker geometry mapping for the opt-in map view mode, mirroring manifest config.map 1:1: \{ latField, lngField, geoField?, popupField?, center? \}. When non-empty (and not excluded by viewModes), a third "Map" toggle segment appears. latField/lngField are object (or @self) property paths (dotted paths supported); geoField is an alternative GeoJSON Point property that wins over lat/lng; center is a [lat, lng] fallback for an empty set. zoom is the map's initial zoom. list: \{ title, sub?, pills?, due? \} draws a numbered list beside the map, both in one framed card (DqZakenKaart): title, sub and due are field templates per row, a pill is \{ path?, text?, map?, colorMap? \}. The pins carry the list's numbers, the row under the pointer is marked on both, the rows without a place are counted under the list with a link to the table, and the count line adds "· N with an address on the map". plotAll, markerColor and count are in Map view mode. |
mapLabel | String | '' | Label for the map view-toggle segment (defaults to "Map"). Fed from pages[].config.mapLabel. |
mapIcon | String | '' | MDI icon name for the map view-toggle segment (defaults to the built-in map-marker icon). |
calendar | Object | \{\} | The opt-in calendar view mode, mirroring manifest config.calendar: \{ dateField, endDateField?, titleField? \}. The segment appears only when viewModes lists calendar and dateField is named. |
viewModes | Array | null | Explicit whitelist of toggle segments to offer, e.g. ['table', 'cards', 'map', 'calendar']. Fed from pages[].config.viewModes. When set it takes precedence over inferred availability (map otherwise appears iff mapConfig is non-empty). |
sortKey | String | null | Current sort column key. null means no column is actively sorted. |
sortOrder | String | 'asc' | 'asc', 'desc', or null (no sort) |
sortKeys | Array | [] | External/host-controlled multi-column sort key list, [{ key, order }, …]; mirrors sortKey/sortOrder for shift+click multi-sort. In self-fetch mode the active multi-sort is instead persisted to and restored from $route.query._order. |
defaultSort | Array | [] | Default multi-key client-side sort applied to the already-loaded rows whenever no explicit column sort is active (no sortKey). Each entry is \{ field, order? \} with order one of 'asc' / 'desc' (default 'asc'); rows compare by the first field, ties broken by the next, etc. (type-aware: numbers numerically, dates by timestamp, else localeCompare; empties sort last). Clicking a sortable header takes over and suppresses this default. Fed from pages[].config.defaultSort. Useful for a fixed presentation order such as group-by-type-then-name. |
rowKey | String | 'id' | Unique row identifier field |
rowIcon | String | Function | null | Optional leading icon for every table row — a static MDI icon name or (row) => iconName. Forwarded to CnDataTable. Fed from the manifest as pages[].config.rowIcon. |
activeOrganisation | Object | null | null | Optional multi-tenant binding from a tenant-switcher higher in the tree. When the bound organisation changes, CnIndexPage calls store.setActiveTenantOrganisation(uuid) so the next fetchCollection() stamps the new X-OpenRegister-Organisation header and the in-memory list caches are cleared. Leave null for single-tenant pages. See Multi-tenancy guide. |
collectionUrl | String | '' | Self-fetch only. List from this endpoint instead of /api/objects/{register}/{schema}, for a list that mixes several register/schema pairs. See Mixed-schema collections. |
columns | Array | [] | Manual column definitions (overrides schema) |
excludeColumns | Array | [] | Schema columns to hide |
includeColumns | Array | null | Schema columns to show (whitelist) |
columnOverrides | Object | \{\} | Per-column overrides |
actions | Array | [] | Custom row action definitions. Each entry accepts the runtime {label, icon, handler, …} shape (function-typed handler fires directly) AND the manifest shape with a string handler resolved through the v2 registry first, then customComponents — see "Action handlers" below. An entry may also be a "builtin:view" / "builtin:edit" / "builtin:copy" / "builtin:delete" placeholder that puts that built-in at its position — see Placing built-in row actions. |
customComponents | Object | null | Custom-component / handler registry. When set takes precedence over the injected cnCustomComponents from a CnAppRoot ancestor. Used to resolve actions[].handler registry names (manifest-actions-dispatch). Named handlers resolve out of the v2 registry (a kind: "handler" entry) FIRST and fall back to this map. |
emptyText | String | 'No items found' | Empty state message |
lenses | Object | null | null | Personal-lens report (@self.lenses) of the list on screen, for a host that fetches itself; self-fetch mode reads it from the store. A lens with available: false makes the empty state say why ("This server does not keep track of what you open.", "Log in to see what you opened recently.", "Your recent items are not available right now."). Needs openregister#4514. |
lensReasonTexts | Object | null | null | App wording for an unavailable lens, keyed <lens>.<reason> or <reason>. |
searchRefusalHint | String | '' | Self-fetch only. What to do after a search the server refused for its grammar, through the app's translate; the default explains AND, OR, NOT and quotes. See A refused search. |
rowClass | Function | Array | null | CSS class(es) for a row: a function (row) => string, or (manifest config.rowClass) rules [{ when: { field, op?, value }, class }], each adding its class to a row whose field compares to the value with the visibleWhen operators; two dates compare as moments, so { when: { field: "dueAt", op: "lt", value: "@today" }, class: "cn-row--overdue" } marks an overdue task (DqTaken). A when list holds when every condition holds: [{ field: "expectedCloseDate", op: "lt", value: "@today" }, { field: "status", value: "open" }] marks an open lead past its date and not a won one. The class is the app's to style. |
addLabel | String | '' | Add button label |
inlineActionCount | Number | 2 | Number of inline action buttons before overflow menu |
showMassImport | Boolean | true | Show mass import action |
showMassExport | Boolean | true | Show mass export action |
showMassCopy | Boolean | true | Show mass copy action |
showMassDelete | Boolean | true | Show mass delete action |
allowExport | Boolean | false | Opt-in flag for the native Export menu (CSV/Excel) rendered next to the Add button. Renders only when true AND the resolved schema is flagged exportable: true (top-level or configuration.exportable); navigates to GET /apps/openregister/api/objects/{register}/{schema}/export, passing the list's own query (without paging) as filters. Distinct from showMassExport, which exports the fetched/selected rows via a blob download instead. |
allowSavedViews | Boolean | false | Opt-in flag for the saved-views control (saved-views-ui): a Views dropdown listing the user's OpenRegister saved-search views (GET /apps/openregister/api/views). Applying a view writes its stored filters/search/sort into the route query (non-underscore keys are filters; _search and _order are reserved); "Save current view…" persists the current route-query state via POST /apps/openregister/api/views and toasts either way, naming the view (a failure also keeps the dialog open with the reason); own views can be deleted after confirmation. Emits apply-view when a view is applied. |
viewCounts | Boolean | Array | false | Which saved views show how many records they match: true for all of them (the tabs named in viewTabs and the entries in the views control), or a list of view ids. Off by default, so no count request is made. A quick filter opts in on its own entry with showCount: true. Entries that filter the same single field share one grouped request. |
savedViewsScope | String | '' | Which pages share this page's saved views. By default a view is shared by every page over the same register and schema and shown on no other page, since a view is filters over one schema's fields. Set a name to share views across pages over different sources, or to keep two pages over one source apart. Written into the saved view's query.scope on save; views saved before scoping existed carry no scope and stay visible everywhere. |
massActionNameField | String | 'title' | Field for display names in mass action dialogs |
nameFormatter | Function | null | Optional function (item) => string to format item names in dialogs. Overrides massActionNameField when provided. Passed to all delete and copy dialogs. |
exportFormats | Array | [] | Available export formats |
importOptions | Array | [] | Import dialog options |
showFormDialog | Boolean | true | Enable built-in create/edit form dialog |
createModal | String | '' | Registry key of a kind: 'modal' entry that the Add button and ?action=create open instead of the built-in form dialog, so an index page can share a dedicated create dialog with, say, a dashboard open-modal header action. Edits keep the form dialog. Needs a CnAppRoot ancestor to mount the modal; without one Add falls back to the form dialog. In a manifest: "config": { "createModal": "ClientCreateDialog" }. |
showRequestFeature | Boolean | true | Show the built-in "Request a feature" entry in the CnActionsBar overflow. Opens the CnSuggestFeatureModal with surface: "index:<schema>". Requires a CnAppRoot ancestor (repo inject) to open — warns + no-ops otherwise |
useAdvancedFormDialog | Boolean | false | Use CnAdvancedFormDialog for create/edit (properties table, JSON tab, optional metadata) instead of CnFormDialog |
createOverride | Function | null | Opt-in async create hook. When set, a create confirmed from the built-in form dialog calls await createOverride(formData, ctx) instead of the store / self-store saveObject. The override owns persistence (e.g. an app posting through a contact-aware endpoint that fills a required FK before saving to OpenRegister) and must return the created object on success (falsy = failure; throwing surfaces the error in the dialog). ctx is { register, schema, objectType, effectiveSchema }. Edits are never routed here; when absent, create behaviour is unchanged. See Per-schema create-override hook. |
showViewAction | Boolean | true | Show the built-in View row action. It is left out of a row's menu whenever a click on that row already opens its detail page (the menu offers Edit instead); a row with no detail page keeps it. Emits a dedicated @view event — independent of @row-click. Set to false when the row has no separate "open detail" target. On a named entitySource page the effective default is false — the source's own open action navigates to the detail page, which is the view; an explicit prop still wins. |
viewTo | Function | null | (row) => location | null: where the View row action links to. When it returns a location, View renders as a real link (middle-click, copy link) and does not emit @view; when it returns null, View stays a button that emits @view. Manifest pages get it from CnPageRenderer, pointing where a row click opens. |
showEditAction | Boolean | true | Show the built-in Edit row action. On a named entitySource page the effective default is false — a source has no schema, so the form modal could only render empty; the source declares its own Edit, which navigates. An explicit prop still wins. |
editOpensDetail | Boolean | false | Send the Edit row action to the record's detail page (emits @edit-open) instead of opening the edit modal. Opt-in only — CnPageRenderer does not derive it, because @edit-open is bound to the same navigation as a row click, so an Edit that routes only repeats the row click (the split pane, or the detail page) and the form stops being reachable from the list. Declare it per page when the modal cannot express the record. |
showCopyAction | Boolean | true | Show copy row action. On a named entitySource page the effective default is whether the source implements copyRow (the built-in copy dialog then confirms through it); an explicit prop still wins. |
showDeleteAction | Boolean | true | Show delete row action. On a named entitySource page the effective default is whether the source implements deleteRow (the built-in delete dialog then confirms through it); an explicit prop still wins. |
excludeFields | Array | [] | Form fields to hide |
includeFields | Array | null | Form fields to show (whitelist) |
fieldOverrides | Object | \{\} | Per-field overrides |
formSize | String | 'normal' | NcDialog size for the built-in Add/Edit form dialog ('small'/'normal'/'large') |
formColumns | Number | 1 | How many columns the built-in Add/Edit form flows its fields into (1 or 2) |
createDefaults | Object | null | Seed values for the built-in create dialog only (never edit). Resolves @me/@now/@today at any depth; @object.*/@workspace.*/@config.* are not resolved here and pass through unchanged. |
createSuccessRoute | String | Object | null | Route opened after a successful create from the built-in Add dialog; the created object's id is merged into the params. |
createSuccessMessage | String | '' | Toast shown after a successful create from the built-in Add dialog. |
showAdd | Boolean | true | Show the Add button in the actions bar |
addDisabled | Boolean | false | Disable the Add button (e.g. when required selections are missing) |
refreshDisabled | Boolean | false | Disable the refresh button (e.g. when required selections are missing) |
subscribe | Boolean | true | Self-fetch mode only — auto-subscribe to live collection updates for the page's register/schema scope and refetch (coalesced) on remote changes. Set false (manifest: config.subscribe: false) for static views. See Live updates. |
showViewToggle | Boolean | true | Show table/card view toggle |
inlineSearch | Boolean | false | Show an inline search field in the actions bar (manifest: config.inlineSearch). The field takes the place of the "Showing X of Y" counter unless showCountWithSearch is set |
search | Boolean | true | false draws no inline search in the actions bar, also in the board look, which otherwise draws one on every index page (manifest: config.search). Wins over inlineSearch. |
live | Array | [] | Object types whose live changes the list follows (manifest config.live, e.g. ["lead", "ticket"]): it subscribes through the object store's live updates and reads the list again half a second after the last change, so a card a colleague moved moves here too. It lets go when the page leaves. |
appConfig | Object | {} | The app config @config.<key> tokens resolve against (manifest: config.appConfig), as on the dashboard and detail pages, merged over a config an ancestor provides on cnAppConfig. A quick filter's filter and its label / activeLabel take the token: "Residence @config.municipality" reads "Residence Zuiddrecht" (board DqContacten); the label is translated first, and a key the config does not hold leaves the token as written. A date token can take a setting as its day count ("@today-{@config.lead_stale_threshold_days}d"), and footerNote names @config.<key> values the same way. |
showCountWithSearch | Boolean | false | Keep the "Showing X of Y" counter visible beside the inline search field, after the search and any #after-search controls; forwarded to CnActionsBar (manifest: config.showCountWithSearch). Only relevant with inlineSearch |
filterMenu | Boolean | false | Show a filter menu (funnel) in the table header listing each enum/badge column's values as toggleable facet filters (manifest: config.filterMenu). Under the board look on a page without a filter sidebar it is the toolbar's Filter button, which carries the number of active filters as a badge while any is active |
columnMenu | Boolean | false | Show a column menu (columns button) in the table header listing every governed column as a visibility checkbox — the in-table equivalent of the sidebar's Columns tab (manifest: config.columnMenu). See Filter and columns: table header vs sidebar. |
searchInFiles | Boolean | false | Show an "Also search inside files" switch beside the search box (manifest: config.searchInFiles). On, a search that has a term also sends _content_search=true (OpenRegister file-content search, capped at 50 candidates, noted under the list), and a row found through a file shows "Found in {file}" from @self.matchedFile. The switch is kept in the route as contentSearch=1. |
relatedFieldFilters | Object | null | Filters over a type's own declared fields beside the search (CnRelatedFieldFilters): { definitions: { register, schema, filter }, related: { schema, backref, definitionKey?, valueKey? } }. Manifest: config.relatedFieldFilters. |
searchPlaceholder | String | '' | Placeholder for the inline search field (manifest: config.searchPlaceholder) |
cardsLabel / tableLabel | String | '' | View-toggle option labels, e.g. "Tiles" / "List" (manifest: config.cardsLabel / config.tableLabel) |
cardsIcon / tableIcon | String | '' | MDI icon names for the view-toggle options (manifest: config.cardsIcon / config.tableIcon) |
store | Object | null | Store instance for automatic save integration. When provided with objectType, the form dialog saves directly to the store via store.saveObject() instead of only emitting create/edit. The object type must already be registered in the store via registerObjectType(). |
objectType | String | '' | Object type slug for store integration (e.g. \${registerId}-\${schemaId}). Required when store is set — a console warning is emitted if missing. |
sidebar | Object | null | Manifest-driven sidebar configuration. When set with enabled: true, CnIndexPage auto-mounts an embedded CnIndexSidebar and forwards its props. Shape: \{ enabled, show?, columnGroups?, facets?, showMetadata?, search? \}. show (default true) is the visibility gate — set false to hide the configured sidebar without removing config. When unset (the default), the legacy slot-based pattern is preserved — consumers wire their own CnIndexSidebar at the App.vue level. See Manifest-driven sidebar below. |
searchValue | String | '' | Current search term forwarded to the embedded sidebar (only relevant when sidebar.enabled). |
visibleColumns | Array | null | Currently visible column keys forwarded to the embedded sidebar (only relevant when sidebar.enabled). |
activeFilters | Object | \{\} | Currently active facet filters \{ fieldName: [values] \} forwarded to the embedded sidebar (only relevant when sidebar.enabled). |
register | String | '' | Effective register slug for the page. Forwarded as a prop to the resolved cardComponent so bespoke card UIs can match the schema → register pair. Manifest-driven path: pages[].config.register flows in via CnPageRenderer. |
cardComponent | String | '' | Optional name of a consumer-provided card component (registered in the v2 registry — any kind carrying a component — or in the legacy customComponents map on CnAppRoot) to render in place of the default CnObjectCard when the page is in card-grid view mode. Resolution priority: #card scoped slot → cardComponent registry entry → default CnObjectCard. Unknown names log a console.warn once and fall back to the default so a misconfigured manifest never blanks the grid. See Bespoke card-grid below. |
customComponents | Object | null | Optional explicit customComponents registry. Overrides the registry injected from CnAppRoot via cnCustomComponents. Mostly used by unit tests; production consumers register components on CnAppRoot instead. |
Export follows the list
The Export menu (allowExport) and the mass-action Export export the rows the list is showing, not the whole schema.
- The menu sends the query the list itself sends: search, sort, facet filters, the page's fixed
filterand the active quick filter, without paging (_limitand_pageare dropped). A host-managed list (objectspassed in) has no such query and keeps forwarding the route's. - The flag that enables the menu is read from the schema's top-level
exportable, then fromconfiguration.exportable. The top-level field wins when both are set; a schema flagged in neither place keeps the menu hidden. (OpenRegister has to keep one of the two; until it does, the menu does not appear on a real instance.) - The mass export exports the selected rows (as
ids[]) when rows are selected, and the rows matching the list's query otherwise. The dialog says which, with the count, before the user confirms (CnMassExportDialogscopeText).
Calendar view mode
viewMode also accepts calendar: the current filtered rows on a month calendar by a date field (CnObjectCalendar). Opt in through config.viewModes and name the fields:
{
"viewModes": ["table", "calendar"],
"calendar": { "dateField": "inspectionDate", "endDateField": "inspectionEnd", "titleField": "address" }
}
With endDateField an entry spans every day from the start to the end. In calendar mode the page adds the visible month to the list query (dateField[gte] and [lte], or with an end field the overlap dateField[lte] and endDateField[gte]), asks again when the month changes, and fetches one page sized to the month; leaving calendar mode removes the range and restores the page size, so the table is never narrowed. A click on an entry opens the record as a row click does. A busy day's "+N" button switches to the table filtered to that day. Nothing here reschedules a record: dragging an entry to another day is not offered. Applying a saved view only changes the list filters, so the same month query is used; the /api/views/{id}/calendar endpoint is not called.
Board and date axis: two more ways to look at the same list
viewMode accepts board and dateAxis beside table, cards, list and
map. Each needs its own config block, and each segment appears only when the
mode can actually work: a board needs a statusField, a date axis needs both
dates. A segment that opens a view saying it cannot be one is worse than no
segment, because the reader has to click it to find out.
{
"viewModes": ["table", "board", "dateAxis"],
"board": {
"statusField": "status",
"cardFields": ["title", "assignee"],
"swimlaneField": "assignee"
},
"dateAxis": {
"startField": "startDate",
"endField": "deadline",
"laneField": "assignee",
"labelField": "title"
}
}
The board never writes the status field. A move goes through
runTransition, the host's own transition, so a board can never move a case
past a rule the case page enforces. With no runTransition the board is
read-only rather than broken. A move emits board-move and refreshes the list,
because a transition may have changed more than the status and a board that
only moved the card would disagree with the table beside it.
A board shows every matching row. A page that fetches its own list asks
for 500 rows in board view instead of the table's page, and gives the table its
page size back when the reader leaves the board. When more rows match, the
footer reads "Showing 500 of 612" with a "Load more" button that adds the next
batch after the rows already on the board. A host-fed board still gets
page-changed and pages as before.
A filter set on one mode does not follow you to another. The two views are asked different questions: a board is "show me the work in flight", a table is "find me this case". Carrying the board's filter into the table is how somebody searches for a case they know exists and is told there are no results; carrying a table filter into a board silently empties three columns, and an empty column reads as "no work here" rather than "you are not being shown it". The saved view's own criteria do follow: the view is the question, the mode is how you look at the answer.
What the manifest cannot check. A statusField naming a field with no enum
and no lifecycle cannot be refused at validation time, because the stages live
in the register schema and the manifest does not contain it. CnBoardView says
so on screen instead of drawing empty columns.
Declared columns
An enum often holds more values than a board should draw. states on board
(for the statusField) or on a columnFields entry (for that field) names the
columns in order, instead of every enum or lifecycle value (since manifest
schema 2.149.0):
"board": {
"statusField": "status",
"states": [
"new",
"in_progress",
"awaiting_customer",
{ "key": "completed", "label": "Finished" },
{ "key": "converted", "closed": true },
{ "key": "resolved", "hidden": true }
]
}
An entry is a value or { key, label?, color?, hidden?, closed? }. hidden
draws no column, so its cards land in "Elsewhere"; closed starts the column
folded; label is an i18n key. A column field with a source or kind: values
ignores states.
Columns from a referenced field
A case's status is often not an enum. It is a reference to a statusType row,
and every case type has its own rows. columnFields lets the board take its
columns from those rows (since manifest schema 2.97.0):
"board": {
"statusField": "status",
"wrap": true,
"columnLimit": 3,
"columnSwitchLabel": "Kolommen",
"hint": "Een kolom per waarde van de eigenschap. Sleep een kaart om de status te wijzigen.",
"moveHandler": "caseStatusMove",
"moveTargetsHandler": "caseStatusTargets",
"narrow": {
"field": "caseType",
"label": "Zaaktype",
"allLabel": "Alle zaaktypen",
"source": { "schema": "caseType", "labelField": "title" }
},
"columnFields": [
{
"field": "status",
"label": "status",
"source": {
"schema": "statusType",
"labelField": "name",
"orderField": "order",
"colorField": "colour",
"mergeBy": "name",
"capacityField": "capacity",
"neutralColor": "grey",
"colorMap": { "orange": "var(--nl-color-orange, #e17000)", "grey-light": "var(--nl-color-grey-light, #f0f0f0)" },
"filter": { "isFinal": false },
"narrowBy": { "field": "caseType", "rowField": "caseType" }
}
},
{ "field": "caseType", "label": "type", "source": { "schema": "caseType", "labelField": "title" }, "readOnly": true },
{ "field": "assignee", "label": "behandelaar", "kind": "values", "emptyLabel": "Niemand" }
]
}
-
The columns are the referenced rows. The page fetches them once per field (
source.registerandsource.schema, by default the page's register and the property's$ref). An empty stage is still a column to drop a card into. -
orderFieldorders them.mergeBymakes one column of rows with the same name, so "In behandeling" of every case type is one column. -
capacityFieldnames the referenced row's limit. The header reads "count / capacity" and is drawn full at the limit, and a move into a full column is refused with "In behandeling is full: 4 of 4." before anything is written (the server still guards). A merged column shows no limit, since each row has its own, but a move into the row that is full is still refused. -
neutralColornames the colour a row holds when nobody chose one (a schema that stores "grey" by default). A merged column then takes the first row colour that is not this one, so a grey row listed first no longer draws "In behandeling" grey when another case type made it orange. Every row grey, the column is grey. Colours are compared as written: "Grey" is not "grey", and a hex value is not a name. Unset, a merged column takes its first row's colour (since manifest schema 2.101.0). -
colorMapmaps a stored row colour to the CSS colour its column is drawn in, so a palette name such as "orange" or "grey-light" draws a theme token rather than the browser's own orange, or no dot at all. It applies after the merge, soneutralColorstill compares the stored names. A colour it does not map draws as before (since manifest schema 2.102.0). -
narrowBylinks a referenced row to its parent. While the page filters onnarrowBy.rowFieldwith one value, the columns are that parent's rows only. -
narrowdraws that filter as a select after the search ("Zaaktype:"). It sets the page filter, so the cards and the active filter chips follow. -
Two or more
columnFieldsdraw a "Columns:" switch after the search. The entry onstatusFieldis the default. -
itemsPathtakes the columns from a LIST on each referenced row instead of the rows themselves: a lead'sstageis a name in its pipeline'sstages. Each item is keyed bykeyField(defaultname), the value a card stores and a drop writes, and linked to its row under_parent, sonarrowBy: { "field": "_parent", "rowField": "pipeline" }with anarrowselect onpipelineshows the chosen pipeline's stages:"board": {
"statusField": "stage",
"narrow": { "field": "pipeline", "label": "Pipeline", "source": { "schema": "pipeline", "labelField": "title" } },
"columnFields": [{ "field": "stage", "source": { "schema": "pipeline", "itemsPath": "stages", "keyField": "name", "orderField": "order", "colorField": "color", "closedField": "isClosed", "narrowBy": { "field": "_parent", "rowField": "pipeline" } } }],
"sumField": "value"
} -
closedFieldnames the referenced row's (or item's) flag for a closed stage, a won or lost deal: its column starts collapsed, showing its count and a "Show N more" button, and still takes a drop. -
kind: "values"is for a field that references no schema, such as a Nextcloud user id. Its columns are the values present on the rows, then one column for no value. -
hintis one sentence after the controls, in the secondary colour. -
card.formattersshows a card field through a formatter from the app'scnFormattersregistry, the one a table column names informatter:{ "caseType": "caseTypeName" }makes the pill read "Woo-verzoek". -
wrapputs the columns on more rows instead of one row that scrolls.
A drop writes the reference. On a merged column the page writes the row of
the card's own parent; a column the parent has no row for refuses the drop. With
moveHandler (a name in the app's registry) the handler makes the move. It gets
{ card, toKey, field, value, target } and returns a promise; a rejection shows
its message as the refusal. That is how a case status goes through the app's
transition. Without a handler the field is written with a PATCH. readOnly: true
gives no move at all. A board without columnFields keeps reading the schema
and the runTransition prop, as before.
moveTargetsHandler answers where one card may go: it gets
{ card, field } and returns the referenced ids the card can reach. The board
fades the other columns during a drag, marks them "not allowed" in the card
menu, and refuses a drop on them. An entry can also be an object
{ key, allowed, reason } (key: the referenced id). With allowed: false the
column is offered but blocked: the card menu shows it disabled with the reason
under its name, during a drag the column shows the reason under its header, and
a drop there is refused with the reason. Plain ids and objects can be mixed.
Opening the board from the menu. An index page opens in the mode
?_view=<mode> names, when it offers that mode, and follows the address when it
changes. The key starts with _ like _search, so it is never read as a list
filter. A menu entry with "query": { "_view": "board" } opens the list as its
board, without a second index page on the same schema.
With selectable the board's cards carry a checkbox, so the bulk band works on
the board as on the table. The column switch emits board-column-field-change
with the field name.
Saved views: the tree, the labels and what a view is called
savedViewTree on an index page turns the flat Views dropdown into a tree.
Two hundred personal views in one flat list is the problem it solves. Absent,
the page renders exactly the dropdown it renders today.
{
"savedViewTree": {
"enabled": true,
"maxDepth": 3,
"groupBy": "status",
"landingView": { "behandelaar": "open-cases" },
"columnsPerRole": { "behandelaar": ["id", "title", "status"] },
"templates": [
{ "slug": "triage", "name": "Triage", "columns": ["id", "title"], "exportFields": ["id"] }
],
"seeded": [
{ "slug": "open-cases", "name": "Open cases", "label": "triage", "actions": ["claim"] },
{ "slug": "open-mine", "name": "Mine", "parent": "open-cases", "inherits": ["columns", "sorting"] }
]
}
}
Inheritance is five parts, resolved separately — criteria, columns,
sorting, defaultSort and exportFields. A child may narrow the criteria and keep
the parent's six columns, which an all-or-nothing rule makes impossible to
express. An absent inherits on a child means every part; an empty array means
none, so a view can hang under another for grouping alone. Overriding a part
and declaring nothing for it resolves to nothing, not to the parent's.
A cycle is refused naming both views. A parent the reader may not see is not an error: the child renders at the root, resolved, and says which parts came from a view they cannot see.
A slug is the one name a view is called by from a dashboard widget, an export action or the API. An unknown slug renders an empty state naming it, never a blank list: a blank list is indistinguishable from a query that matched nothing. A slug is editable only while nothing cites it.
landingView is where a role starts, not where it is kept. A personal
choice always wins and Reset returns to the administered view. A role's landing
view changing mid-session applies on the next arrival: moving somebody's list
out from under them is worse than a stale default.
columnsPerRole narrows index-columns-per-scope, never widens it. A role
naming a column the scope does not offer gets nothing extra; a per-role list
that could add one would be a second, quieter way to put a field on screen that
the scope deliberately left off.
groupBy counts the rows the list holds. On a paged list that is a count
of the page, and the surface says so rather than showing a page count as
though it were the total.
A view's actions intersect with what the reader may run and are never
added to. A view is a thing any user can create, so a view that could add an
action would let any user grant themselves one by saving a view.
Split view
A page declaring splitView opens a row beside the list rather than instead of it. The list keeps its scroll position, its selection and its loaded page, because it is hidden rather than unmounted. A handler at row 180 of 400 opens a case, closes it, and is still at row 180.
| Prop | Type | Default | Description |
|---|---|---|---|
splitView | Object | {} | { enabled, breakpoint, paneWidth }. Without enabled the page renders exactly as it does today. |
splitId | String | '' | The record the pane shows, taken from the split address. Empty closes the pane. |
splitCloseRoute | String | '' | Route name the pane's close button returns to. Defaults to the page the route names. |
splitCloseButton | Boolean | true | Whether the pane draws its own close button, at the top of the pane on the inline end. Set false only when the #split-pane slot draws one from the slot's close. |
splitCloseLabel | String | '' | Accessible name and tooltip for that button. Defaults to Close. |
manualOrder | Boolean | false | Lets this person drag the rows into an order of their own, held per user and per list. |
manualOrderId | String | '' | Stable id the order is held under. Defaults to the object type or the schema. |
personalColumns | Boolean | true | Lets this person order and pin the table columns from the sidebar's Columns tab, and keeps the visible columns, their order and the pinned count per user and per list in their Nextcloud preferences (columns.<list id>; the list id is manualOrderId, else the page id). false keeps show and hide only, stored nowhere. |
copy | Object | null | Copy settings from config.copy. include lists the link kinds a copy may take along (relationRows, incoming, files); the copy dialogs then list them, ticked, and the copy is one request to OpenRegister's copy endpoint. Without it a copy carries the fields only. |
Declare it on the manifest page and build the routes with buildManifestRoutes, which emits the second route the pane needs:
{
"id": "Cases",
"route": "/cases",
"type": "index",
"title": "Cases",
"splitView": { "enabled": true, "breakpoint": 900 },
"manualOrder": true
}
const router = createRouter({
history: createWebHashHistory(),
routes: buildManifestRoutes(manifest, { component: CnPageRenderer, props: { manifest } }),
})
CnPageRenderer then mounts the same detail component the full route mounts into the #split-pane slot. Mounting your own is a second detail implementation, and it will drift from the full page within a month.
Below breakpoint the same address renders the record on its own, so a link sent from a laptop opens on a phone rather than as a narrow column. It falls back to the record, never to the list: answering a colleague's link with a list is the one thing the sender did not mean.
| Slot | Bindings | Description |
|---|---|---|
split-pane | id, layout, close, saved | The open record. layout is split or detail. Call saved(record) after a save and the row updates in place, with no refetch and no scroll reset. |
| Event | Payload | Description |
|---|---|---|
split-close | The pane was closed. | |
split-saved | object | A record saved in the pane was written onto its row. |
manual-order-change | Array<string> | This person reordered the list. Payload is the row ids in their order. |
A manual order is stored against the person and the list, never onto the records, so two people ordering one shared list do not fight and an export carries no ordering field. The order stands down while a sort is active, because a sort the person just chose is them asking for a different order.
Events
| Event | Payload | Description |
|---|---|---|
add | — | Add button clicked (backward compat) |
create | formData | Form dialog create confirmed. When store integration is active, payload is the saved object returned by the store. |
edit | formData | Form dialog edit confirmed. When store integration is active, payload is the saved object returned by the store. |
edit-open | row | Emitted instead of opening the edit modal when editOpensDetail is set. The host navigates to the record's detail page, where the whole record — not just its scalar fields — can be edited. CnPageRenderer binds this to the same navigation as @view, which is why editOpensDetail is opt-in: derived, it made Edit indistinguishable from opening the row. |
delete | id | Single delete confirmed |
copy | \{ id, newName \} | Single copy confirmed |
mass-delete | ids[] | Mass delete confirmed |
mass-copy | \{ ids, pattern \} | Mass copy confirmed |
mass-export | \{ ids, format \} | Mass export confirmed |
mass-import | importData | Mass import confirmed |
refresh | — | Refresh button clicked |
row-aux-click | (row, event) | A row or card middle-clicked, under the same conditions as row-click. The second argument is the native auxclick event; pass it to openRowTarget to open the row in a new tab. A middle click never reaches row-click, so a row-click listener that navigates keeps the current tab. On a named entitySource page the library opens the row in a new tab itself. |
row-click | (row, event) | Row, card, or map marker clicked. The second argument is the native click event (absent for a map marker or keyboard shortcut); pass it to openRowTarget so a ctrl/cmd/shift click opens the row in a new tab. A middle click emits row-aux-click instead. On a named entitySource page the library navigates itself the same way (rowRoute, then the source's rowTarget/openRow/detailRoute). Only fires when selectable is false — when selectable is true, a deliberate click anywhere on a row/card toggles its selection (emitting select) instead — a text-selection drag is not treated as a click. In the map view mode a marker click resolves back to its source row and emits the identical payload, so detail-page navigation is uniform across table, cards, and map. Conceptually distinct from view; for click-to-open in a selectable list, use the built-in View action (@view). |
view | row | Built-in View row action triggered. Conceptually "open the detail view of this row". For a non-selectable list bind alongside row-click (same handler) for click-to-view; for a selectable list, plain clicks toggle selection, so use @view (the eye action) as the open-detail affordance. |
sort | \{ key, order \} | Sort changed. Cycles through asc → desc → null (disabled). When cleared, both key and order are null. |
page-changed | pageNum | Pagination page changed |
page-size-changed | size | Page size changed. In self-fetch mode the list has already refetched page 1 at the new size. |
select | ids[] | Selection changed |
action | \{ action, row, id?, builtin? \} | A row action was chosen from a row's menu, its right-click menu or the keyboard primary action. action is the label, id the action's id when it has one, and builtin: true marks a built-in View / Edit / Copy / Delete. |
search | term | Search input changed in the embedded sidebar (only emitted when sidebar.enabled). |
content-search | boolean | The "Also search inside files" switch changed (needs searchInFiles). Consumer-managed pages use it to add _content_search to their own query; self-fetch pages handle it themselves. |
columns-change | keys[] | Visible columns changed in the embedded sidebar (only emitted when sidebar.enabled). |
filter-change | \{ key, values \} | Facet filter changed in the embedded sidebar (only emitted when sidebar.enabled). |
quick-filter-change | index | Zero-based active tab index changed (only emitted when quickFilters is set). The fetch is automatically triggered — listen for observability / analytics. |
apply-view | view | A saved view was applied via the Views dropdown (only emitted when allowSavedViews). The route query has already been replaced with the view's stored state — listen for observability / analytics. |
Slots
| Slot | Scope | Description |
|---|---|---|
#below-header | — | Content rendered between the page header and the actions bar (e.g. status banners, alerts) |
#mass-actions | \{ count, selectedIds \} | Extra mass action buttons |
#action-items | — | Extra action bar buttons |
#header-actions | — | Extra header buttons |
#delete-dialog | \{ item, close \} | Replace single-item delete dialog |
#copy-dialog | \{ item, close \} | Replace single-item copy dialog |
#form-dialog | \{ show, item, schema, confirm, close \} | Replace create/edit dialog (any variant). Use show as a v-if guard so the dialog unmounts after close; otherwise an always-mounted override re-opens when its internal close animation finishes. Call await confirm(object) to save — see Replacing the form dialog. |
#form-fields | \{ fields, formData, errors, updateField \} | Form content override (CnFormDialog only; ignored when useAdvancedFormDialog is true) |
#field-\{key\}-option | option object properties | Custom dropdown option rendering for a select field (forwarded to NcSelect #option) |
#field-\{key\}-selected-option | option object properties | Custom selected option display for a select field (forwarded to NcSelect #selected-option) |
#import-fields | \{ file \} | Extra import dialog fields |
#empty | — | Custom empty state |
#card | \{ object, selected \} | Custom card template (cards view) |
#row-actions | \{ row \} | Custom row actions |
#column-\{key\} | \{ row, value \} | Custom cell renderer per column |
Public Methods
| Method | Description |
|---|---|
setFormResult(result) | Set the terminal form dialog result (\{ success?, error? \}) — switches to the result phase, replacing the form |
setFormValidationErrors(fieldErrors, message?) | Show a validation error while keeping the form visible (so the user can fix the data). Use for 400/422; store integration calls this automatically for isValidation errors |
setSingleDeleteResult(result) | Set delete dialog result |
setSingleCopyResult(result) | Set copy dialog result |
setMassDeleteResult(result) | Set mass delete result |
setMassCopyResult(result) | Set mass copy result |
setExportResult(result) | Set export dialog result |
setImportResult(result) | Set import dialog result |
openFormDialog(item) | Programmatically open form (null = create) |
Usage
<template>
<CnIndexPage
:title="schema?.title || 'Contacts'"
:schema="schema"
:objects="objects"
:pagination="pagination"
:loading="loading"
@row-click="onRowClick"
@create="onCreate"
@edit="onEdit"
@delete="onDelete"
@refresh="onRefresh"
@page-changed="onPageChanged"
@sort="onSort">
<!-- Custom status column rendering -->
<template #column-status="{ row, value }">
<CnStatusBadge :label="value" :colorMap="statusColors" />
</template>
</CnIndexPage>
</template>
Using the advanced form dialog
Set use-advanced-form-dialog to use CnAdvancedFormDialog for Add/Edit (properties table, JSON tab, optional metadata). The same @create and @edit events and setFormResult() apply.
<CnIndexPage
title="Items"
:schema="schema"
:objects="items"
:pagination="pagination"
:loading="loading"
use-advanced-form-dialog
@create="onCreate"
@edit="onEdit"
@refresh="fetchItems"
/>
Replacing the form dialog
The #form-dialog slot swaps the whole dialog out — use it when the replacement needs
control the built-in dialog cannot give it (a wider size, a multi-pane layout, its own
footer). Reach for #form-fields first if you only need different fields inside the
standard dialog.
Save through the scope's confirm, not your own store call. confirm(object) runs the
page's normal save path — createOverride / the store prop / the self-fetch store,
whichever applies — then emits @create or @edit and refreshes the list (the
self-fetch and createOverride paths refresh automatically; with the store prop, list
refresh is driven by your own @create/@edit handler, same as it always has been). A
replacement dialog that persists on its own instead bypasses all of that: the row will not
appear until the user reloads, because the built-in refresh never runs. (Live
or-collection-* updates do cover this eventually, but only where server push is actually
delivered, so do not rely on them.) Saving through confirm also keeps writes in the same
store the list reads from, rather than a second cache of the same objects.
A write that cannot go through confirm, such as an app modal that uploads files, can call
dispatchObjectsChanged({ register, schema })
instead. Every mounted index page for that register and schema then refreshes its list.
confirm is async — await it, then close():
<CnIndexPage title="Mappings" register="openconnector" schema="mapping">
<template #form-dialog="{ show, item, confirm, close }">
<MyWideDialog
v-if="show"
:item="item"
@save="async (draft) => { await confirm({ ...item, ...draft }); close() }"
@cancel="close" />
</template>
</CnIndexPage>
An object carrying no id creates; otherwise it updates, so spread the incoming item under
your edits to preserve fields the replacement dialog does not touch. Result-phase helpers
(setFormResult, setFormValidationErrors) target the built-in dialog's ref and become
no-ops once it is replaced — surface success and failure in your own dialog.
Store integration
Set store and objectType to have the form dialog save directly to the store. The object type must be registered in the store (via registerObjectType()) before passing the store here. On save, store.saveObject(objectType, formData) is called; on success the result phase is shown and @create / @edit are emitted with the saved object. On a validation error (isValidation, i.e. 400/422) the form stays open with the server message shown above the fields so the user can correct the data; other failures show a terminal error result.
<CnIndexPage
title="Clients"
:schema="schema"
:objects="clients"
:pagination="pagination"
:loading="loading"
:store="objectStore"
object-type="register-schema"
@refresh="fetchClients"
/>
No @create / @edit handlers or setFormResult() calls are needed when store integration is active. You can still listen to @create / @edit for side effects (e.g. refreshing the list) — the payload will be the object returned by the store.
Per-schema create-override hook
Some schemas can't be persisted by a plain saveObject straight to OpenRegister — they have a server-side prerequisite that must run first. The canonical example: a client whose required contactsUid is a foreign key to a Nextcloud addressbook contact. The generic create flow would POST without that FK and get a 400. The app already has a contact-aware endpoint (POST /api/contacts-sync/create) that resolves/creates the contact and saves with the FK filled in — but the generic "Add" button on the list went straight through saveObject.
createOverride closes that gap. Pass an async function; on a create (not edit), the built-in form dialog calls it instead of saveObject. The override owns persistence and returns the created object:
<CnIndexPage
title="Clients"
:schema="clientSchema"
:store="objectStore"
object-type="crm-client"
:create-override="createClientContactAware"
@refresh="fetchClients"
/>
methods: {
// Route generic client creates through the contact-aware endpoint that
// fills the required contactsUid (FK to a NC addressbook contact) before
// saving to OpenRegister. Other schemas can branch on ctx.objectType.
async createClientContactAware(formData, ctx) {
const created = await contactSyncApi.create(formData) // POST /api/contacts-sync/create
return created // truthy => @create emitted + dialog success; falsy => failure
},
}
Rules:
- Create-only. Edits always fall through to the normal store / self-store path; the override is never called for an edit.
- Return the created object (truthy) on success; return a falsy value to signal failure (terminal error shown). Throw to surface
err.messagein the dialog. ctxis{ register, schema, objectType, effectiveSchema }so one handler can branch per schema.- When the prop is absent, create behaviour is unchanged — no regression for existing consumers.
Custom item names in dialogs
When items don't have a simple name field (like audit trails that only have an ID), use nameFormatter to control how items are displayed in delete and copy dialogs:
<CnIndexPage
title="Audit Trails"
:objects="auditTrails"
:columns="columns"
:pagination="pagination"
:name-formatter="(item) => t('openregister', 'Audit Trail #{id}', { id: item.id })"
@delete="onDelete"
@refresh="onRefresh" />
This formatter is passed through to CnDeleteDialog, CnMassDeleteDialog, CnCopyDialog, and CnMassCopyDialog. It takes precedence over massActionNameField.
Read-only listing
Set :show-add="false" to hide the Add button. Combine with disabled row actions and mass actions for a fully read-only page.
<CnIndexPage
title="Entities"
:objects="entities"
:columns="columns"
:pagination="pagination"
:loading="loading"
:show-add="false"
:selectable="false"
:show-edit-action="false"
:show-copy-action="false"
:show-delete-action="false"
:show-form-dialog="false"
:show-mass-import="false"
:show-mass-export="false"
:show-mass-copy="false"
:show-mass-delete="false"
@row-click="onRowClick"
@refresh="onRefresh"
@page-changed="onPageChanged" />
Hiding built-in actions from a manifest
Manifest type:'index' pages can hide individual built-in actions without writing a wrapper component. The renderer (CnPageRenderer.resolvedProps) flattens config.actionToggles.* into the matching show* / selectable props before mounting CnIndexPage. Explicit config.<key> wins over config.actionToggles.<key> (precedence mirrors the existing config.readOnly shortcut).
{
"id": "Catalogs",
"route": "/catalogi",
"type": "index",
"title": "Catalogs",
"config": {
"register": "opencatalogi",
"schema": "catalog",
"actionToggles": {
"showEditAction": false,
"showCopyAction": false,
"showDeleteAction": false,
"showMassImport": false,
"showMassExport": false,
"showMassCopy": false,
"showMassDelete": false
}
}
}
Known keys (each maps to the matching CnIndexPage prop):
showAdd, showFormDialog, showViewAction, showEditAction, showCopyAction, showDeleteAction, showMassImport, showMassExport, showMassCopy, showMassDelete, showViewToggle, selectable. Unknown keys pass validation (forward-compat).
For a fully read-only page, prefer the all-or-nothing shortcut:
"config": { "register": "...", "schema": "...", "readOnly": true }
This expands to nine show*: false defaults; explicit config.showAdd: true still re-enables a specific button.
Placing built-in row actions
By default a row's menu lists the app actions from actions first and then the enabled built-ins in the order View, Edit, Copy, Delete. To put a built-in somewhere else, name it in actions with a placeholder string: "builtin:view", "builtin:edit", "builtin:copy" or "builtin:delete". OpenCatalogi's Publications page uses this to read Edit, Copy, File list, Delete:
"config": {
"register": "publication",
"schema": "publication",
"actionToggles": { "showViewAction": false },
"actions": [
"builtin:edit",
"builtin:copy",
{ "id": "file-list", "label": "File list", "icon": "FormatListBulleted", "handler": "openPublicationFiles" },
"builtin:delete"
]
}
The rules:
- A placeholder only places. Whether a built-in renders is still decided by
actionToggles/ theshow*Actionprops. A placeholder for a built-in that is turned off renders nothing.validateManifest()warns when the manifest itself turns that built-in off; the page stays silent, because a toggle turned off at runtime (a permission check,readOnly) is legitimate. - Unplaced built-ins are appended. Every enabled built-in the array does not name goes after all other entries, in the default order. That is why the example turns View off: left on, View would be appended after Delete. A page without placeholders renders exactly as before.
- An object is always an app action, whatever its
id.{ "id": "edit", "label": "Open editor" }renders beside the built-in Edit, not instead of it. In a manifest an object'sid, when present, must be a string. - Each placeholder at most once. A repeated placeholder, an unknown one such as
"builtin:archive", a bare string such as"edit", an object whoseidstarts withbuiltin:and an object that sets abuiltinkey are all manifest schema errors. Placeholders are refused on every page type other thanindex. - Delete last, by convention. Placing
"builtin:delete"before other entries is honoured, butvalidateManifest()returns a warning (not an error) when Delete is not the last entry of the rendered order, appended built-ins included. The page logs the same warning in development builds.
A named entitySource may place built-ins in its own rowActions the same way; the manifest's actions, when declared, still wins over the source's.
What placement changes. The order of the actions menu, and therefore the keyboard primary action (p with listShortcuts), which runs the first entry the menu shows and enables (a hidden or disabled entry is skipped): in the example it becomes Edit instead of File list. It does not change which entries show as inline icons: CnRowActions collapses into the overflow menu above three entries and renders an entry inline only when it is the only one. A future inline setting would show the first entries as icons, so placement would then decide those too.
Testids and the action event. A built-in's data-testid is cn-action-item-<id> (cn-action-item-edit, and so on) in every locale; an app action keeps the slug of its label. The action event payload keeps action as the label and adds the action's id, plus builtin: true for a built-in, so an app action with id: "edit" and the built-in Edit stay distinguishable. A row's availability block (rowActionField, default @self.actions) matches a built-in by its id, never by its label, and also by the OpenRegister permission verb that governs it: read permits View and Copy, update permits Edit, delete permits Delete. A built-in shows when the block allows either; a block allowing neither hides it. An app action sharing a built-in id matches by its id only. A verb refused with a reason hands that reason to the built-in through rowActionRefusal(row, action), unless its own id allows it, and a reason on the built-in's own id wins over the verb's. rowActionRefusal maps the verb only when handed the built-in action itself, such as the action from the action event payload or { id: 'edit', builtin: true }; a plain { id: 'edit' } matches by its id only. rowActionsNotDeclared(row) does not list a verb that a declared built-in uses.
Library version. The placeholders ship in the manifest schema 2.50.0. An app that adopts them MUST raise its @conduction/nextcloud-vue range to the release that ships them in the same change: an older library rejects the manifest, and useAppManifest then falls back to the unresolved bundled manifest, losing the backend manifest merge and @resolve: sentinel resolution on every page, not just the row order.
Self-fetch mode
A manifest type:"index" page dispatches to CnIndexPage via CnPageRenderer, which spreads pages[].config (register, schema, columns, sidebar, actions, filter) plus $route.params — but never an objects prop. So when register and schema are both set and the caller did not pass objects, CnIndexPage self-fetches: it derives objectType = '${register}-${schema}', registers it in the object store, and drives the whole list (collection fetch, _search/_order/_page/_limit, facet filters, schema load, sidebar wiring, the on* handlers) through useListView against the store provided by an ancestor CnAppRoot.
{
"type": "index",
"title": "Decisions",
"config": {
"register": "decidesk",
"schema": "decision",
"sidebar": { "enabled": true }
}
}
In this mode the page's rows, loading, pagination, schema, sort and search term all come from the useListView instance rather than from props; @search / @sort / @page-changed / @filter-change / @refresh route to its handlers (and still $emit for observers).
Form save (create/edit), mass export, and mass import are also self-handled in this mode, because the manifest path has no parent listening for @create / @edit / @mass-export / @mass-import. Confirming the export dialog downloads the register/schema's objects in the chosen format from OpenRegister's /api/objects/{register}/{schema}/export?type= endpoint; confirming the import dialog uploads the file to /api/registers/{register}/import (multipart; the schema slug is added for CSV) and refreshes the list. Both resolve their dialog with no consumer handler required. In consumer-managed mode (objects supplied) @mass-export / @mass-import still just emit for the parent to handle.
A failed fetch
When the latest fetch fails (OpenRegister answers a search term it cannot parse, such as an unbalanced bracket in verzoek (2026, with HTTP 400), the page shows an error state ("An error occurred") where the empty state would be, instead of the rows and "Showing X of Y" counter of the previous query, which the object store keeps on a failure. The server's own message is not shown (a search refused with a position is the exception, see A refused search); the state instead suggests changing the search or trying again when a search term is set, and trying again later when none is. The next successful fetch, for example after the search term is corrected, brings the results back, and so does a successful live-update refetch, so a transient failure does not outlast the next background fetch. Only the most recently started fetch decides whether the error state shows, judged by that request's own response, so an older response that settles late cannot turn it on or off. That holds when an older failure lands while a newer request is still in flight, and for a refresh that joins an identical request already in flight. The #empty slot is not used for this state, and consumer-managed mode (objects supplied) is unaffected.
A refused search
OpenRegister refuses a _search term it cannot parse, such as an unclosed bracket or quote, with 400 { error, position, term } rather than running it as a literal. A literal would return nothing and read as an honest empty result. When the failed fetch is such a refusal (a 400 with a term typed and a position, carried on the store's error or read from the message's "at position N"), the page shows the term with the character it stopped at marked, the server's reason, and what to do next (searchRefusalHint), instead of the generic error state.
<CnIndexPage register="dossiq" schema="case" search-refusal-hint="Search for a case number or plain words." />
Scoping a list to a parent — config.filter
config.filter becomes the filter prop and is applied to every fetch as a fixed filter (a user's facet selection for the same key cannot override it). String values of the form "@route.<name>" or ":<name>" resolve against $route.params; everything else is passed through literally. The filter re-resolves when $route.params change, so a list nested under a parent route (/forms/:id/submissions, /automations/:id/history) is a fully declarative type:"index" page:
{
"type": "index",
"title": "Submissions",
"route": "/forms/:id/submissions",
"config": {
"register": "pipelinq",
"schema": "intakeSubmission",
"filter": { "intakeForm": "@route.id", "archived": false }
}
}
Live updates — collection subscription
In self-fetch mode the page also subscribes to live collection updates for its or-collection-{register}-{schema} scope (via useObjectSubscription and the store's liveUpdatesPlugin). When another user creates, updates, or deletes an object in the register/schema pair, the list refetches with its current params (page, sort, search, filters) — events are hints, so bursts (mass import, bulk edits) are coalesced into at most one refetch per ~750 ms window, deduped against in-flight requests. When notify_push is unavailable the transport falls back to visibility-gated polling; nothing else changes for the page.
The subscription attaches on mount and is released on unmount; the epoch guard inside useObjectSubscription prevents a navigation-away during the async subscribe from leaking a stale subscription.
Opt out per page with the subscribe prop (default true):
{
"type": "index",
"title": "Archive",
"config": { "register": "decidesk", "schema": "decision", "subscribe": false }
}
Consumer-managed mode is unchanged
When the objects prop is supplied (every current consumer), nothing changes — no useObjectStore / useListView call, no registerObjectType / fetchCollection, no live-updates subscription; objects and the other props are used as today and filter has no effect. The switch is purely "did the caller pass objects?".
Mixed-schema collections (collectionUrl)
Set collectionUrl to list from an endpoint that searches several register/schema pairs at once, such as an app's catalog API. The endpoint takes _page, _limit, _search and _order[key]=dir, and answers { results, total, page, pages }.
<CnIndexPage
title="Publications"
register="19"
schema="24"
:collection-url="generateUrl('/apps/opencatalogi/api/{slug}', { slug })" />
register and schema remain the page's own pair. They drive the columns, the Add button, export and import.
A row whose @self.register / @self.schema names another pair behaves as a row of that pair:
- Edit opens the form with that pair's schema. The page's
includeFields,excludeFieldsandfieldOverridesare not applied to it. - Save, delete, mass delete and copy go to that pair's own URL. A selection kept across pages stays on each row's own pair.
- If that pair's schema can't be loaded, the form does not open and an error toast is shown.
register may be a slug. The page then loads the register once to match it against the rows' @self.register ids; passing ids skips that request.
Keep the columns to ones every pair has, such as @self.name, @self.updated and shared properties. Live updates follow the page's own pair only. In this mode, any dispatchObjectsChanged signal refreshes the list.
Map view mode
Alongside table and cards, CnIndexPage offers an opt-in map view mode — a third view-toggle segment that plots the current filtered rows on a CnMapWidget. It is strictly opt-in and fully backward compatible: pages that don't configure it render exactly as before.
Key properties of the map view:
- Same data, same filters. The map plots exactly the rows the table/cards show (
displayObjects) — there is no separate fetch path, so the sidebar facets, quick-filters, and search all narrow the markers too. - Geometry from object metadata. Marker coordinates are read from each object via
mapConfig, typically off the OpenRegister@selfmetadata block that the maps-overview leaf populates — not a bespoke per-app endpoint. - Navigation parity. A marker click resolves back to its source row and emits the same
@row-clickpayload as a table row-click, so detail-page navigation is identical across all three modes. - Graceful geometry gaps. Rows without finite, resolvable coordinates are skipped silently; an empty set falls back to
mapConfig.center(or a neutral world view). - Every matching row (
plotAll). By default the map plots the current page.mapConfig.plotAll: trueloads every row that matches the filters while the map is open, up to 500 (orplotAll: <number>), and restores the page size when the reader leaves the map. When more rows match, a note under the map says the first N are shown and asks to narrow the filters. - Marker colour (
markerColor).{ field, colorMap?, source?, default? }colours each marker by a field of its row. Withoutsourcethe value is looked up incolorMap. Withsource: { schema, register?, colorField, filter? }the field is a reference: the referenced row'scolorFieldis the colour, or the keycolorMapmaps to a CSS colour ("blue": "var(--nl-color-blue, #0b71ab)").var()is resolved for the SVG marker. Numbered pins (list) take the colour too, except the active one. - Count line (
count).trueadds "Showing {located} of {total} located" under the map: the rows it placed against the rows that match. A string is a template with{located}and{total}, through the app's translate.
"map": {
"geoField": "geometry",
"plotAll": true,
"count": "Showing {located} of {total} located cases",
"markerColor": {
"field": "status",
"source": { "schema": "statusType", "colorField": "colour" },
"colorMap": { "blue": "var(--nl-color-blue, #0b71ab)", "green": "var(--nl-color-green, #39870c)" }
}
}
Opting in (manifest):
{
"id": "Cases",
"type": "index",
"route": "/cases",
"config": {
"register": "procest",
"schema": "case",
"viewModes": ["table", "cards", "map"],
"map": {
"geoField": "@self.geo",
"latField": "@self.geo.lat",
"lngField": "@self.geo.lng",
"popupField": "title"
}
}
}
config.map maps 1:1 onto the mapConfig prop. config.viewModes is optional — when omitted, the map segment appears automatically whenever config.map is non-empty. Set an explicit viewModes list to force or suppress it. geoField (a GeoJSON Point) takes precedence over latField/lngField when present and resolvable; all three accept dotted paths.
Direct (non-manifest) use:
<CnIndexPage
:objects="cases"
:schema="caseSchema"
view-mode="map"
:map-config="{ latField: 'lat', lngField: 'lng', popupField: 'title' }"
:selectable="false"
@row-click="openCase" />
Context Menu
Right-clicking any table row opens a context menu at the cursor position. It is the same menu as that row's three-dot actions menu: CnIndexPage passes it rowActionsFor(row), the same per-row list the table, list and card menus render, so it has the same entries in the same order, after the same @self.actions narrowing and the same visible / visibleWhen rules. Each entry carries the same key, testid and action payload in both menus. No app-side changes are needed.
Powered by the CnContextMenu component and useContextMenu composable. The composable handles cursor positioning via CSS custom properties; the component renders the NcActions menu.
- Each action's
disabledstate (boolean or function) is respected - Destructive actions are styled with
--color-error - The menu closes on action click or outside click, cleaning up the CSS properties and data attribute
- Works out of the box for all consumer apps (OpenRegister, Keepiq, etc.)
Filter and columns: table header vs sidebar
Faceted filtering and column visibility can live in two places, and you choose per page from the manifest:
| Surface | Filter | Columns | Config |
|---|---|---|---|
| Table header (recommended default) | filterMenu: true → funnel button | columnMenu: true → columns button | config.filterMenu / config.columnMenu |
| Sidebar | sidebar.facets | sidebar.columnGroups (Columns tab) | config.sidebar.enabled: true |
The recommended default for an index page is the table header — it keeps both controls one click away inside the table and frees the sidebar for the detail/object surface. Use the sidebar variant when you want a persistently-open faceting panel.
// Recommended index-page default — both controls in the table header,
// search inline, sidebar off so the space is reclaimed.
{
"type": "index",
"config": {
"register": "petstore", "schema": "order",
"inlineSearch": true,
"filterMenu": true,
"columnMenu": true,
"sidebar": { "enabled": false }
}
}
Both surfaces drive the same state — filterMenu/columnMenu toggle the same activeFilters / visibleColumns the sidebar would, and emit the same @filter-change / @columns-change events — so a page can even expose both at once if desired.
Manifest-driven sidebar
Set the sidebar prop to an object to auto-mount an embedded CnIndexSidebar. This keeps the sidebar reachable from manifest.json (pages[].config.sidebar) without consumer apps wiring it manually.
<CnIndexPage
title="Decisions"
:schema="schema"
:objects="decisions"
:sidebar="{
enabled: true,
columnGroups: extraColumnGroups,
facets: facetData,
showMetadata: true,
search: { searchPlaceholder: 'Find decisions...', filtersLabel: 'Refine' },
}"
:search-value="searchTerm"
:visible-columns="visibleColumns"
:active-filters="activeFilters"
@search="onSearch"
@columns-change="onColumnsChange"
@filter-change="onFilterChange" />
sidebar field | Forwarded to CnIndexSidebar as | Notes |
|---|---|---|
enabled | (existence gate) | When false (or missing), the embedded sidebar is NOT mounted — the legacy slot-based pattern still works. |
show | (visibility gate) | Defaults to true. When false, the embedded sidebar is suppressed even if enabled: true. See show vs enabled below. |
columnGroups | columnGroups | Extra column groups beyond schema properties + Metadata. |
facets | facetData | Live facet data \{ fieldName: \{ values: [\{value, count\}] \} \}. |
showMetadata | showMetadata | Defaults to true. |
search | (spread via v-bind) | Sub-fields like searchPlaceholder, searchTabLabel, searchLabel, filtersLabel map 1:1 onto matching CnIndexSidebar props. |
@search, @columns-change, and @filter-change from the embedded sidebar re-emit on CnIndexPage, so consumer event handling stays at the page level.
If you prefer to mount your own CnIndexSidebar (e.g. at the App.vue level for cross-page state), simply leave sidebar unset — the legacy slot-based pattern is unchanged.
show vs enabled
enabled and show answer different questions and are intentionally
kept distinct:
enabled— existence gate: does this page configure an embedded sidebar at all? Whenfalse(or unset), the auto-mount code path is bypassed entirely — no<CnIndexSidebar>is rendered, and the consumer's slot-based pattern stays active.show— visibility gate: should the configured sidebar be rendered right now? Defaults totrue. Whenfalse, the sidebar config is preserved (so a parent watcher / feature flag can flip back totruelater) but the visible surface is suppressed.
Concrete example: a consumer wants the sidebar on wide viewports
and hidden on narrow ones. Keep enabled: true, columnGroups: [...]
static and toggle show from a layout watcher — the
columnGroups / facets / search config is retained across
flips.
Action handlers (manifest-actions-dispatch)
actions[] items declared in pages[].config.actions (manifest path) accept a string handler, and so do bulkActions[] and headerActions[]. All three resolve the name the same way: the v2 registry first — an entry of kind: "handler" exposing the function as .handler (or .fn), or a directly function-valued entry — then the deprecated customComponents map, which keeps an app that has not migrated working unchanged. A name that matches something registered but uncallable (a component where a function belongs) warns and falls back to emit-only; an unknown name falls back silently.
// registry.js — the v2 home for a manifest-named behaviour
export default {
claimCase: { kind: 'handler', handler: claimCase },
}
A row action that opens a modal
A row action of type: "open-modal" opens its target (a registry modal, or a built-in such as CnActionDialog) through the app root's cnOpenModal, with the row as object and its key as objectId; the action's own props win. An entity-sourced list reads its rows again on cn:page:refresh, which CnActionDialog signals after it acted, so a confirmed POST on a row is configuration: the dialog posts confirm.request, shows the server's refusal sentence when the server refuses, and the list refreshes when it did not. Without an app root the action falls back to emitting @action.
"actions": [
{ "id": "restore", "label": "Restore", "type": "open-modal", "target": "CnActionDialog",
"props": { "config": { "title": "Restore this record?", "reason": { "required": false },
"confirm": { "label": "Restore", "request": { "url": "/apps/myapp/api/records/@objectId/restore" } } } } }
]
A row action that calls an endpoint
A row action of type: "api-call" posts (or method: "PUT") to its url for the row it was picked on: {objectId} is the row's key and {field} any row field. It toasts successMessage or errorMessage (the server's sentence when none is set) and reads the list again after a success, unless refresh: false. Nothing is sent while the menu is drawn. With visibleWhen an Enable and a Disable action can share one row:
"actions": [
{ "id": "enable", "label": "Enable", "type": "api-call", "url": "/apps/pipelinq/api/export/jobs/{objectId}/enable",
"visibleWhen": { "field": "enabled", "value": false }, "successMessage": "Job enabled" },
{ "id": "disable", "label": "Disable", "type": "api-call", "url": "/apps/pipelinq/api/export/jobs/{objectId}/disable",
"visibleWhen": { "field": "enabled", "value": true }, "successMessage": "Job disabled" }
]
A header action that opens a modal
A header action of type: "open-modal" opens its registry modal with the list's active filters as activeFilters (the pipeline a board is narrowed to), the action's own props winning on a colliding key.
Registry-name handler
Manifest declaration:
{
"id": "Queues",
"route": "/queues",
"type": "index",
"title": "Queues",
"config": {
"register": "pipelinq",
"schema": "queue",
"actions": [
{ "id": "process", "label": "Process queue", "handler": "queueProcessHandler" }
]
}
}
Registry entry (src/registry.js):
export function queueProcessHandler({ actionId, item }) {
// open the right modal, dispatch a store action, etc.
store.processQueue(item.id)
}
export default {
// …existing component entries…
queueProcessHandler: { kind: 'handler', handler: queueProcessHandler },
}
When the user clicks "Process queue" on a row, CnIndexPage looks up queueProcessHandler in the registry, sees a function, and calls it with { actionId: "process", item: row }. The page's @action event still fires for any external listeners.
Reserved keywords
Three keywords short-circuit the registry lookup:
"navigate"— calls$router.push({ name: action.route, params: { id: row[rowKey], ...action.params } }). Theroutefield is required when this keyword is set. An optionalparamsobject holds literal route params merged over the default{ id: row[rowKey] }— soparams: { "id": "new" }makes a "New X" action land on the detail route in create mode, andparams: { "mode": "edit" }keeps the row id while adding an extra param. The sameparamsworks onconfig.headerActions[](page-level — no row, so the literals are the whole param map)."emit"— explicit no-op handler that just bubbles@action. Identical to leavinghandlerunset, but makes intent visible in the manifest."none"— disables the action click entirely (no handler call, no@actionemit).
Example:
{
"actions": [
{ "id": "view", "label": "Open", "handler": "navigate", "route": "QueueDetail" },
{ "id": "z", "label": "Z", "handler": "emit" },
{ "id": "x", "label": "X", "handler": "none" }
],
"headerActions": [
{ "id": "new", "label": "New resource", "handler": "navigate", "route": "ResourceDetail", "params": { "id": "new" } }
]
}
Fallback semantics
- Missing handler name in the registry → silent fall-through to
@action-only (no warning; preserves v1.2 manifests). - Non-function entry in the registry (e.g. a Vue component) → console.warn + fall-through to
@action-only. - Function-typed
handler(passed via the runtime prop, NOT through the manifest) keeps working unchanged — used by the built-inview/edit/copy/deleteactions.
Header actions that are links (href)
A headerActions[] entry that only goes somewhere carries href instead of handler. It renders as a real link (<a href>) in the actions bar's overflow menu, in the board header's Actions menu and as a headerButtons[] button naming it, so it can be middle-clicked, opened in a new tab, copied and bookmarked.
- An absolute
http(s),mailto:ortel:URL is used as written, and so is a protocol-relative//host/...URL, which leaves the instance; an instance path (a single leading/) goes throughgenerateUrl(), so/apps/integriq/connectionsworks with and without pretty URLs. A path that already names an entry point (/index.php/,/remote.php/,/public.php/,/ocs/) is only prefixed with the instance root, and one that already starts with the root and an entry point is used as written. Anything else (a relative path, another scheme) is dropped with a warning. - The link opens in place;
target: "_blank"opens it in a new tab.NcActionLinkandNcButtongive every linkrel="nofollow noreferrer noopener". - A link only navigates: it runs no handler and emits no
@header-action. The schema ($defs/headerAction) refuseshreftogether withhandleror atypeother thanhandler, and takeshrefon header actions and theirchildren[], and on a detail page'squickActions[]/primaryActionByStageentries, only; row, bulk and navigation actions and their children do not take it. - A JS-composed entry carrying a function
handlerandhrefis a link like any other, on every page type: thehrefis resolved, the handler is dropped and never called, and a one-timeconsole.warnnames the entry's id. Anhrefthat does not resolve is dropped instead, and the handler keeps running. - A header action's
children[]render, and so can be links, only in the dashboard header, whereCnActionButtonsdraws an action's own dropdown.
{
"headerActions": [
{ "id": "add-integration", "label": "Add integration", "icon": "Plus", "href": "/apps/integriq/connections?app=stackiq&link=1" },
{ "id": "guide", "label": "Integration guide", "href": "https://example.org/guide", "target": "_blank" }
]
}
The same key works on detail, dashboard and reports pages.
Bespoke card-grid via cardComponent
The default card-grid view renders CnObjectCard for each row using
the page's schema. When that's not enough — e.g. softwarecatalog's
Organisaties page needs a profile-style card with a logo,
contactpersoon block, and a CTA button — point the manifest at a
consumer-provided card component:
// src/registry.js
import OrganisatieCard from './components/cards/OrganisatieCard.vue'
export default \{ OrganisatieCard: \{ kind: 'page', component: OrganisatieCard \} \}
<!-- App.vue -->
<CnAppRoot
:manifest="manifest"
app-id="softwarecatalog"
:registry="registry">
<router-view />
</CnAppRoot>
// src/manifest.json — pages[]
\{
"id": "organisaties",
"route": "/organisaties",
"type": "index",
"title": "Organisaties",
"config": \{
"register": "softwarecatalog",
"schema": "organisation",
"cardComponent": "OrganisatieCard"
\}
\}
The resolved card component receives \{ item, object, schema, register, selected \}
props and emits click and select. When the page is not selectable a
click is forwarded as row-click; when it is selectable a click toggles
the item's selection instead (matching the default card/row behaviour). select
is always forwarded as select on the page. item and object are aliases of
each other; pick whichever feels natural.
Resolution priority (highest first):
#cardscoped slot — App.vue overrides always win.cardComponentregistry entry — manifest-driven dispatch.CnObjectCard— the schema-driven library default.
Unknown cardComponent names log console.warn once and fall back
to the default so a misconfigured manifest never blanks the grid.
Two-Phase Pattern
CnIndexPage uses the two-phase dialog pattern for all actions:
- User triggers action → dialog opens
- App handles the event (API call)
- App calls
setResult()on the component ref
<template>
<CnIndexPage ref="indexPage" @delete="onDelete" />
</template>
<script>
export default {
methods: {
async onDelete(id) {
try {
await this.objectStore.deleteObject('contact', id)
this.$refs.indexPage.setSingleDeleteResult({ success: true })
} catch (error) {
this.$refs.indexPage.setSingleDeleteResult({ error: error.message })
}
},
},
}
</script>
Documentation link
Set documentationUrl (and optionally documentationLabel) to surface a Documentation entry in the CnActionsBar overflow menu, alongside the built-in Request-a-feature item. It opens the link in a new tab. Empty (the default) hides it.
Reference (auto-generated)
The tables below are generated from the SFC source via vue-docgen-cli. They reflect what's actually in CnIndexPage.vue — props, events, and named slots — and update automatically whenever the component changes (see CLAUDE.md "Documenting components").
OpenRegister reliance
heavy: this component cannot work without OpenRegister. 12 direct references, 224 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, 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, CnWorkingCalendarWidget, CnWorkspaceFilterWidget, CnXwikiPageCreate, CnXwikiPagePicker.
See the reliance overview for the filterable list.
Props
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
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), such as "{total} open": {total} and {shown} are the list's counts, and {count:<name>} the count of a list named in headerMetaCounts ("{total} contracten bij {count:suppliers} leveranciers"). | |
headerMetaCounts | Record<string, {register: string, schema: string, filter?: object}>|null | null | The other lists headerMeta counts (manifest config.headerMetaCounts): { <name>: { register, schema, filter? } }, each read as one list total and filled in for {count:<name>}. While a count loads, or when it fails, the note is left out rather than shown with a gap. | |
pageTabs | Array<object>|null | null | Tabs to sibling pages above the toolbar (manifest config.pageTabs), each { id?, label, route?, params?, query?, href?, countFrom?: { register, schema, filter? }, adminOnly?, permission? }: DqPrivacy's "AVG-verzoeken | Datalekken". The current page's tab is marked; countFrom adds the count of that list. A tab with adminOnly shows only to an instance admin, one with permission only to a user who holds it. That hides the tab and nothing more: the page it points to must still refuse the user on the server. Wins over a named source's own page tabs. | |
notice | {text: string, variant?: string, placement?: string}|null | null | A notice under the list (manifest config.notice): { text, variant?: 'info' | 'success' | 'warning' }, a band that explains the list, such as who decides what. The text goes through the host translate. placement: 'page' draws it under the list card, on the page ground, instead of inside the list under its rows. | |
description | string | '' | Optional description shown below the title | |
countSubtitle | string|{singular: string, plural: string} | '' | A description that carries the collection's total: {total} in the text is replaced by the current pagination total ("{total} open cases" reads "48 open cases"). Rendered in place of description once a total is known; before that, description shows. Manifest key config.countSubtitle. Goes through the host translate function. { singular, plural } picks the form by the total ("1 invoice", "12 invoices") through the app's plural translation (translatePlural with the app id CnAppRoot provides), so a language with other plural rules gets its own forms. | |
showTitle | boolean | false | Whether to show the page header (icon, title, description) inline. When false (default), only the sidebar header shows the title visually — but the <h1> is still rendered visually-hidden inside the page, so the <main> landmark always has an accessible heading. This prop controls VISIBILITY only; it can no longer remove the heading from the accessibility tree. | |
routeState | boolean | true | Whether the list writes its filters, search and sort into the address ($route.query), so a reload or a shared link shows the same view. A list embedded in another page (the index-list widget in a detail tab) sets this false: the address belongs to the page. | |
showTitleIcon | boolean | true | Whether the page header draws its icon before the title. false (manifest config.showTitleIcon: false) drops it, for a title that stands alone as the board draws it. True by default. | |
showCount | boolean | true | Whether the actions bar shows its "Showing 20 of 258" line. false (manifest config.showCount: false) drops it, for a page whose title line already gives the total (countSubtitle). True by default. | |
look | ('' | 'board' | 'nextcloud') | undefined | Draw this page in the board look (or nextcloud) whatever the app does. Empty follows the cnLook CnAppRoot provides. Manifest key config.look. | |
countText | string | '' | Board look: the count line under the title, a template with {shown} (rows on this page) and {total} (all rows) and free text. Manifest key config.countText. Without it the page's countSubtitle, else "{shown} of {total}". | |
countTextFiltered | string | '' | The count line while a filter narrows the list (from the address, the side panel, a filter strip or a quick filter), in either look: a template with the countText tokens ({shown}, {total}, countValues names), such as "{read} of {total} read" over the messages of one sending. Manifest key config.countTextFiltered. Empty (the default) keeps the count line as it is. | |
savedViewCountText | string | '' | Board look: the count line while a saved view is applied (manifest config.savedViewCountText), a template as countText that may name the view's conditions as {view}: its description, else its filters in words (DqFilterInMenu "3 van 48 lopende zaken · termijn binnen 7 dagen, van mij · gesorteerd op termijn"). A view's own countText override and a scope's come first. | |
countValues | Record<string, object>|null | null | Named values the board count line can carry besides {shown} and {total} (manifest config.countValues), each written as a template token with a format: {pipeline|currency:EUR}. An entry is a sum or count over this page's register and schema, under the list's active filters plus its own filter ({ metric: 'sum', field: 'value', filter? }), or a field read from an app endpoint ({ endpoint, path, followFilters? }; followFilters: true sends the active filters along as filter[<field>]=<value>). A value not read (yet) leaves its token empty (board PqLeads "€ 509.928 in de pijplijn"). unfiltered: true reads an aggregation under the page's own filter only, so the footer note can name the whole list ("73 aanmeldingen in totaal"); the footer note fills the same tokens. | |
countTextByView | object | null | Board look: a count line per view (manifest config.countTextByView), { table?, cards?, list?, board?, map? }, each a template as countText: the board view says "bordweergave per status" where the table says "gesorteerd op termijn" (DqWerkbord, DqZaken). A view it does not name keeps countText; a scope's own countText comes first. | |
cardFields | Array<string> | null | The property keys the card's facts list shows, in order (manifest key config.cardFields). Without it the board look shows the first four list columns. | |
expandableRows | object | null | List view: every row opens to a sub-table (CnExpandableRow). { title, badge?, description?, chips?, meta?, table?, buttons?, open?: 'first' | 'all' }; a header button or the footer action names a row action by its id, which runs as in the row's menu. Manifest key config.expandableRows (index-expandable-rows). | |
tableTitle | string | '' | A title at the top of the table view's card (manifest key config.tableTitle), in the host's translation. Under the board look the head row of a titled table reads on the card's white with a rule under it (board PqInloop "In de wachtrij"). | |
cardLayout | object | null | Board look: the record layout of each card in the cards view (manifest key config.cardLayout): { headPill, number, title, meta, footerPill, footerDate }, each part naming a field. See CnObjectCard layout. | |
cardAccent | ((object: object) => ({variant: string, icon: string, label: string}|null))|null | null | Gives each card in the card view a status accent: a colored start border and icon. See CnObjectCard accent. | |
footerNote | string | '' | Board look: free text after the footer's count ("8 of 48 · click a column header to sort"). Manifest key config.footerNote. | |
pagerOnOnePage | boolean | true | Board look: whether a list that fits on one page still draws its count and the "1" with an inert Next (manifest config.pagerOnOnePage). Off, it ends in its footerNote alone, as PqWachtrij does. | |
footerNoteByView | object | null | Board look: the footer note per view (manifest config.footerNoteByView), { table?, cards?, list?, board?, map? }, each a template as footerNote: DqZakenSorteren's cards say "sorted by deadline, ascending · sort in the side panel" where the table says "click a column header to sort". A view it does not name keeps footerNote; a scope's, saved view's or preset's own note comes first. | |
bulkBandAlways | boolean | false | Board look: draw the bulk band before anything is selected too, its buttons disabled until there is a selection (DqZaken, DqWerkbord). Manifest key config.bulkBandAlways. Only when the band has an action to offer. | |
bulkHint | string | '' | Board look: the 13px hint after the bulk band's buttons ("See what changes first, then run it"). Manifest key config.bulkHint. | |
bulkBandViews | object | null | Board look: another shape of the bulk band per view mode, keyed by the view (board, cards, ...). { lead?: { one, other }, actions?: Array<id|{ id, label? }>, cancel?: boolean, hint?: boolean }: the lead counts the selection ({count}, through the app's translate), actions picks and relabels bulk actions, cancel adds a Cancel button that clears the selection, hint: true keeps bulkHint. In such a view the band shows only with a selection and without the built-in copy and delete (DqWerkbord: "1 zaak geselecteerd · Status wijzigen · Annuleren"). Manifest key config.bulkBandViews. | |
bulkNoun | string | '' | Board look: the plural the bulk band names ("With the selected cases"), through the app's translate and lower-cased. Wins over the schema's plural. Manifest key config.bulkNoun. | |
headerButtons | Array<{label?: string, action: string, variant?: ('primary'|'secondary'), icon?: string, format?: ('csv'|'excel'), id?: string, items?: Array<(string|{heading: string})>, placement?: ('header'|'tabs')}> | [] | Buttons beside the page title, as the board's "Export" and "New case" (manifest config.headerButtons). Each is { label?, action, variant?, icon?, format?, id? }: action is add (the Add flow; its label defaults to the Add label), export (the export leaf in format, csv by default, else the export dialog; with run the headerActions entry of that id; on an entitySource page without run and without a @mass-export listener it is not drawn), import, refresh, save-view (the save-current-view dialog: the board's "Zoekopdracht opslaan", label "Save view" by default), or the id of a headerActions entry; variant is primary or secondary (the default). Shown only with showTitle. When they show, the actions bar drops its Views and Actions menus, and the Add button and Export menu when a button takes their action. Empty (the default) changes nothing. action: "actions-menu" is one labelled menu: the page's header actions, or what its items name (header-actions, a header action id, import, export, refresh, copy-selected, delete-selected, documentation), so the entries the bar's menu loses have a place. items can group them: { heading } draws a group heading (an i18n key) and separator a rule, each only when an entry follows. placement: "tabs" on the menu draws it at the end of the page tabs' row instead of in the header (PqBiExport); without page tabs it stays in the header. | |
buildiqButton | boolean | true | Whether the actions bar may draw the buildiq square. false for a list embedded in a page that draws its own (CnIndexListWidget), so a page carries one square. | |
showActionsMenu | boolean | null | Whether the toolbar draws the Actions menu (manifest config.showActionsMenu): true keeps it beside header buttons (DqAfdelingen: Downloaden beside the title, Acties above the search), false leaves it out. Null derives it: drawn unless the header carries buttons. | |
rowTitle | string | 'link' | How the board look draws the table's title column (manifest config.rowTitle): link (the default) underlines the title, plain draws it as bold text without an underline over a 13px muted secondary line, text as an ordinary 14px cell and strong as a 14px weight 600 name in the main ink. The row stays clickable. The Nextcloud look ignores it. Maps to CnDataTable rowTitle. | |
icon | string | '' | Optional MDI icon name. Defaults to schema.icon when a schema is provided. | |
schema | object|string | null | Schema. Either a resolved schema object (consumer-managed path) OR a schema-slug string — when a string is given together with register and no objects prop, the page enters self-fetch mode: it drives the list via useListView('\$\{register}-\$\{schema}', …) and the column generation uses the schema object that composable loads. Backwards- compatible: [Object, String] still accepts an object. | |
filter | object | null | Base filter for the self-fetch path. String values of the form "@route.<name>" / ":<name>" are interpolated from $route.params. | |
quickFilters | array | null | Self-fetch mode only — an array of clickable filter tabs rendered as a strip above the table. Each entry is {label, filter, default?, icon?}; clicking a tab merges its filter into the fetch — spread AFTER filter (so the active tab wins) and BEFORE the user's activeFilters (so user facets still narrow within the active tab). String values in a tab's filter resolve @route.<name> / :<name> from $route.params just like the filter prop. The first tab with default:true (else index 0) is active on mount; changing tabs re-fetches at page 1. Omit (or null) → no tab strip, behaviour unchanged. Under the board look a tab with activeLabel ("Pipeline: Sales") adds a removable chip with that text to the Active line and counts on the Filter badge while it is selected; removing the chip goes back to the default tab. A tab can say empty: "field" (or a list of fields) for the rows where the field has no value, and notEmpty for the rows where it has one: it reads as the filter { field: { isnull: true } }. A tab can set its own order with sort: { key, order } (or a list of those): selecting it sorts the list that way, and selecting a tab without sort goes back to the page's sortKey/sortOrder. A column the person sorts by still wins until the next tab switch. | |
quickFiltersFrom | {field: string, register?: string, schema?: string, valueField?: string, labelField?: string, allLabel?: string}|null | null | Quick filters made from the values a field holds in this list (manifest config.quickFiltersFrom): { field, register?, schema?, valueField?, labelField?, allLabel? }. The page asks OpenRegister for the distinct values of field with their counts (within filter) and draws "All" plus one tab per value, the most frequent first, each with its count. With register and schema the values are ids of records of that schema and each tab shows the record's labelField (else its title or name). With valueField as well, the values are matched on that field of those records instead of their id (a slug). Ignored when quickFilters is set. | |
personalLenses | Array<'favourite'|'recent'|'watching'|'unread'> | [] | Personal lenses appended to the quick filters: any of watching (_watching, labelled Following), recent (_recent) and unread (_unread). favourite is a deprecated alias of watching: a favourite is a follow now, and asking for both gives one tab. They combine with every other filter. While Recent is active column sorting is off, because the lens owns the order. Manifest config.personalLenses. | |
showUnreadRows | boolean | null | Whether the table marks unread rows (@self.unread) in bold with the unread marker: true in every look, false never. Unset (null) keeps the look's default (see marksUnreadRows). Manifest config.showUnreadRows. | |
showFollowColumn | boolean | false | Add a first column with a follow toggle per row (CnFollowToggle, compact), bound to each row's @self.watching. Clicking it does not open the row. Manifest config.showFollowColumn. | |
showFavouriteColumn | boolean | false | Deprecated alias of showFollowColumn: the star column became the follow column (OpenRegister merge-follow-and-favourites). | |
filterStrip | {field: string, label?: string, allLabel?: string, options?: Array<{value?: string, values?: Array<string>, label?: string}>, showCount?: boolean}|null | null | A second filter strip under the toolbar, on one field (manifest config.filterStrip): { field, label?, allLabel?, options?: [{ value | values, label }], showCount? }. It draws "All" and one pill per value (the options, else the field's schema enum); picking one sets the page's filter on that field, "All" clears it. An option's values gathers several stored spellings under one pill. With showCount each pill counts the rows it would show within the active quick filter. Absent (the default) draws nothing. | |
savedViewChips | boolean | true | Whether the board look draws the saved views as chips in the toolbar (manifest config.savedViewChips). false keeps only Save view, for a page whose views live in the side panel's Weergaven tab (DqZaken, DqZakenSorteren, DqZakenKaart, DqWerkbord, DqFilterBeheren). | |
savedViewSave | boolean | true | Whether the toolbar draws Save view (manifest config.savedViewSave). false leaves it out for a page whose board draws none (DqTaken, DqOrganisaties); the views stay in the side panel. | |
savedViewShare | boolean | false | Whether the toolbar offers to share the open saved view (manifest config.savedViewShare): "Share: {name}" beside Save view, for a view of the reader's own, opening the side panel's share dialog (PqTicketsSelectie). | |
savedViewTitle | boolean | false | Whether an applied saved view names the page and its side panel (manifest config.savedViewTitle): a view opened from the menu or the panel heads the list with its own name (DqFilterInMenu "Termijn deze week"). Off, the page keeps its title. | |
quickFilterPlacement | string | '' | Where the quick-filter chips sit (manifest config.quickFilterPlacement). '' (the default) as before. 'toolbar' keeps them on one row with the Filter button and the view switch, in whatever width that row has beside a side panel (DqTeamwachtrij): the chips take the room the buttons leave, and those that do not fit move into the overflow chip. 'row' puts them on a row of their own above the toolbar, wrapping onto more lines instead of folding into the overflow chip. 'active' draws no tabs: a chosen tab with an activeLabel shows only on the Active line, where it can be removed (DqAanMijToegewezen). | |
quickFilterPlacementByView | object | null | The quick-filter placement per view mode (manifest config.quickFilterPlacementByView): { table?, cards?, board?, map? }, each '', 'toolbar', 'row' or 'active'. A view it does not name keeps quickFilterPlacement (dossiq's case list: the chips beside Filter in its board and map views, on their own row in its table view). | |
searchPlacement | string | '' | Where the board look's search field sits (manifest config.searchPlacement): '' (the default) opens row 2 with it, 'toolbar' puts it on row 1 before the Filter button and the view switch (DqTeamwachtrij). | |
quickFilterMode | string | 'chips' | How the quick filters render: 'chips' (pill strip, default) or 'dropdown' (a single NcSelect). Sourced from the manifest as pages[].config.quickFilterMode. | |
quickFilterMultiple | boolean | false | Allow several quick filters active at once. Selected tabs' filters are OR-ed together into the fetch (same field → array value → field[]= IN query). Sourced from pages[].config.quickFilterMultiple. | |
quickFilterMaxVisible | number | 0 | Chips mode only: how many quick-filter pills render inline before the rest move into an overflow menu. 0 (the default) renders every tab. A long strip wraps the actions bar onto a second line and squeezes the "Showing X of Y" count, so a page with many lenses caps this and keeps the everyday few in view. Sourced from pages[].config.quickFilterMaxVisible. | |
filterLabels | object | \{\} | How the Active line names a filter: per filter key an optional label for the field and values naming each value, both through the app's translate. Wins over the schema and sidebar names. Sourced from pages[].config.filterLabels. A range filter's entry may set relative: true, naming a range from today in words ("within 7 days"). An entry with hidden: true is a working-list rule every view carries: the line that says what a saved view shows leaves it out. | |
columns | array | [] | Manual column definitions (used instead of schema when provided) | |
extend | array | [] | OpenRegister _extend[] values forwarded on the fetch, e.g. ["calculations"]. Sourced from pages[].config.extend. A schema's x-openregister-calculations entries declared materialise: false are VIRTUAL: RenderObject evaluates them only when the caller asks for them through _extend, so without this a declared calculation is simply absent from every row and its column renders empty. The same contract objectTableSource.extend already carries for dashboard widgets, which is where it shipped first; index pages could not ask for it at all. | |
collectionUrl | string | '' | Self-fetch only: list from this endpoint instead of /api/objects/{register}/{schema}, e.g. an app endpoint that searches several register/schema pairs at once. register and schema stay the page's own pair (columns, create, export, import). Rows of another pair, read from their @self.register / @self.schema, are edited, copied and deleted against that pair, with its own form. The endpoint takes _page, _limit, _search and _order[key]=dir and answers { results, total, page, pages }. | |
searchInFiles | boolean | false | Offer an "Also search inside files" switch beside the search box. On, a search also matches words inside attached files (OpenRegister _content_search), and a row found that way says which file matched. Manifest: config.searchInFiles. | |
relatedFieldFilters | object | null | Filters over a type's own declared fields, beside the search (CnRelatedFieldFilters): { definitions: { register, schema, filter }, related: { schema, backref, definitionKey?, valueKey? } }. Manifest: config.relatedFieldFilters. | |
objects | array | [] | Object/row data array | |
entitySource | string | '' | Name of a registered NON-OBJECT entity collection to list (e.g. flows). The third data mode. register + schema fetches OpenRegister objects; :objects renders rows a parent already holds; entitySource names a list that is neither — a flow definition is deliberately not an OpenRegister object, so an index had nothing to point at and such lists became bespoke type: "custom" pages instead. Non-empty :objects still wins, and an entity source wins over register/schema. See src/composables/indexSources.js. | |
rowRoute | string | '' | Route name a clicked row opens, overriding a named source's own navigation. An entity source knows where its rows live and navigates itself, and for a source whose detail page belongs to ANOTHER app that is right: tasks sends a click to openregister's task page, because pushing on this app's router could not reach it. It is wrong for an app that HAS its own page for those rows. Dossiq keeps a task detail page on purpose, so its handlers see a task in dossiq's vocabulary beside the case it belongs to. Without this prop adopting entitySource: "tasks" would send every click out of the app, and the row-click event cannot recover it: openRow calls window.location.assign(), so a host's push never lands. Set it and the row pushes { name: rowRoute, params: { id } } on this app's router instead. Leave it unset and the source's own navigation is unchanged, which is what every current consumer gets. | |
sourceConfig | object | null | Config handed to the named source's loader (e.g. { app: 'dossiq' }). | |
pagination | object | null | Pagination state: { page, pages, total, limit } | |
loading | boolean | false | Whether data is loading | |
selectable | boolean | true | Whether rows/cards can be selected | |
hideTableHeader | boolean | false | Draw the table without its column-header row (manifest config.hideTableHeader), for a list the board draws as plain rows (DqTeamwachtrij). Pair it with selectable: false for no checkboxes. | |
rowClickToView | boolean | false | When true, a row/card click emits row-click (to open/navigate) even while selectable — selection then happens via the checkbox only. Manifest-driven index pages set this when a matching detail page exists, so clicking a row opens its detail. Default false preserves the legacy select-on-click behaviour. | |
splitView | { enabled?: boolean, breakpoint?: number, paneWidth?: string } | \{\} | The page's splitView declaration: { enabled, breakpoint, paneWidth }. With enabled, opening a row renders it beside the list in the #split-pane slot instead of navigating away, and the list keeps its scroll position, its selection and its loaded page. Omit it and the page renders exactly as it does today. | |
splitId | string | '' | The record the split pane is showing, taken from the split address. Empty closes the pane. Ignored unless splitView.enabled. | |
splitCloseRoute | string | '' | Route name the pane's close button returns to. Defaults to the current route's own list address when omitted. | |
splitCloseButton | boolean | true | Whether the pane draws its own close link. Set false when the #split-pane slot draws one from the slot's close. | |
splitCloseLabel | string | '' | Accessible name and tooltip for the pane's close button. | |
personalColumns | boolean | true | Lets this person order and pin the table columns from the sidebar's Columns tab, and keeps the visible columns, their order and the pinned count per user and per list in their Nextcloud preferences. false keeps show and hide only, stored nowhere (for a page whose column set is a contract, such as an export preview). | |
manualOrder | boolean | false | Lets this person drag the rows into an order of their own, held against them and this list and never written onto the records. The order stands down while a sort is active, because a sort the person just chose is them asking for a different order. | |
manualOrderId | string | '' | Stable id this list's manual order is held under. Defaults to the object type or the schema, so two lists of one schema on different pages share an order only when the host says they should. | |
selectedIds | array | [] | Currently selected IDs | |
viewMode | string | 'table' | View mode: 'table', 'cards', 'list', 'map', 'board', 'dateAxis' or 'calendar'. Default 'table'. List is opted in via availableViewModes; map via mapConfig / config.viewModes; board and dateAxis via config.viewModes and their own config blocks. | |
mapConfig | { latField?: string, lngField?: string, geoField?: string, popupField?: string, center?: [number, number], zoom?: number, list?: object } | \{\} | Marker geometry mapping for the opt-in map view mode, mirroring the manifest config.map block 1:1. When non-empty (and not excluded by an explicit config.viewModes), a third "Map" segment appears in the view toggle and the current filtered rows are plotted on a CnMapWidget. - latField / lngField — object (or @self) property paths holding the marker's latitude / longitude. Dotted paths are supported (e.g. @self.geo.lat). - geoField — alternative single property holding a GeoJSON Point geometry ({ type: 'Point', coordinates: [lng, lat] }); takes precedence over lat/lngField when present and resolvable. - popupField — object property rendered in the marker popup. - center — optional [lat, lng] fallback centre when the filtered set has no plottable rows. - zoom — the map's initial zoom level. - list — a numbered list beside the map, map and list in one card (DqZakenKaart): { title, sub?, pills?: [{ path?, text?, map?, colorMap? }], due?, missingTitle? }, field templates read per row. The pins carry the list's numbers, the row under the pointer is marked on both, the rows without a place are counted under the list with a link to the table (titled by missingTitle, { singular, plural } with {total}, else "8 without an address"), and the page's count line adds how many are on the map. | |
mapLabel | string | '' | Label for the map view-toggle segment (defaults to "Map"). | |
mapIcon | string | '' | MDI icon name for the map view-toggle segment (defaults to the built-in map-marker icon). | |
viewModes | Array<'table' | 'cards' | 'list' | 'map' | 'board' | 'dateAxis' | 'calendar'> | null | Explicit whitelist of view-toggle segments to offer, e.g. ['table', 'cards', 'map']. Fed from the manifest as pages[].config.viewModes. When set it takes precedence over the inferred availability (map otherwise appears iff mapConfig is non-empty). Cards/table always render regardless of this list. | |
viewSwitch | Array<'table' | 'cards' | 'board' | 'map'> | null | Board look: the segments the view switch draws, e.g. ['table', 'cards', 'board', 'map'] as the boards do. A listed mode the page can open is an ordinary segment; one it cannot (no board columns, no map configured) is drawn disabled, named "<mode>: not available on this list". Fed from pages[].config.viewSwitch. Ignored without the board look; absent, the board look draws all four. | |
viewSwitchLinks | {[mode: string]: {route?: string, params?: object, query?: object, href?: string}} | null | Board look: view switch segments that open another PAGE, by mode (table, cards, board, map): { board: { route: 'CaseBoard', params?, query? } } or { map: { href: '/apps/x/map' } }. The segment sits in its place in the switch as a link, for a board or a map that is a page of its own. A mode this page opens in place stays a button. Fed from pages[].config.viewSwitchLinks. Ignored without the board look. | |
board | object | \{\} | The board's configuration, mirroring the manifest config.board block: { statusField, cardFields, swimlaneField }. The board is offered only when this names a statusField AND viewModes lists board: a segment that opens a board saying it cannot be one is worse than no segment. | |
dateAxis | object | \{\} | The date axis's configuration, mirroring the manifest config.dateAxis block: { startField, endField, laneField, labelField }. Offered only when both date fields are named. | |
calendar | {dateField?: string, endDateField?: string, titleField?: string} | \{\} | The calendar's configuration, mirroring the manifest config.calendar block: { dateField, endDateField?, titleField? }. Offered only when dateField is named and viewModes lists calendar. Only the visible month is fetched. | |
runTransition | ((move: { card: object, toKey: string }) => Promise<object>)|null | null | The host's transition, handed to the board. Absent, the board is read-only: it never writes the status field itself, so with no transition there is nothing it can do. | |
availableViewModes | Array<'cards' | 'table' | 'list' | 'map' | 'board' | 'dateAxis' | 'calendar'> | ['cards', 'table'] | Which view-mode toggle segments to expose (cards/table/list), in order. Defaults to the historical Cards/Table pair; include 'list' to offer the list view. Fed from the manifest as pages[].config.availableViewModes. Map is added separately via mapConfig / viewModes. | |
sortKey | string | null | Current sort key | |
sortOrder | string | 'asc' | Current sort order | |
sortKeys | Array<{key: string, order: 'asc'|'desc'}> | [] | Ordered multi-column sort state (host-controlled / non-self-fetch mode): [{ key, order }, ...], mirroring the sortKey/sortOrder pair but for more than one active key. Ignored in self-fetch mode (register + schema), which manages its own multi-sort state via useSelfFetchList/useListView and persists it in the route query. | |
defaultSort | Array<{field: string, order?: 'asc'|'desc'}> | [] | Optional declarative DEFAULT multi-key client-side sort, applied to the already-loaded rows whenever no explicit column sort is active (no sortKey selected by the user / passed in). Each entry is { field, order } with order one of 'asc' / 'desc' (default 'asc'); rows are compared by the first field, ties broken by the next, and so on. Comparison is type-aware (numbers numerically, dates by timestamp, strings via localeCompare). Clicking a sortable header takes over and suppresses this default. Useful for a fixed presentation order such as "group by type, then name". | |
rowKey | string | 'id' | Unique row identifier property | |
rowIcon | string | ((row: object) => string) | {field: string, icons: object, tones?: object, icon?: string} | null | null | Optional leading icon for every table row — a static MDI icon name or a (row) => iconName function. Forwarded to CnDataTable. Fed from the manifest as pages[].config.rowIcon. Unset = no icon column. An object { field, icons, tones?, icon? } picks the icon and its tile tone by a field of the row (see CnDataTable). | |
rowIconTone | string | 'primary' | The leading icon's tile tone in the board look (primary, teal, neutral), from pages[].config.rowIconTone. Forwarded to CnDataTable. | |
excludeColumns | array | [] | Columns to exclude in schema mode | |
includeColumns | array | null | Columns to include in schema mode (whitelist) | |
columnOverrides | object | \{\} | Per-column overrides in schema mode | |
actions | array | [] | Row action definitions, merged with the built-in View / Edit / Copy / Delete. Objects are app actions. A "builtin:view", "builtin:edit", "builtin:copy" or "builtin:delete" string places that built-in at its position when its show*Action toggle is on; enabled built-ins not placed are appended in that order. | |
emptyText | string | () => t('nextcloud-vue', 'No items found') | Text shown when no items found. The default is the library's own string, so it reads in the user's language; a page's own text goes through the app's translate function. | |
lenses | union | null | Personal-lens report of the list on screen, for a host that fetches itself: the response's @self.lenses ({ recent: { available, reason } }). In self-fetch mode the page reads it from the store and this prop is ignored. When a lens reports available: false the empty state explains why instead of showing emptyText. | |
lensReasonTexts | {[key: string]: string}|null | null | App wording for an unavailable lens, keyed <lens>.<reason> (recent.audit-trail-disabled) or <reason>; the specific key wins, and both win over the library's object-neutral text. | |
searchRefusalHint | string | '' | What to do after a refused search, through the app's translate. The default explains AND, OR, NOT and quotes. | |
loadingText | string | 'Loading…' | Accessible label for the loading spinner (NcLoadingIcon aria-label) | |
live | Array<string> | [] | Object types whose live changes this list follows (manifest config.live): it subscribes to them through the object store and reads the list again shortly after a change, so a card a colleague moved moves here too. Empty (the default) subscribes to nothing. | |
rowClass | ((row: object) => string)|Array<{when: {field: string, op?: string, value: unknown}, class: string}>|null | null | CSS class(es) for a row: a function (row) => string, or (manifest config.rowClass) rules [{ when: { field, op?, value }, class }], each adding its class to a row whose field compares to the value (the visibleWhen operators, @today included). DqTaken marks an overdue task: { when: { field: "dueAt", op: "lt", value: "@today" }, class: "cn-row--overdue" }. | |
addLabel | string | '' | Override label for the Add button. Defaults to "Add {schema.title}" | |
rowInlineActions | number | 0 | How many of a row's actions show as buttons beside its menu, the first as a tonal pill (manifest config.rowInlineActions, board PqWachtrij "In behandeling nemen" and an eye). 0 keeps them all in the menu. | |
inlineActionCount | number | 0 | How many action buttons to show inline (rest go in overflow dropdown) | |
showMassImport | boolean | true | Whether to show the built-in mass Import action | |
importTemplate | boolean | false | The import dialog offers OpenRegister's empty import template for this schema. | |
importMapping | boolean | false | The import dialog maps each column of a CSV or JSON file to a schema field. | |
importCheckFirst | boolean | false | The import dialog offers to check the file first and import nothing. | |
showMassExport | boolean | true | Whether to show the built-in mass Export action | |
copy | {include?: Array<'relationRows'|'incoming'|'files'>}|null | null | Copy settings from the manifest's config.copy. include lists the link kinds a copy may take along (relationRows, incoming, files); the copy dialogs then list them, ticked, and the copy is one request to OpenRegister's copy endpoint. Without it a copy carries the fields only, as before. A server without the endpoint shows the list read-only. | |
showMassCopy | boolean | true | Whether to show the built-in mass Copy button | |
showMassDelete | boolean | true | Whether to show the built-in mass Delete button | |
allowExport | boolean | false | Opt-in flag for the native Export menu (CSV/Excel) rendered in the toolbar next to the Add button. Defaults to false — an app must explicitly enable it per page. The menu only renders when this is true AND the resolved schema is flagged exportable: true; it navigates the browser to OpenRegister's export leaf (GET /apps/openregister/api/objects/{register}/{schema}/export), passing the current route's query params through as filters. This is distinct from the showMassExport mass-action, which exports only the fetched/selected rows via a blob download. | |
allowSavedViews | boolean | null | Saved views (saved-views-ui). Unset, the sidebar's Views tab is on for every page with a sidebar and a source a view can be scoped to (register and schema, entitySource or savedViewsScope); false turns it off. true also forces the sidebar and adds the toolbar control, where a Views dropdown lists the current user's OpenRegister saved-search views (GET /apps/openregister/api/views); applying one writes its stored filters/search/sort into the route query (reusing the existing deep-link contract — non-underscore keys are filters, _search and _order are reserved), "Save current view…" persists the current route-query state via POST and toasts either way naming the view (a failure also keeps the dialog open with the reason), and own views can be deleted after confirmation. | |
savedViewsScope | string | '' | Which pages share this page's saved views. By default a view is shared by every page over the same register and schema and by no other page, because a view is filters over one schema's fields. Set this to share views across pages over different sources, or to keep two pages over the same source apart. Written into the saved view's query.scope; views saved before scoping stay visible everywhere. | |
defaultSavedViews | array | [] | Views the app ships for this page (config.defaultSavedViews), each { slug, name, filters, search?, sort?, label? }. Listed read-only above the user's own saved views, never stored; a user may apply one or save a copy. @-tokens in filters resolve when it is applied. | |
massActionNameField | string | 'title' | Property name used to display item names in dialogs | |
nameFormatter | func | null | Optional function to format item names in dialogs. Receives the item, returns a string. Overrides massActionNameField when provided. | |
exportFormats | array | [ \{ id: 'excel', label: 'Excel (.xlsx)' \}, \{ id: 'csv', label: 'CSV (.csv)' \}, ] | Available export formats for the export dialog | |
importOptions | array | [] | Import option definitions for the import dialog | |
showFormDialog | boolean | true | Whether to show the built-in form dialog for Add/Edit | |
createModal | string | '' | Registry key of a kind: 'modal' entry that Add (and ?action=create) opens instead of the built-in form dialog. Edits keep the form dialog. | |
useAdvancedFormDialog | boolean | false | Use CnAdvancedFormDialog (properties table, JSON tab, optional metadata) instead of CnFormDialog for Add/Edit | |
formSize | string | 'normal' | NcDialog size for the built-in Add/Edit form dialog. The dialog itself has taken a size since it shipped, but this page never passed one, so an index page's Add form was stuck at normal however many properties its schema declared. A manifest-declared open-form header action, which reaches CnFormDialog through CnActionButtons, could already ask for large — which is why the same app could have a roomy create form on a detail page and a cramped one on its index. | |
formColumns | number | 1 | How many columns the built-in Add/Edit form flows its fields into. Pair 2 with formSize: 'large', or the two columns are merely two narrow ones. Worth it once the schema asks more questions than fit on a screen; below 700px CnFormDialog collapses back to one column on its own, so this is safe on a narrow viewport. | |
draftAppId | string | '' | The app a form draft belongs to, forwarded to every form this page opens as CnFormDialog's draftAppId, so what a user typed and did not save is kept and offered back under this app's key. | |
allowDraft | boolean | false | Offer "Save draft" on the create form, forwarded as CnFormDialog's allowDraft. On an edit form it is offered only while the record is still a draft: saving a record that is already in use as a draft would take it out of use. | |
draftField | string | 'isDraft' | The boolean property that marks a record as a draft (CnFormDialog's draftField). | |
createDefaults | union | null | Seed values for the built-in create dialog. Never applied on edit: both dialogs consult initialData / initialValues only when there is no item. Values resolve @me / @now / @today at any depth; @object.* / @workspace.* / @config.* need a context this page does not carry, so they pass through unresolved. | |
createSuccessRoute | union | null | Where to go after a successful create from the built-in Add dialog. A route name, or { name, paramField?, objectParam? }; the created object's id is merged into the params. Empty stays on the list. | |
createSuccessMessage | string | '' | Toast shown after a successful create from the built-in Add dialog, run through the host cnTranslate. Empty shows none. | |
createOverride | union | null | Opt-in async create hook. When provided, a create (not edit) confirmed from the built-in form dialog calls await createOverride(formData, ctx) INSTEAD of persisting via the store / self-store saveObject. The override owns persistence (e.g. an app posting through a contact-aware endpoint that fills a required FK before saving to OpenRegister) and MUST return the created object (a truthy value) on success; return a falsy value to signal failure. The returned object is used as the created result (@create payload + dialog success). Throwing rejects with the error surfaced in the form dialog. Edits are never routed here. ctx carries { register, schema, objectType, effectiveSchema } so a single handler can branch per schema. When absent, create behaviour is unchanged (store / self-store save). | |
showViewAction | boolean | true | Whether to add a View action to row actions. The action emits a dedicated view event — independent of row-click. Bind @view to handle "open detail" and @row-click to handle row click (selection, expand, etc.); they may share a handler when the app wants click-to-view, but they are conceptually distinct. On a named entitySource page the effective default is FALSE: the source's own open action navigates to the detail page, which is the view. Passing the prop explicitly still wins. | |
viewTo | func | null | Where the View row action points, as (row) => location | null. When it returns a location, View renders as a link to it (middle click, copy link) and does not emit view; when it returns null, View stays a button that emits view. CnPageRenderer sets it to where a row click opens. | |
showEditAction | boolean | true | Whether to add an Edit action to row actions. On a named entitySource page the effective default is FALSE: a source has no schema, so the form modal this action opens could only ever render empty — the source declares its own Edit, which navigates. Passing the prop explicitly still wins. | |
editOpensDetail | boolean | false | Send the Edit row action to the record's detail page instead of opening the edit modal, by emitting edit-open rather than showing the form dialog. OFF by default, and CnPageRenderer no longer derives it: the host binds @edit-open to the same navigation as a row click, so an Edit that routes is an Edit that does what clicking the row does — the split pane, or the detail page — while the form it names becomes unreachable from the list. Set it when the modal genuinely cannot express the record and you accept the duplication: it renders the schema's flat scalars only, so related rows, sub-resources and tabs stay uneditable there. | |
showCopyAction | boolean | true | Whether to add a Copy action to row actions. On a named entitySource page the effective default is whether the source implements copyRow — without it, the copy dialog's confirm has nowhere to go. Passing the prop explicitly still wins. | |
showDeleteAction | boolean | true | Whether to add a Delete action to row actions. On a named entitySource page the effective default is whether the source implements deleteRow — without it, the delete dialog's confirm has nowhere to go. Passing the prop explicitly still wins. | |
excludeFields | array | [] | Field keys to exclude from the form dialog | |
includeFields | array | null | Field keys to include in the form dialog (whitelist mode) | |
fieldOverrides | object | \{\} | Per-field overrides passed to CnFormDialog | |
showViewToggle | boolean | true | Whether to show the Cards/Table view toggle in the actions bar | |
inlineSearch | boolean | false | Show an inline search field in the actions bar (in addition to / instead of the sidebar search). Fed from the manifest as pages[].config.inlineSearch. | |
search | boolean | true | false draws no inline search in the actions bar, also in the board look, which otherwise draws one on every index page. Fed from the manifest as pages[].config.search. | |
appConfig | object | \{\} | The app config @config.<key> tokens resolve against, in quick-filter filters and labels ("Residence @config.municipality"), as on the dashboard and detail pages. Merged over a config an ancestor provides on cnAppConfig. Manifest: config.appConfig. | |
showCountWithSearch | boolean | false | Keep the "Showing X of Y" counter visible beside the inline search field, after any #after-search controls (only relevant with inlineSearch, which otherwise takes the counter's place). Fed from the manifest as pages[].config.showCountWithSearch. | |
searchPlaceholder | string | '' | Placeholder for the inline search field (manifest config.searchPlaceholder) | |
searchPlaceholderByView | object | null | A search placeholder per view (manifest config.searchPlaceholderByView), { table?, cards?, board?, map? }, through the app's translate: the board view asks "Zoek op zaak of verzoeker", the map "Filter op zaak of aanvrager" (DqWerkbord, DqZakenKaart). A view it does not name keeps searchPlaceholder. | |
cardsLabel | string | '' | Label for the cards view-toggle option (manifest config.cardsLabel, e.g. "Tiles") | |
tableLabel | string | '' | Label for the table view-toggle option (manifest config.tableLabel, e.g. "List") | |
cardsIcon | string | '' | MDI icon name for the cards view-toggle option (manifest config.cardsIcon) | |
tableIcon | string | '' | MDI icon name for the table view-toggle option (manifest config.tableIcon) | |
listLabel | string | '' | Label for the list view-toggle option (manifest config.listLabel, e.g. "Rows") | |
showSortSelect | boolean | false | Deprecated, without effect: the toolbar draws no sort select. The table sorts by its column headers, the list, card and map views by the Sort section in the index sidebar. | |
sortSelectOptions | union | [] | The orders the index sidebar's Sort section offers in the list, card and map views (manifest config.sortSelectOptions): { value, label, order?, default?, source? }, the order its order (an orderToSortKeys form) or its value read as one. Without them the section offers the sortable columns. An option may name an endpoint source ({ url, params?, rowsPath?, rowPath?, carry?, idPath?, annotate?, searchFields?, failedNote? }) for an order the server cannot sort by: choosing it lists that endpoint's rows in their order, and the page's search, sidebar filters and pager run over them in the browser. default: true opens the page on it unless the address carries an order; a column header click in the table view leaves it for that column's order. When the endpoint fails the list falls back to the option's order and shows failedNote. carry copies entry fields onto each row (a tier a card's head pill reads); with annotate they also reach the rows of every other order, matched on idPath (id by default). The option is chosen by its value (selectSortOption), as a saved view's sortOption does. | |
sortSelectValue | string | '' | Deprecated, without effect: the toolbar sort select is gone; the Sort section in the index sidebar shows the current order. | |
defaultOrder | union | '' | The order a self-fetch page opens on when neither the address nor sortKeys/sortKey gives one (manifest config.defaultOrder): "-createdAt", "priority:desc,title", an _order map or a [{ key, order }] list. | |
listIcon | string | '' | MDI icon name for the list view-toggle option (manifest config.listIcon) | |
listConfig | { titleField?: string, subtitleField?: string, imageField?: string, iconField?: string, iconName?: string, badgeField?: string, badgeVariantField?: string, badgeVariant?: string, badgeColorMap?: object } | \{\} | Field mapping for the default list-view rows (CnObjectRow). Overrides the schema-configuration defaults. Fed from the manifest as pages[].config.listConfig. | |
folderSidebar | object | null | Opt-in folder navigation pane (rendered left of the list). Selecting a folder filters the list by filterField (via the self-fetch filter); "All" clears it. Fed from the manifest as pages[].config.folderSidebar. - source — 'register' (fetch the folder list from an OpenRegister register/schema), 'field' (distinct values of the current rows' field), 'custom' (use folders), or 'files' (NC folders). - register / schema — the OR source for source:'register'. - idField / nameField — which folder object props map to the folder id (the filter value) and display name. Dotted paths supported. - field / filterField — the row field to group/filter by (filterField defaults to field). - folders — explicit folder list for source:'custom'. - allLabel / title / allowCreate — passed to CnFolderSidebar. - scopeViews — the view modes the scope's look (columns, title, count line and the other scope keys) applies in, e.g. ["table", "list"]; other views keep the page's own look. Default: every view. - pane — false draws no pane: the scope still comes from the deep-link filter (?caseType=<id>) and still applies its look, as a list narrowed to one case type does without a folder column. A folder entry is also a SCOPE: it may carry columns, defaultSort and searchFields, and while it is selected the list is shown that way. columns takes the same shapes as the columns prop, and the page's own columns still decides which columns this page has, so a scope naming one the page does not declare is dropped rather than rendered. A source: 'register' folder list reads the same three keys off each row's x-index block, which the folder entry's own value wins over, key by key. A folder entry may also carry schema (and optionally register, defaulting to the page's own). While it is selected the page loads that register and schema instead of its own, with that schema's columns, fetch and live updates; "All", or a folder without schema, restores the page's own. Switching clears the row selection and closes open dialogs. A folder without schema filters the page's schema as before. | |
statRow | Array<object> | [] | KPI tiles above the list (manifest config.statRow): dashboard widget definitions { id, type, title?, content }, usually stat, drawn in an auto-fit row (each at least 200px) in the listed order. Types resolve like dashboard widgets: the app registry, then the dashboard catalog. Empty by default. | |
sidePanel | Array<object> | [] | Cards beside the list (manifest config.sidePanel): dashboard widget definitions { id, type, title?, content, headerLink? } drawn in a 300px column right of the toolbar and the list. Empty by default; below 1024px the column moves above the list. | |
afterList | Array<object> | [] | Cards after the list (manifest config.afterList): dashboard widget definitions { id, type, title?, content, headerLink? } stacked under the list in the listed order, the counterpart of statRow above it. A query preset or a scope can set its own. | |
fixedFilters | union | null | The route query pairs that chose this page's query preset, set by CnPageRenderer. They scope the list, so they show no removable active-filter chip. | |
defaultFilters | union | null | Filters the list opens with (manifest config.defaultFilters), as { field: value | [values] }: applied when the address names no filter and no saved view, shown on the Active line and removed with their chip or "Clear all" like any other filter. An address that names a filter wins (DqContracten "Status: actief en verlopend"). | |
heldDefaultFilters | Array<string>|null | null | The defaultFilters keys that stay while the address names filters of its own (manifest config.heldDefaultFilters). A link to one case type keeps isFinalStatus: false; a link that names the key itself, or a saved view, decides on its own. | |
rowActionField | string | DEFAULT_ROW_ACTION_FIELD | Where a row carries the actions the server says this caller may run on it: a dotted path, read off the rows the list already fetched, so ninety rows cost one request rather than ninety. A row's menu is then the INTERSECTION of what this page declares and what the server allows. An action the server allows but this page has stopped declaring stays out, so a row cannot bring back a button the page removed. An action the page declares but the server refuses stays out too, and its reason is available from rowActionRefusal(row, action). An action matches by its id. The built-in View, Edit, Copy and Delete also match OpenRegister's permission verbs: read permits View and Copy, update permits Edit, delete permits Delete. A row carrying nothing at this path is a server that does not answer about actions, and the page's declaration stands unchanged. | |
rowIndicators | Array<object> | [] | State indicators this page declares for its rows, handed straight to CnDataTable. Each entry is { id, field, equals?, in?, icon, text, tooltip? }. The page declares which indicators exist; a record cannot add one the page has not declared. A page declaring none renders its rows as before. Fed from the manifest as pages[].config.rowIndicators. | |
rowIndicatorCap | number | DEFAULT_ROW_INDICATOR_CAP | How many declared indicators render on the row itself before the rest move into the row menu. Fed from the manifest as pages[].config.rowIndicatorCap. | |
quickEditFields | string[] | [] | The fields a quick edit asks for, opened from a row without leaving the list. Empty means no quick edit. The page names the fields; a record cannot open a form on one the page did not name. Fed from the manifest as pages[].config.quickEditFields. | |
writableField | string | '@self.writableFields' | Where a record lists the fields this caller may write. A field the page named that is not in that list renders read-only rather than missing, so a person sees the value and learns it is not theirs to change. A row carrying nothing there leaves every named field editable. | |
viewTabs | string[] | [] | Saved view ids this page renders as tabs instead of as entries in the views control. A view appears in one place or the other, never both. An id naming a view that no longer exists produces no tab. | |
viewCounts | union | false | Which saved views show how many records they match: true for all of them (tabs and the entries in the views control), or a list of view ids. Off by default, so no count request is made. A quick filter opts in on its own entry with showCount: true. | |
offeredTeams | union | [] | The teams this person may claim. The instance decides this list; it is the membership side of claimedTeams. | |
claimedTeams | string[] | [] | The teams this person stored as claimed, read as a personal preference alongside the others. It is narrowed to offeredTeams, so a team they claimed before it was taken away is passed over rather than honoured. | |
priorityField | string | '' | The field carrying a record's DERIVED priority, and the order its values rank in, lowest first. The list reads the value and sorts on it; it never computes one. A record with no priority sorts after every ranked one, in both directions, and stays in the list. | |
priorityLevels | string[] | [] | The priority values in rank order, lowest first, e.g. ['low', 'medium', 'high']. A value outside this list is unranked. | |
listShortcuts | boolean | false | Offer the list's keyboard shortcuts. Every one of them is also listed in the command palette and on the help key, because a shortcut nobody can find does not count. | |
headerFilters | boolean | true | Per-column filters in the table header: a filter button on every column that can filter, opening a small panel that fits the column (checkboxes, yes/no/any, from and to, a searchable reference list). On by default; a column opts out with filterable: false, a page with pages[].config.headerFilters: false. Filters write into the same active-filter map as the facet sidebar, so they persist in the route query and reach the same OpenRegister query parameters. | |
filterMenu | boolean | false | Show a filter menu (funnel button) in the table header, above the row-actions column. Its menu lists every enum/badge column's values as toggleable facet filters — a compact alternative to the facet sidebar. Under the board look, on a page with no filter sidebar, it is the toolbar's labelled Filter button instead (row 1, before the view switch). Fed from the manifest as pages[].config.filterMenu. | |
filterMenuFields | Array<{key: string, label?: string, values?: string[], referenceType?: string}> | [] | Filter menu entries with no column behind them (manifest config.filterMenuFields): [{ key, label?, values?, referenceType? }]. Each lists its values, else the schema's enum or options, else the API's facet buckets, else a named source's facets(), each value named as the Active chip names it. referenceType: "nextcloud-user" names a user id by its display name (PqContracten "Eigenaar"). | |
columnMenu | boolean | false | Show a column menu (columns button) in the table header, above the row-actions column. Its menu lists every governed column as a toggleable checkbox — a compact, in-table alternative to the sidebar's Columns tab, so the sidebar space can be reclaimed. Fed from the manifest as pages[].config.columnMenu. | |
refreshing | boolean | false | Whether the refresh action is currently in progress | |
subscribe | boolean | true | Whether to auto-subscribe to live collection updates in self-fetch mode. Defaults to true. When register + schema are set (and no objects prop is passed), the page subscribes to the collection's or-collection-{register}-{schema} scope on mount and refetches (coalesced — events are hints) when an update event arrives; the subscription is released on unmount. Set false (manifest: config.subscribe: false) for static / read-once views. No-op in consumer-managed mode (an objects prop was passed) and on stores without live-updates support. | |
refreshDisabled | boolean | false | Whether the refresh action is disabled (e.g. when required selections are missing) | |
addDisabled | boolean | false | Whether the Add button is disabled (e.g. when required selections are missing) | |
showAdd | boolean | true | Whether to show the Add button in the actions bar | |
store | object | null | Store instance for automatic save integration. When provided alongside objectType, the form dialog saves directly to the store instead of emitting create/edit events. The object type must already be registered in the store via registerObjectType() before passing the store here. | |
objectType | string | '' | Object type slug for store integration (e.g. \$\{registerId}-\$\{schemaId}). Required when store is set — a console warning is emitted if missing. | |
sidebar | { enabled: boolean, show?: boolean, columnGroups?: Array, facets?: object, showMetadata?: boolean, search?: object }|null | null | Manifest-driven sidebar configuration. When set with enabled: true, CnIndexPage auto-mounts an embedded CnIndexSidebar wired to the page's schema, search, columns, and facet props. When unset or enabled: false, the legacy slot-based interface is preserved — consumers mount their own CnIndexSidebar at the App.vue level. Shape: - enabled (boolean) — existence gate. Whether the page configures an embedded sidebar at all. When false or unset, the auto-mount path is bypassed (no <CnIndexSidebar> rendered) and the consumer's slot pattern stays active. - show (boolean, default true) — visibility gate. Even when enabled: true, show: false SUPPRESSES rendering for this page so manifest authors can hide the sidebar declaratively without removing the config. Distinct from enabled so config can be retained (e.g. for a watcher / responsive layout) while the visible surface is hidden. - columnGroups (array) — extra column groups beyond schema + Metadata. - facets (object) — live facet data { fieldName: { values: [...] } }. - showMetadata (boolean) — include the built-in Metadata column group (defaults true). - search (object) — search-related label overrides forwarded to CnIndexSidebar. | |
searchValue | string | '' | Current search term (forwarded to the embedded sidebar when sidebar.enabled). | |
visibleColumns | array | null | Currently visible column keys (forwarded to the embedded sidebar). | |
activeFilters | object | \{\} | Currently active facet filters: { fieldName: [values] } (forwarded to the embedded sidebar). | |
register | string | '' | Effective register slug for the page. Forwarded as a prop to the resolved card component (when cardComponent is set) so bespoke card UIs can match the schema → register pair. Manifest-driven path: pages[].config.register flows in via CnPageRenderer's v-bind="resolvedProps" spread. | |
cardComponent | string | '' | Optional name of a consumer-provided card component (registered in the customComponents registry on CnAppRoot) to render in place of the default CnObjectCard when the page is in card-grid view mode. Resolution priority (highest first): 1. The parent's #card scoped slot (always wins). 2. The component resolved from cardComponent against the v2 registry (any kind carrying a component), then the legacy customComponents map. 3. The library default (CnObjectCard). Unknown names log console.warn once and fall back to the default so a misconfigured manifest never blanks the grid. | |
listComponent | string | '' | Name of a custom row component for list view, resolved against the v2 registry and then the legacy customComponents map (manifest pages[].config.listComponent). Same resolution priority as cardComponent: the #list-item slot wins, then this component, then the default CnObjectRow. Unknown names warn once and fall back to the default. | |
customComponents | union | null | Optional explicit customComponents registry. When set, this overrides the registry injected from CnAppRoot via cnCustomComponents. Provided primarily so unit tests can pass a registry without mounting CnAppRoot. Used by: - cardComponent resolution (REQ-MCI from manifest-card-index) - actions[].handler registry name resolution (REQ-MAD-3 from manifest-actions-dispatch — handler funcs called on row-action click) | |
headerActions | Array<{ id: string, label: string, icon?: string, handler?: string|(() => void), route?: string, href?: string, target?: ('_blank'|'_self'), disabled?: boolean }> | [] | Manifest-driven page-level actions rendered inside the NcActions overflow dropdown between Refresh and the #action-items slot. Each entry is { id, label, icon?, handler?, route?, disabled? }. The handler field mirrors the row-level actions[].handler pattern: a function, the keyword 'navigate', 'emit', 'none', or a string name looked up in the v2 registry (a kind: 'handler' entry) and then in the legacy customComponents. The page dispatches the resolved handler via onHeaderAction AND (unless the handler is the 'none' keyword) emits @header-action({ action: id, id }). An entry with href instead renders as a real link and is never dispatched or emitted: an absolute http(s), mailto:, tel: or //host/... URL is used as written, an instance path (leading /) goes through generateUrl(). target: '_blank' opens it in a new tab. Reserved ids (those used by built-ins on the bar — refresh, import, export, copy, delete) are dropped from the merged list with a console.warn. | |
bulkActions | Array<{ id: string, label: string, icon?: string, handler?: string|((scope: { actionId: string, selectedIds: Array<string>, count: number }) => void), target?: string, props?: object, disabled?: boolean }> | [] | Declarative bulk actions for the contextual selection strip. The strip has had a #selection-actions slot for a while, but a slot can only be filled by a hand-written host component — so a page declared in an app manifest could carry row actions and header actions and never a bulk one. This prop is the missing vocabulary. Handler resolution mirrors headerActions[], with one difference that is the whole point: the handler is called with the SELECTION. A bulk handler that has to go and find out what was selected is a bulk handler waiting to disagree with the strip that invoked it. Reserved ids (copy, delete) are dropped with a warning — the strip already ships those two as built-ins, and a second button with the same name doing something else is worse than no button. | |
activeOrganisation | union | null | Active organisation entity (multi-tenancy-context). When bound from a tenant-switcher higher in the tree, CnIndexPage watches it and calls store.setActiveTenantOrganisation(uuid) so the next fetchCollection() stamps the new tenant header and the in-memory caches are cleared. When the prop is unset the legacy single-tenant behaviour is preserved exactly. | |
documentationUrl | string | '' | When set, adds a Documentation entry to the Actions overflow (after Refresh). Opens the URL in a new tab. Empty hides it. | |
documentationLabel | string | '' | Label for the Documentation overflow entry. |
Events
| Name | Payload | Description |
|---|---|---|
configure | — | |
folder-create | — | |
action | — | A row action was chosen from a row's actions menu, its right-click menu or the keyboard primary action. Payload: action (the label), the row, the action's id when it has one, and builtin: true for a built-in View / Edit / Copy / Delete. Its handler has already run. |
add | — | |
apply-view | — | |
board-move | — | A card moved through the host's transition. |
board-column-field-change | — | The board's column switch picked another field. Payload: the field name. |
bulk-action | — | A declarative bulk action was triggered from the selection strip. Payload: { action, id, selectedIds, count }. The SELECTION travels with it, because an action that has to go and find out what was selected is one re-render away from acting on a different set than the user saw highlighted. |
clear-filters | — | |
columns-change | — | |
quick-edit-save | — | Emitted with the fields a quick edit wrote onto a row. |
content-search | — | Emitted when the "Also search inside files" switch changes, so a consumer-managed page can add _content_search to its own query. |
copy | — | |
create | — | Emitted after a create is confirmed (store, self-store, or createOverride). |
delete | — | |
edit-open | — | Emitted instead of opening the edit modal when editOpensDetail is set — the host navigates to the record's detail page, where the full record (not just its scalars) is editable. |
filter-change |