Skip to main content

CnTimelineWidget

An object's dated events in time order, on a detail page. Place it with the timeline widget type.

{
"type": "timeline",
"content": {
"title": "Timeline",
"fields": [
{ "field": "@self.created", "label": "Booking created" },
{ "field": "depositClearedAt", "label": "Deposit cleared" },
{ "field": "confirmationSentAt", "label": "Confirmation mail sent" },
{ "field": "startsAt", "label": "Starts" },
{ "field": "endsAt", "label": "Ends" }
],
"related": [
{ "schema": "payment", "field": "booking", "label": "Payment received", "titleField": "amount" }
],
"auditTrail": true
}
}

Sources​

All five are optional and end up in one list.

KeyWhat it adds
fieldsThe object's date properties, [{ field, label }]. A dotted path reaches metadata, such as @self.created. A field without a date adds nothing.
relatedRelated objects, [{ schema, field, register?, dateField?, label, titleField?, limit? }]. Rows of schema whose field holds this object's id, each dated by dateField (default @self.created). titleField becomes the line under the label.
auditTrailtrue adds the object's audit trail: "Updated by Ruben".
listsA list held on the object, [{ field, dateField, labelField?, valueLabels?, label?, detailField? }], such as a status history. Each entry with a date at dateField becomes one event, labelled by its labelField value (else label), with detailField as the line under it. valueLabels words a stored value ({ "confirmed": "Status: Confirmed" }), translated like every label; a value it does not name shows as stored.
timelinetrue adds OpenRegister's timeline of notes, calls and messages.

order: "desc" lists newest first; the default is oldest first. limit: 3 keeps the first three events of that order, for a short History side card. An audit-trail read is not a change, so it is not listed.

A history in words​

The audit trail takes the History card's words: actionLabels (by action), changeLabels ([{ field, to?, action?, label }], by the field an entry changed) and valueLabels, with the tokens {actor}, {state}, {changed.<key>} (the new value; {changed.<key>.old} the old one) and {object.<path>}. excludeActions and excludeActors leave entries out, as on the card. limit keeps the first few events after sorting. A related entry whose label holds {path} tokens names the row itself ("{name} is on the waiting list"), and its when (a local visibleWhen condition) keeps only the rows it holds for. Board PqEvenement:

{ "type": "timeline", "content": {
"auditTrail": true, "order": "desc", "limit": 4, "excludeActions": ["read"],
"actionLabels": { "create": "Event created" },
"changeLabels": [{ "field": "capacity", "label": "Places raised from {changed.capacity.old} to {changed.capacity.new}" }],
"related": [{ "schema": "eventRegistration", "field": "event", "label": "{name} is on the waiting list", "when": { "field": "status", "value": "waitlist" } }]
} }

resolve ({ "<field>": { "register"?, "schema", "labelField"? } }) names the record a reference points at: a label's {object.<field>} reads that record's label instead of its id, read once through the shared reference resolver ("Event created in campaign {object.campaign}" with "resolve": { "campaign": { "schema": "campaign" } }). The id stays until the label is known.

An actionLabels value may also be a list of { when?, text }: the first entry whose local visibleWhen condition holds for the record gives the words, and one without when is the fallback ("create": [{ "when": { "field": "campaign", "op": "notEmpty" }, "text": "Event created in campaign {object.campaign}" }, { "text": "Event created" }]). The History card (audit-trail) reads the same form.

Manage mode​

manage: true replaces the read view with a working view over OpenRegister's timeline alone (/objects/{register}/{schema}/{id}/timeline), newest first with pinned entries on top:

  • kind chips (All, then each kind present, with counts; a plain note has no kind), filtering without a second read;
  • a visibility filter, pin / unpin, and "Mark as answered" on an open follow-up;
  • a note composer with the seeded standard notes (/timeline/text-blocks); a picked block is sent as textBlock, so OpenRegister fills in the object's own values;
  • Export of the shown entries as CSV;
  • entryActions that open a modal from the app's registry on one entry.

The read says whether the reader may manage (canManage); every control that writes is drawn only then. A failed read is shown as an error, never as an empty history.

