Skip to main content

CnActionsMenu

CnActionsMenu is the shared … overflow Actions menu that renders the canonical built-in action trio used across every Conduction surface:

  1. Refresh
  2. Documentation (only when a documentationUrl is supplied)
  3. 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 @refresh with { widgetId, title }. Unless a host listener calls event.preventDefault() on the second handler argument, it then emits on the @nextcloud/event-bus channel named by refreshChannel (cn:widget:refresh for widgets, cn:page:refresh for pages). The menu stays open while the refresh runs, with the item disabled and spinning, and closes once it settles. Refresh work reports itself through waitUntil(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 the refreshing prop 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 NcActionLink only when documentationUrl is 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 / cnFeatureRequestForge injects provided by CnAppRoot with an English headline (authored title, else the surface slug). Being a real link, it can be middle-clicked or copied. A click emits @request-feature with { widgetId, title }; a handler that calls preventDefault() on the second argument cancels the link. Without a resolvable repo the item is a button that emits the event and logs a one-line console.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​

SlotDescription
lead-itemsItems 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-itemsAdditional NcActionButton-family items appended inside the overflow menu, after the built-in Refresh / Documentation / Request-a-feature group.

Labels & state props​

PropDefaultDescription
documentationLabelt('Documentation')Pre-translated label for the Documentation item.
refreshLabelt('Refresh')Pre-translated label for the Refresh item.
requestFeatureLabelt('Request a feature')Pre-translated label for the Request-a-feature item.
actionsMenuLabelt('Actions')Pre-translated aria-label / tooltip for the overflow trigger.
trailingChevronfalseDraw 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.
hasPrimaryItemsfalseTells 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.
refreshingfalseWhile 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​

NameTypeRequiredDefaultDescription
showRefreshbooleantrueWhether 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.
showRequestFeaturebooleantrueWhether the Request-a-feature item renders.
documentationUrlstring''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.
docsAnchorstring''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.
showDocumentationbooleantrueWhether 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.
showReportBugbooleantrueWhether the "Report a bug" item renders.
reportBugUrlstring''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.
reportBugLabelstring() =&gt; t('nextcloud-vue', 'Report a bug')Pre-translated label for the Report-a-bug action.
documentationLabelstring() =&gt; t('nextcloud-vue', 'Documentation')Pre-translated label for the Documentation item. Defaults to the lib's translation of "Documentation".
widgetIdstring''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).
titlestring''Human-readable title carried on action payloads.
surfacestring''Stable surface slug naming where the menu sits (e.g. widget:&lt;id&gt;, detail:&lt;id&gt;, dashboard:&lt;id&gt;). Used as the English headline fallback for both new-issue deep-links when no authored title can be recovered.
specRefstring''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).
refreshingbooleanfalseWhether 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.
refreshChannelstring'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.
refreshLabelstring() =&gt; t('nextcloud-vue', 'Refresh')Pre-translated label for the Refresh action.
requestFeatureLabelstring() =&gt; t('nextcloud-vue', 'Request a feature')Pre-translated label for the Request-a-feature action.
trailingChevronbooleanfalseDraw 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.
placementstring'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).
actionsMenuLabelstring() =&gt; t('nextcloud-vue', 'Actions')Pre-translated aria-label / tooltip for the overflow trigger.
variantstring''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".
hasPrimaryItemsbooleanfalseTell 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.
testidBasestring'cn-actions-menu'Prefix for the data-testids emitted on the menu container and its items: &lt;base&gt;-actions (container), &lt;base&gt;-action-refresh, &lt;base&gt;-action-request-feature, &lt;base&gt;-action-report-bug, &lt;base&gt;-action-documentation. Lets each host keep its own stable testids.

Events​

NamePayloadDescription
refreshundefinedUser 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-featureundefinedUser 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​

NameBindingsDescription
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.

PropDefaultDescription
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.
showDocumentationtrueWhether the Documentation item renders. For the rare surface that must suppress it deliberately.
showReportBugtrueWhether 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.
reportBugLabelt('Report a bug')Pre-translated label for the Report-a-bug item.

The target is resolved in this order:

  1. the documentationUrl prop, if set (deep-linked with docsAnchor when both are given);
  2. the app-wide cnDocumentationBaseUrl provided by CnAppRoot, plus docsAnchor;
  3. 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.