Ga naar hoofdinhoud

CnObjectDataWidget

Schema-driven editable data grid widget. Displays object properties in a CSS grid, supports inline editing (click-to-edit with all widget types), dirty tracking, and saves via objectStore.

A plain-object value shows as a definition list, with one nested list for an object inside it (a per-language map such as { nl: { shortDescription, longDescription } } reads per language, with nested keys labelled by their sub-schema title or made readable: "Short description"). Structured values have no inline editor: a field with a json, code, file, sub-objects or child-records widget, or holding an object or a list of objects that is not a relation, edits through the Edit form unless a field-<key> slot supplies an editor.

Usage​

<CnObjectDataWidget
title="Character info"
:schema="schema"
:object-data="character"
object-type="characters" />

Props​

PropTypeDefaultDescription
titleString'Data'Widget title in the card header
show-titleBooleantrueDraw the header's title row. Set false in a tab panel, where the open tab already names the panel. The header still renders whenever the actions slot is filled, so the Save button an inline edit needs does not vanish with the title. Needed because title carries a DEFAULT of 'Data': a host that wanted no title passed undefined and got the default instead.
show-actionsBooleantrueDraw the overflow Actions menu in the header. Set false where the host already offers one within a few pixels, a tab panel being that case: the strip carries its own menu, so a second copy inside the panel bought a header band to hold it and nothing else. Switching it off costs nothing, because the two items it holds travel instead of vanishing. Metadata and the full-form Edit are published to the host surface and render in its menu, each still opening this widget's own dialog with this widget's overrides, include and exclude applied. That scoping is why they are published rather than left to the page: a detail page carries its own record Edit, but it opens the form the page configures, not the subset declared here. Inline editing never used the menu, because a cell opens its editor when clicked and Save and Discard arrive in the actions slot as soon as there is an edit to commit.
borderlessBooleanfalseDrop the card border and background, for a host that draws its own.
flushBooleanfalseDrop the content padding, for a host that supplies its own inset.
chromelessBooleanfalseDraw no card at all: what a tab panel wants, in one prop instead of three. Implies show-title="false", borderless and flush, and drops the header divider too. The Save button keeps its header. Forwarded to CnWidgetWrapper.
iconObject|FunctionnullOptional MDI icon component for the header
object-dataObjectnullThe object to display and edit. Keys must match the schema property keys. Optional — null while the object is still loading (internal reads are null-guarded).
schemaObjectnullJSON Schema defining properties. Must have a properties field. Optional — null renders the empty state (e.g. before the schema is fetched).
object-typeString''Registered object type slug in the objectStore. Required for saving via objectStore.saveObject().
storeObjectnullOptional objectStore instance. When provided, used directly for saving instead of auto-detecting via Pinia.
overridesObject{}Per-property configuration overrides (see below)
columnsNumber3Number of grid columns
collapsedFields (collapsed-fields)NumbernullNumber of fields shown while collapsed, with a "Show all N fields" button for the rest. null fits the cell: the whole rows that fit stay, and the button only appears when the cell overflows
footnoteString''A muted 13px line under the fields, through the host translate. A detail page data widget sets it as content.footnote (DqZaakContact "Ontvangstbevestiging").
editableBooleantrueWhether editing is enabled globally — gates both inline (click-to-edit) and the full-form Edit action item
edit-labelString'Edit'Label for the Edit action item, which opens a schema-driven CnFormDialog pre-filled with the object (alongside inline editing)
hide-emptyBooleanfalseHide fields that have no value instead of rendering them with an em dash. Read grid only — a field being edited, a field with an unsaved change, and the full Edit form stay visible.
excludeArray[]Property keys to hide from display
includeArraynullProperty keys to show (whitelist — all others hidden)
formSize (form-size)String'normal'NcDialog size for the full-form Edit dialog ('small', 'normal', 'large'). The widget already scopes that form with include / exclude, but a scoped form can still be long enough to want the room.
formColumns (form-columns)Number1How many columns the Edit form flows its fields into (1 or 2). Pair 2 with formSize: 'large', or the two columns are merely two narrow ones. Collapses back to one column below 700px.
save-labelString'Save'Label for the save button
discard-labelString'Discard'Label for the discard button
empty-labelString'No data available'Label when no properties are found
documentation-urlString''Documentation link surfaced in the widget's overflow Actions menu (empty hides the Documentation item).
widget-idString''Stable id forwarded to the widget chrome (falls back to object-type).
metadata-labelString'Metadata'Label for the Metadata item in the overflow Actions menu.
fixedColumnsBooleanfalseKeep columns under the board look too, instead of fitting 200px columns (manifest content.fixedColumns).

