CnActionsMenu
CnActionsMenu is the shared … overflow Actions menu that renders the canonical built-in action trio used across every Conduction surface:
- Refresh
- Documentation (only when a
documentationUrlis supplied) - Request a feature
Request a feature deep-links the forge's feature-request issue form directly, exactly like Report a bug. It's used internally by CnWidgetWrapper (per-widget menu) and by the page-level headers of CnDetailPage and CnDashboardPage, so widgets and pages stay in lockstep. CnActionsBar (list pages) mirrors the same items inline.
Most apps never instantiate CnActionsMenu directly — they configure it through the host component's props (documentation-url, show-refresh, show-request-feature, …). Reach for it directly only when building a new surface that needs the same trio.
Behaviour
-
Refresh — emits
@refreshwith{ widgetId, title }. Unless a host listener callsevent.preventDefault()on the second handler argument, it then emits on the@nextcloud/event-buschannel named byrefreshChannel(cn:widget:refreshfor widgets,cn:page:refreshfor pages). The menu stays open while the refresh runs, with the item disabled and spinning, and closes once it settles. Refresh work reports itself throughwaitUntil(promise), which is on both the handler's event argument and the bus payload: the spinner lasts until every promise handed to it has settled (at least 400 ms, at most 15 s, so a hung request cannot lock the item) and therefreshingprop is false. A bus subscriber that refetches should pass its fetch in:subscribe('cn:page:refresh', (payload) => {
const done = this.fetchData()
payload?.waitUntil?.(done)
}) -
Documentation — rendered as an
NcActionLinkonly whendocumentationUrlis non-empty. Opens the link in a new tab (target="_blank"+rel="noopener noreferrer"); there is no JS handler. -
Request a feature — a link to the forge's feature-request issue form, opening in a new tab, built from the
cnFeatureRequestRepo/cnFeatureRequestForgeinjects provided byCnAppRootwith an English headline (authored title, else the surface slug). Being a real link, it can be middle-clicked or copied. A click emits@request-featurewith{ widgetId, title }; a handler that callspreventDefault()on the second argument cancels the link. Without a resolvable repo the item is a button that emits the event and logs a one-lineconsole.warn.
The overflow trigger hides itself entirely when no built-in item is visible and no #action-items slot content is supplied.
The data-testids are derived from testidBase: <base>-actions (container), <base>-action-refresh, <base>-action-documentation, <base>-action-request-feature. Each host passes its own base (e.g. cn-widget-wrapper, cn-detail-page).
Usage
<CnActionsMenu
:widget-id="resolvedId"
:title="title"
:surface="`detail:${resolvedId}`"
:documentation-url="documentationUrl"
refresh-channel="cn:page:refresh"
testid-base="cn-detail-page"
@refresh="onRefresh"
@request-feature="onRequestFeature">
<template #action-items>
<NcActionButton @click="…">Custom action</NcActionButton>
</template>
</CnActionsMenu>
Slots
| Slot | Description |
|---|---|
lead-items | Items at the very top of the menu, above Refresh. CnTabsWidget lists a board strip's overflow tabs here. The caller owns any separator after them. |
action-items | Additional NcActionButton-family items appended inside the overflow menu, after the built-in Refresh / Documentation / Request-a-feature group. |
Labels & state props
| Prop | Default | Description |
|---|---|---|
documentationLabel | t('Documentation') | Pre-translated label for the Documentation item. |
refreshLabel | t('Refresh') | Pre-translated label for the Refresh item. |
requestFeatureLabel | t('Request a feature') | Pre-translated label for the Request-a-feature item. |
actionsMenuLabel | t('Actions') | Pre-translated aria-label / tooltip for the overflow trigger. |
trailingChevron | false | Draw a 14px chevron after the label instead of the dots before it, as the board's "Meer" menu in a detail header. CnDetailPage sets it in the board look. |
placement | 'bottom' | Where the menu opens against its trigger. CnDetailPage passes bottom-end in the board look, so "Meer" lines up with its trigger's right edge. |
hasPrimaryItems | false | Tells the menu that #primary-items has content. Only needed by a host that switches every built-in item off: the menu decides in a computed whether to render at all, and a slot that fills in after mount is not something a computed notices. |
refreshing | false | While true, the Refresh item is disabled and shows a loading spinner — for exactly as long as this stays true, so it reflects the real refresh time. |
specRef | '' | Accepted for backward compatibility with the removed in-product suggestion modal; no longer forwarded. |
Reference (auto-generated)
The table below is generated from the SFC source via vue-docgen-cli and updates automatically whenever the component changes.
OpenRegister reliance
light: this component touches OpenRegister lightly. 1 direct reference, 0 files reached through imports.
See the reliance overview for the filterable list.
Props
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
showRefresh | boolean | true | Whether the Refresh item renders. The parent surface is responsible for any opt-out aliasing (e.g. CnWidgetWrapper's hideRefresh) and passes the resolved boolean here. | |
showRequestFeature | boolean | true | Whether the Request-a-feature item renders. | |
documentationUrl | string | '' | Explicit documentation link target, opened in a new tab. Wins over the cnDocumentationBaseUrl + docsAnchor pair. Leave empty (the default) to let the menu build the per-widget deep-link itself. | |
docsAnchor | string | '' | This surface's own section in the app's documentation, appended to the app-wide cnDocumentationBaseUrl. A bare slug (open-cases) becomes a #fragment; a value starting with / is resolved as a path; a full scheme:// URL is used as written. Supplying it is what makes the Documentation item land on THIS widget's section rather than the docs homepage. | |
showDocumentation | boolean | true | Whether the Documentation item renders. Defaults to true — the canonical trio is meant to be present on every surface; set false only where a docs link genuinely cannot exist. | |
showReportBug | boolean | true | Whether the "Report a bug" item renders. | |
reportBugUrl | string | '' | Explicit "Report a bug" target. Empty (the default) builds a new-issue deep-link on the app's forge from the injected cnFeatureRequestRepo + cnFeatureRequestForge, pre-filled with the surface's title. | |
reportBugLabel | string | () => t('nextcloud-vue', 'Report a bug') | Pre-translated label for the Report-a-bug action. | |
documentationLabel | string | () => t('nextcloud-vue', 'Documentation') | Pre-translated label for the Documentation item. Defaults to the lib's translation of "Documentation". | |
widgetId | string | '' | Stable id forwarded on the @refresh / @request-feature payloads (as widgetId) and on the cn:widget:refresh event-bus payload. The parent resolves it (explicit id or slugified title). | |
title | string | '' | Human-readable title carried on action payloads. | |
surface | string | '' | Stable surface slug naming where the menu sits (e.g. widget:<id>, detail:<id>, dashboard:<id>). Used as the English headline fallback for both new-issue deep-links when no authored title can be recovered. | |
specRef | string | '' | Optional specRef slug. Accepted for backward compatibility with hosts that bound it for the removed in-product suggestion modal; no longer forwarded anywhere (the forge issue form asks for its own context). | |
refreshing | boolean | false | Whether a refresh is currently in flight. While true, the Refresh item is disabled and shows a loading spinner for exactly as long as this stays true — so the spinner reflects the real refresh time. | |
refreshChannel | string | 'cn:widget:refresh' | Event-bus channel the default Refresh handler emits on when no host listener suppresses it. Widgets use cn:widget:refresh; page surfaces pass cn:page:refresh. | |
refreshLabel | string | () => t('nextcloud-vue', 'Refresh') | Pre-translated label for the Refresh action. | |
requestFeatureLabel | string | () => t('nextcloud-vue', 'Request a feature') | Pre-translated label for the Request-a-feature action. | |
trailingChevron | boolean | false | Draw a 14px chevron after the label instead of the dots before it: the board's "Meer" menu in a detail header (DqZaak). The board look puts the icon after the label; the Nextcloud look keeps it first. | |
placement | string | 'bottom' | Where the menu opens against its trigger: NcActions' bottom (centred under it), or bottom-end, the board's "Meer" menu, whose right edge lines up with the trigger's (DqZaakMeer). | |
actionsMenuLabel | string | () => t('nextcloud-vue', 'Actions') | Pre-translated aria-label / tooltip for the overflow trigger. | |
variant | string | '' | How the trigger button is drawn: tertiary (NcActions' own default, used when empty), secondary for a header that wants a bordered button, as the board look's "More". | |
hasPrimaryItems | boolean | false | Tell the menu that #primary-items has content. Only needed by a host that switches every built-in item off: the menu decides whether to render at all in a computed, and a slot that fills in later (a page's actions arrive after mount) is not something a computed notices. With any built-in item showing, the menu renders anyway and this changes nothing. | |
testidBase | string | 'cn-actions-menu' | Prefix for the data-testids emitted on the menu container and its items: <base>-actions (container), <base>-action-refresh, <base>-action-request-feature, <base>-action-report-bug, <base>-action-documentation. Lets each host keep its own stable testids. |
Events
| Name | Payload | Description |
|---|---|---|
refresh | undefined | User clicked the Refresh item. Payload: { widgetId, title }. Handlers may call the second arg's preventDefault() to suppress the built-in default (event-bus emit on refreshChannel), and its waitUntil(promise) to keep the item spinning until that work settles. |
request-feature | undefined | User clicked the Request a feature item. Payload: { widgetId, title }. Handlers may call the second arg's preventDefault() to suppress the built-in default (opening the forge's feature-request issue form). |
Slots
| Name | Bindings | Description |
|---|---|---|
lead-items | — | lead-items Items rendered at the very top of the menu, above Refresh: the tabs a board strip lists here instead of drawing them (CnTabsWidget). The caller owns any separator after them. |
primary-items | — | primary-items The surface's OWN actions — a page's |
action-items | — | action-items Additional NcActionButton-family items |
The mandatory trio
Request a feature, Report a bug and Documentation render on every surface. None of them is conditional on a URL being configured: the menu resolves each target itself, so a host that passes nothing still gets all three. That is the point — the items used to be per-host markup, and OpenRegister's widget menus shipped without the Documentation entry while OpenCatalogi's were inconsistent.
| Prop | Default | Description |
|---|---|---|
docsAnchor | '' | This surface's own section in the app's documentation, appended to the app-wide base. A bare slug (open-cases) becomes a #fragment; a value starting with / is resolved as a path; a full scheme:// URL is used as written. Supplying it per widget is what makes the docs link land on that widget's section instead of the docs homepage. |
showDocumentation | true | Whether the Documentation item renders. For the rare surface that must suppress it deliberately. |
showReportBug | true | Whether the Report-a-bug item renders. |
reportBugUrl | '' | Explicit bug-report target. Empty builds a new-issue deep-link on the app's own forge from the injected cnFeatureRequestRepo / cnFeatureRequestForge, pre-filled with the surface's title. |
reportBugLabel | t('Report a bug') | Pre-translated label for the Report-a-bug item. |
Where the documentation link points
The target is resolved in this order:
- the
documentationUrlprop, if set (deep-linked withdocsAnchorwhen both are given); - the app-wide
cnDocumentationBaseUrlprovided byCnAppRoot, plusdocsAnchor; - the app's conventional docs site derived from
cnAppId— a last resort so the item is never simply missing.
An app that hosts its docs anywhere else should provide cnDocumentationBaseUrl rather than pass a URL per widget.
Trigger variant
variant (String, default ''): how the trigger button is drawn. Empty keeps the NcActions default (tertiary); secondary draws a bordered button, as the board look's "More" in the detail header.