Ga naar hoofdinhoud

CnRelatedObjectsWidget

Everything linked to an object, in one widget. It has two rendering modes that share the CnWidgetWrapper chrome.

Tabbed self-fetch mode (default)​

With layout="tabs" (the default), the widget resolves the object's register / schema / id — from the register / schema props, falling back to object-data['@self'] — and fetches its relations directly from OpenRegister, with no object-store wiring required:

  • /relations — the aggregated leaf groups: Mails, Meetings, Contacts, Notes, Tasks, Deck.
  • /uses + /used — merged (and deduped) into a single Objects group; /contracts is folded in only when show-contracts is set.
  • /files — the Files group.

It renders one tab per non-empty group, each with a count badge equal to the group's total, and shows that group's items inline. An item with an owning Nextcloud app renders as a real link (new tab, so middle-click and copy-link work): files open via the canonical /f/{fileid} permalink (Files + Viewer), records carrying a url/link/accessUrl open that, and known leaf types (contacts, deck) build their app route; related objects emit @select-object for the host to route to their detail page. When no link can be resolved, @select-related is emitted so the host can route it. When every group is empty, no tab renders and the empty state shows.

Each section shows as soon as its own request returns: a fast /relations does not wait for slow /uses and /used calls. Tabs keep their fixed order as sections arrive, and the tab the reader saw first stays open. While another section is still loading, a line names it ("Still loading: Objects"). A section whose request failed is named with Could not load {section}. and the other sections stay visible.

Earlier builds offered an "open in sidebar" action per tab. That was removed — it only worked when the host mounted CnObjectSidebar, and silently did nothing otherwise. Deep-linking to the owning app works regardless of host wiring. (open-in-sidebar-label is kept as a deprecated no-op prop.)

Sections grouped by relation type​

layout="sections" with group-by-relation draws a case's related cases as board DqZaakGerelateerd does: one heading per relation type ("Onderwerp van deze zaak", "Wacht op"), each over its rows, and a host section such as "Gepland vervolg" with its heading action ("Vervolg plannen").

{ "id": "related", "type": "related", "content": {
"layout": "sections",
"groupByRelation": true,
"groupActions": { "relation:Waits on": { "label": "Link case", "icon": "LinkVariant", "type": "open-modal", "target": "LinkCase" } }
} }

Sections read from an app endpoint​

Some related content is not an OpenRegister relation: a follow-up that is scheduled but does not exist yet, or a typed link an app keeps itself. extraSources reads it and adds the sections beside the widget's own:

{
"type": "related",
"content": {
"showObjects": false,
"extraSources": [
{
"key": "planned",
"label": "Planned items",
"icon": "CalendarClock",
"endpoint": "/apps/myapp/api/item/@objectId/planned",
"path": "results",
"itemLabel": "{title}, next on {date}",
"static": true,
"rowActions": [{ "label": "Stop series", "endpoint": "/apps/myapp/api/item/@objectId/planned/{id}/stop", "when": { "field": "recurrence", "op": "neq", "value": "none" } }],
"children": { "path": "occurrences", "label": "{title}", "route": { "name": "ItemDetail", "params": { "id": "{id}" } } }
},
{
"key": "relations",
"endpoint": "/apps/myapp/api/items/@objectId/relations",
"path": "results",
"groupBy": ["{displayLabel}", "{kind}"],
"groupLabels": { "follow-up": "Follow-up" },
"itemLabel": ["{title} ({notes})", "{title}"],
"requireLabel": true,
"rowRoute": { "name": "ItemDetail", "params": { "id": "{itemId}" } }
}
],
"referenceSections": [{ "key": "parent", "label": "Parent item", "field": "parentItem", "register": "myapp", "schema": "item", "route": { "name": "ItemDetail", "params": { "id": "{id}" } } }],
"footerActions": [{ "label": "Plan follow-up", "icon": "CalendarClock", "type": "open-modal", "target": "PlanFollowUpDialog", "props": { "itemId": "@objectId" } }]
}
}