{
"type": "timeline",
"content": {
"manage": true,
"title": "History",
"exportName": "history",
"entryActions": [
{
"id": "reply",
"label": "Reply",
"kinds": ["portal-message-in"],
"modal": "ReplyDialog",
"props": { "open": true, "recordId": "@objectId", "subject": "@row.fields.subject" },
"doneEvent": "sent",
"closesFollowUp": true
}
]
}
}
KeyDefaultDescription
managefalsetrue renders the manage view.
title, subtitle"History", "What happened, who did it and when, newest first"Headings (translated through the app).
publicLabel"Visible to the requester"Label of the public badge, filter option and composer switch.
exportNamehistoryCSV file name prefix; the object id is appended.
composertruefalse hides the note composer. "only" draws the composer alone, to stack as a card of its own under the list (board DqZaakHistorie "Notitie toevoegen"); "separate" draws the list without a composer but keeps "Add note", which focuses that card. A note saved in the card reloads the list of the same object.
visibilityLabeltruefalse draws the visibility filter without its "Visibility" label (it stays the accessible name), so the select reads "Internal and public" on its own (board DqZaakHistorie).
readsToggle—true or a label adds a footer switch, off by default, that puts who read the record (the object's audit trail read events, as OpenRegister answers them to the reader) among the entries, without actions, with a "Viewed" chip; while off the count says "changes only". Offered only when OpenRegister answers readEventsVisible: true for the reader (the groups audit.readEventsVisibleTo names, and administrators); not an access control of its own (board DqZaakHistorie "Ook wie de zaak las").
auditTrailLinkunsettrue ("Full audit trail in the sidebar") or a label: a link beside the event count that opens the object sidebar on its audit trail tab. Drawn only when the page has an object sidebar.
auditTrailTabauditTrailThe sidebar tab the audit trail link opens, for a page that declares its audit trail tab under its own id.
textBlockstruefalse skips the standard notes.
entryActions[]{ id, label, kinds?, modal, props?, doneEvent?, closesFollowUp? }. modal names a registry entry; props resolve @objectId and @row.<path>. On doneEvent (default done) an open follow-up is closed when closesFollowUp is set, else the timeline is read again; close dismisses.

Props​

PropTypeDefaultDescription
objectObjectnullThe object whose events the widget shows.
titleString''Card title override.
contentObject{}Stored widget content: { title, fields, related, auditTrail, timeline, order }.
apiBaseString'/apps/openregister/api'OpenRegister API base the widget reads related objects, the audit trail and the timeline from.

Behaviour​

  • Labels are authored in English and pass through the app's translation.
  • A calendar date shows as a date, a moment as date and time, in the reader's language.
  • A moment after now shows a hollow dot and the word "Upcoming".
  • Each source loads on its own. When one fails, a warning names it and the rest still show.
  • With no dated facts the widget says "Nothing has happened yet."

The object comes from the detail page, as for audit-trail: explicit register, schema, objectId and object props win, then the page's object context, then content. When only the id is known, the widget fetches the object.

Items from an app endpoint, with type chips​

An app that merges its own sources answers them from one endpoint. endpointSource reads it a page at a time, and typeChips narrow it on the server:

{ "type": "timeline", "content": {
"order": "desc",
"endpointSource": {
"url": "/apps/pipelinq/api/timeline",
"params": { "entityType": "client", "entityId": "@objectId" },
"itemsPath": "items", "pagesPath": "pages",
"dateField": "date", "labelField": "title", "detailField": "description",
"typeField": "type", "userField": "user",
"typeLabels": { "interaction": "Contact moment", "task": "Task" },
"typesParam": "types[]", "limit": 20
},
"typeChips": [{ "value": "interaction", "label": "Contact moments" }, { "value": "task", "label": "Tasks" }]
} }

endpointSource.icons ({ path?, map?, typeMap?, default? }) gives each event an icon instead of the dot: the value at path through map (a contact moment's channel: { "phone": "Phone", "email": "Email" }), else its type through typeMap, else default. emptyText replaces "Nothing has happened yet." when there is nothing to show. Each item becomes an event: the label (an item without one reads "(no title)"), the detail cut at 120 characters, and a meta line of its type label and author. pageParam (default _page) and limitParam (default _limit) name the paging parameters; "Load more" reads the next page while the answer's pages is higher. A chip sends its value in typesParam and reads from page 1; All sends none. A failed read says that the activities could not load.

An activity card: feed rows and a note box​

layout: "feed" draws each event as one row: a round icon, a meta line of the moment, the kind and the author ("2 Oct, 09:30 · contact moment · Fatma Yildiz") and the text. A detail that says more than the text stands under it. composer puts a note box above the list; a note is written on the record (POST /objects/{register}/{schema}/{id}/notes) and the timeline reads again. The read view also reads again whenever cn:timeline:changed names its record.

{
"type": "timeline",
"title": "Activity",
"headerActions": [
{ "label": "Link email", "icon": "EmailOutline", "variant": "tonal", "action": { "type": "open-modal", "target": "EmailLinkDialog", "props": { "register": "pipelinq", "schema": "client", "objectId": "@objectId" } } },
{ "label": "Compose in Mail", "icon": "EmailArrowRightOutline", "variant": "tonal", "action": { "type": "navigate", "target": "/index.php/apps/mail/compose?uri=mailto:@object.email" } }
],
"content": {
"order": "desc",
"layout": "feed",
"composer": { "placeholder": "Add an internal note. Type @ to mention a colleague.", "label": "Add note", "submitLabel": "Add note" },
"endpointSource": { "url": "/apps/pipelinq/api/timeline", "params": { "entityType": "client", "entityId": "@objectId" } },
"typeChips": [{ "value": "interaction", "label": "Contact moments" }, { "value": "note", "label": "Notes" }]
}
}

A header action's navigate target fills @object.<field> inside the URL. CnEmailLinkDialog (register, schema, objectId) is the "Link an existing email" picker on its own; register it in the app's registry as a modal to open it from a button.