Slots​

SlotScoped propsDescription
#actions—Extra buttons in the widget header (right side, next to save/discard)
#field-{key}{ field, value, update, cancel }Override the inline editor for a specific property
#display-{key}{ field, value, raw }Override the display (read-only) view for a specific property

Events​

EventPayloadDescription
@savedresult objectEmitted after a successful objectStore save
@save-errorerror messageEmitted when the objectStore save fails
@savemerged data objectEmitted when no objectType is set — lets the parent handle the save
@discard—Emitted when the user clicks the discard button

One config, two surfaces (display + edit modal)​

The overrides / exclude / include props drive a single fieldsFromSchema pipeline that both the inline display and the full-form Edit modal (CnFormDialog) consume. So a property hidden via overrides.id.hidden = true is hidden in the widget grid and dropped from the edit form; an order set on a property reorders both. gridColumn/gridRow (span) are display-only; the modal is single-column (stacked).

fieldsFromSchema honors, per property: hidden (drop the field), order (wins over the schema's own order for sorting), readOnly: false (un-skip a schema-readonly field), plus any field props to merge (label, widget, enum, …).

Discriminated supertypes (hide-empty)​

exclude / include / overrides.hidden are static — they hide the same keys for every object. That is the wrong tool for a schema whose properties are only relevant to some of its objects.

The canonical case is a supertype with a discriminator: one ticket schema holding request | complaint | contactmoment, where a complaint never carries the telephony fields (ctiExtension, recordingUrl, dispositionNotes, …) a contactmoment does. Rendering the union statically means every complaint shows a wall of em dashes.

Set hide-empty and the grid shows only what the object actually has, so the page becomes type-aware without the schema (or the manifest) having to enumerate which fields belong to which variant:

<CnObjectDataWidget
:object-data="ticket"
:schema="ticketSchema"
hide-empty />

It is display-only and non-destructive: the field currently being edited, any field with an unsaved change, and the full Edit form all stay visible — so an empty field is always still reachable to fill in. false and 0 count as values, not absences, and are never hidden.

Configuring it in-app​

On a detail page in Buildiq edit mode, the widget's cog opens CnObjectDataWidgetForm: it lists the schema's properties (resolved from the widget's register/schema, or the page's injected cnObjectContext when the widget inherits them) and lets you, per property, toggle visibility, set a label, span, editor type and editable, drag to reorder, and pick a layout preset (Stacked / 2-col / 3-col → the columns value). The form emits a minimal overrides map persisted on the widget's content.overrides.

Property overrides​

The overrides prop accepts per-property configuration:

{
propertyKey: {
order: 1, // Sort order (lower = first)
gridColumn: 2, // Number of grid columns to span
gridRow: 2, // Number of grid rows to span
hidden: false, // Whether to hide this property
editable: true, // Whether this property can be edited
label: 'Custom', // Override the display label
widget: 'textarea', // Override the widget type for editing
enum: [...], // Override enum values for select/multiselect
formatter: 'timeBlocks', // Display through a formatter registered on CnAppRoot
}
}

formatter names a function in CnAppRoot's formatter registry (the library's built-ins plus the app's formatters prop), the same id a table column's formatter uses. It is called as (value, object, property), and its result is the text the cell shows, so a structured value an app already formats in its list reads the same on the detail page. An id nobody registered, or a formatter that throws, keeps the default rendering. It changes the display only: inline editing still edits and writes the stored value. In a manifest the override sits on the data widget's content.overrides.

Supported widget types​

The widget auto-detects the editor based on the JSON Schema property type:

WidgetSchema typeEditor
textstringText input
emailstring format emailEmail input
urlstring format uriURL input
numbernumber/integerNumber input
textareastring (long)Textarea
selectstring with enumSingle select dropdown
multiselectarray with enumMulti-select dropdown
tagsarray (no enum)Tag input
checkboxbooleanToggle switch
datestring format dateDate picker
datetimestring format date-timeDatetime picker
groupstring with referenceType: "nextcloud-group" (or format: "nc-group")Searchable list of Nextcloud groups
group-multiselectarray whose items is a groupSearchable list of groups, several at once
userstring with referenceType: "nextcloud-user" (or format: "user")Searchable list of Nextcloud users
user-multiselectarray whose items is a userSearchable list of users, several at once

A group or user field is picked by display name and stores the group id or uid, with the same search the create and edit dialogs use. When not editing, a group field shows the group's display name (cached per id, the id while it loads or when it cannot be found).

Example with overrides​

<CnObjectDataWidget
title="Publication details"
:schema="publicationSchema"
:object-data="publication"
object-type="publications"
:overrides="{
title: { order: 1, gridColumn: 2 },
description: { order: 2, gridColumn: 2, widget: 'textarea' },
status: { order: 3, editable: false },
internalNotes: { hidden: true },
}" />