A template in a list is candidates: the first that fills. { "parts": [...], "separator": ", " } fills each part on its own and leaves the empty ones out ("{title}, every year, next on 1 Mar, 2 opened so far"). valueLabels maps a field's stored values to the words a template shows ({ "recurrence": { "yearly": "Every year", "none": "" } }). static rows open nothing. A row action calls its endpoint (POST unless method says otherwise), with @objectId and the row's {field} tokens filled in, and reads the sources again; a refusal shows the server's sentence as an alert. A source that cannot be read is logged and left out, and the related content around it stays.

Legacy list mode (deprecated)​

With layout="list" — or when no register/schema can be resolved — the widget falls back to the original flat sections driven by the object store's fetchUses / fetchUsed / fetchContracts / fetchFiles actions, plus the static leaf-integration Linked apps list. This path logs a one-time deprecation warning. Prefer the tabbed mode.

It is a Widget (not a Card): it carries the standard overflow Actions menu (Refresh / Documentation / Request a feature); Refresh refetches every group. The detail-page auto-body renders this widget beneath CnObjectDataWidget automatically (manifest type: "detail" pages), and it is registered as the related built-in widget key for manifest grids.

Usage​

<!-- Tabbed self-fetch (default): just pass the loaded object -->
<CnRelatedObjectsWidget
:object-data="lead"
@select-object="openObject"
@select-file="openFile"
@select-related="openLeafItem"
@open-integration="openSidebarTab" />

<!-- Or pass register/schema/id explicitly to override @self -->
<CnRelatedObjectsWidget
register="crm"
schema="lead"
:object-id="lead.id"
:show-contracts="true" />

In the deprecated list mode, relation and file sections only render when the store exposes the matching actions (relationsPlugin / filesPlugin). Collections the store can't resolve generically can be passed in via extra-sections.

Props​

PropTypeDefaultDescription
titleString'Related'Widget title shown in the header
bareBooleanfalseDrop the card chrome: no header, no border. For a surface that already supplies both, such as a CnTabsWidget panel. The Actions menu lives in the header, so a bare widget has none and the surface hoists it.
object-typeString''Registered object type slug (used for legacy store fetches)
object-idString|Number''The object's id
object-dataObject{}The object data — used to derive id/register/schema (from @self) when not passed explicitly
registerString''OpenRegister register slug. When omitted, derived from object-data['@self'].register. Required (with schema) for the tabbed self-fetch path
schemaString''OpenRegister schema slug. When omitted, derived from object-data['@self'].schema. Required (with register) for the tabbed self-fetch path
layoutString'tabs'Render mode: 'tabs' (self-fetch, tab per non-empty group), 'sections' (self-fetch, every group under its own heading in one list) or 'list' (deprecated store-action list)
groupByRelationBooleanfalseSplit the Objects group into one group per relation type, labelled with the label OpenRegister answers for the direction (relation.displayLabel on each uses/used row), through the app's translate; a row without one stays in Objects
groupActionsObject{}An action on a group's heading in the sections layout, keyed by group key (objects, files, an extra section's key, or relation:<label>): { label, icon?, ...action }. An extra-sections entry may carry its own action. Pressing it dispatches the action and emits group-action
storeObjectnullObject store instance (legacy list path only). When omitted, the widget tries Pinia auto-detection.
show-objectsBooleantrueShow the related-objects (uses/used/contracts) section
show-filesBooleantrueShow the files section
show-contractsBooleanfalseInclude /contracts relations in the Objects group (opt-in).
show-integrationsBooleantrueShow the leaf-integration entry-point section
hide-single-tab-titleBooleantrueSuppress the tab strip when only one group is visible. A lone tab repeats the widget title verbatim (a "Files" card carrying a "Files" tab), so hide it and let the card header stand alone.
show-total-countBooleanfalseRender a count pill beside the widget title totalling every visible group. Keeps the count reachable once hide-single-tab-title has taken the sole tab — and its pill — away.
include-groupsArray[]Whitelist of relation-group keys to display (tabbed path). When non-empty, ONLY these render (e.g. ['objects', 'files', 'mails']); empty shows every non-empty group. Lets a detail page carry several Related widgets scoped to different relations. Keys: objects, files, and the leaf groups (mails, events, contacts, notes, tasks, deck, talk, forms, maps, polls, …). Configurable in-app via the widget's cog.
exclude-integrationsArray[]Integration ids to omit from "Linked apps" (on top of the always-omitted core tabs)
extra-sectionsArray[]Extra related sections the store can't resolve generically. Each: { key, label, icon?, items: [] }
extra-sourcesArray[]Extra sections the widget reads itself from app endpoints (extraSources). See "Sections read from an app endpoint" below
reference-sectionsArray[]Sections naming the record a field points at (referenceSections): [{ key, label, icon?, field, register, schema, labelField?, route? }]. Shown only with a readable title, never as a bare id
footer-actionsArray[]Buttons under the widget (footerActions): [{ label, icon?, type, ... }], page actions dispatched with @objectId and @object.<field> resolved
documentation-urlString''Documentation link for the overflow Actions menu
widget-idString''Stable id forwarded to the widget chrome (falls back to object-type)
objects-labelString'Objects'Section heading for related objects
files-labelString'Files'Section heading for files
linked-apps-labelString'Linked apps'Section heading for leaf-integration entry points (legacy list path)
open-in-sidebar-labelString'Open in sidebar'Deprecated, no-op. The per-tab open-in-sidebar affordance was removed in favour of deep-linking; kept for backward compatibility. No longer rendered in tabbed mode
empty-labelString'Nothing related yet'Empty-state label. When left at its default a contextual label is derived instead: a widget scoped to a single group (include-groups: ['files']) shows "No files yet", an unscoped/multi-source one shows "No relations yet". The state renders as an NcEmptyContent with the group's icon (generic link icon when unscoped)
show-add-footerBooleantrueRender the "Add" footer on the tabbed self-fetch path: upload file (built-in, posts to the object's filesMultipart endpoint), add note (built-in, posts to the object's notes endpoint), and one emit-add entry per other configured group. Disable for read-only hosts