Conditional immutability (x-openregister-readonly-when)​

A schema property can declare that it becomes read-only when another field on the same object holds a given value — the widget evaluates the rule against the live object data and renders the field locked (shown, not hidden). This is the declarative way to express identity fields that must not be edited in a particular state (e.g. a hybrid app's slug/name/description/ productionVersion, which mirror the installed app it customizes).

// In the OpenRegister schema property:
"slug": {
"type": "string",
"x-openregister-readonly-when": { "field": "appType", "equals": "hybrid" }
}
// or match a set of values:
"slug": { "type": "string", "x-openregister-readonly-when": { "field": "appType", "in": ["hybrid", "managed"] } }

An unconditional "readOnly": true on the property locks the field in every state (still shown, never editable). Both are honoured by isEditable; a per-field overrides[key].editable still takes priority. Read-only here is a UI affordance — pair it with server-side enforcement (an OpenRegister write guard / listener) for the authoritative boundary.

Reference (relation) display​

Relation properties display the referenced object's name, never its raw uuid (ADR-062). Two property shapes are recognised:

  • x-openregister-relation: { target: "<register>/<schema>" } (explicit, works on every surface), and
  • the canonical OpenRegister shorthand "$ref": "<schemaSlug>" on a uuid-string property or its array items — the slug resolves against the same register, taken from the detail-page object context (cnObjectContext inject). On surfaces without that context the shorthand falls back to the shortened-id display.

Names resolve via one GET /api/objects/{register}/{schema}/{id} per distinct id (cached per widget instance): name → title → displayName → firstName lastName → @self.name → the id itself.

Scoping picker options: x-relation-filter​

A relation property may declare x-relation-filter to narrow its edit-picker options to objects that fit the CURRENT object:

"status": {
"type": "string", "format": "uuid", "$ref": "statusType",
"x-relation-filter": { "caseType": "@object.caseType" }
}

Filter values are token-resolved (@objectId / @object.<field>), with the widget's dirty values winning — picking a new caseType immediately scopes the status options to it, before any save. Entries whose token stays unresolved are dropped (an unfiltered picker beats an empty one). Options reload on every edit start for the same reason.

A key inside an object​

An overrides key or an include entry can be a dotted path such as handling.teams: the widget shows and edits that key inside the handling object, and saves handling with its other keys kept. See CnFormDialog.

A value as a pill​

A field override pill: { variantMap } draws the shown value as a status pill, toned by the raw value:

{ "status": { "enumLabels": { "settled": "Settled" }, "pill": { "variantMap": { "settled": "success", "parked": "warning" } } } }

Values as inputs, with a hint (fieldLook: "input", overrides[key].hint)​

fieldLook: "input" draws each value as a 40px input box under its label, as board PqOfferte draws the quote's facts; a click still edits the field in place and saves it. overrides[key].hint adds a muted line under a value, translated ("Staat op de pdf", "Wordt gezet bij verzenden"), in either look.