Events​

EventPayloadDescription
@select-objectrelated object recordAn Objects row was clicked
@select-filefile recordA Files row was clicked
@select-related{ group, item }A leaf-group row (mails, events, contacts, …) was clicked in tabbed mode and no owning-app deep link could be resolved
@select-extra{ section, item }A row in a host-supplied extra-sections group was clicked (legacy list path)
@open-integrationintegration id (string)A "Linked apps" row or a tab's "open in sidebar" affordance was activated — the host opens that leaf (the detail-page auto-body deep-links the sidebar tab)
@addgroup key (string)An Add-footer entry without a built-in flow was activated (e.g. objects, mails); the host routes it (open a link-object dialog, compose a mail, …)
@file-uploadedFile[]Files were uploaded to the object via the Add footer's built-in upload flow
@note-addednote message (string)A note was created on the object via the Add footer's built-in note flow
@group-action{ group, action }A group's heading action was pressed in the sections layout

A side card that the boards draw as a few links (PqKassabon "Gerelateerd") uses layout: "links". The host's sections (extraSources, referenceSections, extraSections) show as plain links, one per line, the label and the meta joined by a comma. Without host sections the related objects are listed. "Show all" opens the tabbed view, so files and every other relation stay one click away.

{
"type": "related",
"title": "Gerelateerd",
"content": {
"layout": "links",
"referenceSections": [
{ "key": "shift", "label": "Shift", "field": "shift", "register": "pipelinq", "schema": "cashShift",
"labelTemplate": "Shift {floatAt|date}, {drawer}", "route": { "name": "CashShiftDetail", "params": { "id": "{id}" } } }
],
"extraSources": [
{ "key": "refunds", "endpoint": "/apps/openregister/api/objects/pipelinq/posRefund?originalTransaction=@objectId",
"path": "results", "itemLabel": "Refund {reference}", "itemMeta": "{status}",
"rowRoute": { "name": "PosRefundDetail", "params": { "id": "{id}" } } }
]
}
}

sectionOrder (keys) orders the host's sections: ["shift", "refunds", "audit"] puts the referenced shift before the lists. Keys it leaves out follow in their declared order.