Skip to content

Commit 8bb94f1

Browse files
bszymanbszyman
committed
Document "Menu Items" extension type for Umbraco: added new section in "Extension Types" with examples for manifest and TypeScript approaches, detailed usage, and custom implementations. Updated summary to include the new section.
1 parent a43d1ad commit 8bb94f1

File tree

6 files changed

+730
-0
lines changed

6 files changed

+730
-0
lines changed

‎16/umbraco-cms/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,7 @@
171171
* [Kinds](customizing/extending-overview/extension-types/kind.md)
172172
* [Localization](customizing/extending-overview/extension-types/localization.md)
173173
* [Menu](customizing/extending-overview/extension-types/menu.md)
174+
* [Menu Item](customizing/extending-overview/extension-types/menu-item.md)
174175
* [Modals](customizing/extending-overview/extension-types/modals/README.md)
175176
* [Confirm Dialog](customizing/extending-overview/extension-types/modals/confirm-dialog.md)
176177
* [Custom Modals](customizing/extending-overview/extension-types/modals/custom-modals.md)

‎16/umbraco-cms/customizing/extending-overview/extension-types/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,10 @@ The `localization` extension type is used to register additional languages and f
7373

7474
The `menu` extension type is used to create custom menus. These can be placed in sidebar extensions or displayed as a fly-out from a button, header, or workspace view.
7575

76+
### [Menu Items](menu-item.md)
77+
78+
The `menuItem` extension type is used to create custom menu items. These can be used in conjunction with custom menu extensions or placed in any of the existing/default Umbraco menus.
79+
7680
### [Modals](modals/README.md)
7781

7882
The `modal` extension type is used to configure and present dialogs and sidebars within the Umbraco backoffice.

‎16/umbraco-cms/customizing/extending-overview/extension-types/menu-item.md‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
---
2+
description: >-
3+
Create menu items that appear throughout the backoffice, in sidebars, button flyouts, and more.
4+
---
5+
6+
# Menu Items
7+
8+
Menu Item extensions are used together with [Menu](menu.md) extensions. Menu items can be added to custom menus, sidebars, and even the built-in Umbraco menus. Developers can either use the default Menu Item component or create custom Menu Item elements and register them as extensions.
9+
10+
11+
<figure><img src="../../../.gitbook/assets/menu-item.png" alt="" width="250"><figcaption><p>Menu Item</p></figcaption></figure>
12+
13+
## Creating Menu Items
14+
15+
Menu Item extensions can be defined either with JSON in `umbraco-package.json` or with TypeScript.
16+
17+
### Manifest
18+
19+
To add custom menu items, define a single `menuItem` manifest and link an element to it. Inside that element, you can fetch data and render as many menu items as needed based on that data.
20+
21+
{% tabs %}
22+
{% tab title="JSON" %}
23+
{% code title="umbraco-package.json" %}
24+
```json
25+
{
26+
"$schema": "../../umbraco-package-schema.json",
27+
"name": "My Package",
28+
"version": "0.1.0",
29+
"extensions": [
30+
{
31+
"type": "menuItem",
32+
"alias": "My.MenuItem",
33+
"name": "My Menu Item",
34+
"element": "./menu-items.ts",
35+
"meta": {
36+
"label": "My Menu Item",
37+
"menus": ["My.Menu"]
38+
}
39+
}
40+
]
41+
}
42+
```
43+
{% hint style="info" %}
44+
The `element` property is optional. If you omit it, Umbraco will render a default-styled menu item.
45+
{% endhint %}
46+
{% endcode %}
47+
{% endtab %}
48+
{% tab title="TypeScript" %}
49+
50+
Extension authors define the menu manifest, then register it dynamically/during runtime using a [Backoffice Entry Point](../../extending-overview/extension-types/backoffice-entry-point.md) extension.
51+
52+
{% code title="my-menu/manifests.ts" %}
53+
```typescript
54+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
55+
56+
export const menuItemManifest: ManifestMenuItem = {
57+
type: 'menuItem',
58+
alias: 'My.MenuItem',
59+
name: 'My Menu Item',
60+
meta: {
61+
label: 'My Menu Item',
62+
menus: ["My.Menu"]
63+
},
64+
};
65+
```
66+
{% endcode %}
67+
68+
{% code title="entrypoints/entrypoints.ts" %}
69+
```typescript
70+
import type {
71+
UmbEntryPointOnInit,
72+
} from "@umbraco-cms/backoffice/extension-api";
73+
import { umbExtensionsRegistry } from "@umbraco-cms/backoffice/extension-registry";
74+
import { menuItemManifest } from "./../my-menu/manifests.ts";
75+
76+
export const onInit: UmbEntryPointOnInit = (_host, _extensionRegistry) => {
77+
console.log("Hello from my extension 🎉");
78+
79+
umbExtensionsRegistry.register(menuItemManifest);
80+
};
81+
```
82+
{% endcode %}
83+
{% endtab %}
84+
{% endtabs %}
85+
86+
## Associate Menu Items with Entities
87+
88+
The `menuItem` extension type accepts an optional `entityType` property. When set, this property automatically links the menu item to the matching workspace and shows any registered Entity Actions for that entity type.
89+
90+
{% code title="menu-item.ts" %}
91+
```typescript
92+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
93+
94+
export const menuItemManifest: ManifestMenuItem = {
95+
type: 'menuItem',
96+
alias: 'Umb.MenuItem.Users',
97+
name: 'Users Menu Item',
98+
weight: 200,
99+
meta: {
100+
label: '#treeHeaders_users',
101+
icon: 'icon-user',
102+
entityType: UMB_USER_ROOT_ENTITY_TYPE,
103+
menus: [UMB_USER_MANAGEMENT_MENU_ALIAS],
104+
},
105+
};
106+
```
107+
{% endcode %}
108+
109+
## Menu Item Kinds
110+
111+
The Umbraco backoffice streamlines displaying menu items by providing three kinds that extension authors can reuse. These menu item kinds cover common tasks, including registering `links`, `actions` and `trees`.
112+
113+
### Links
114+
115+
Use a link menu item to navigate to another location, typically external URLs.
116+
117+
{% code title="menu-item.ts" %}
118+
```typescript
119+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
120+
121+
export const menuItemManifest: ManifestMenuItem = {
122+
type: 'menuItem',
123+
kind: 'link',
124+
alias: 'Umb.MenuItem.Help.LearningBase',
125+
name: 'Learning Base Help Menu Item',
126+
weight: 200,
127+
meta: {
128+
menus: [UMB_HELP_MENU_ALIAS],
129+
label: 'Umbraco Learning Base',
130+
icon: 'icon-movie-alt',
131+
href: 'https://umbra.co/ulb',
132+
},
133+
};
134+
```
135+
{% endcode %}
136+
137+
### Action
138+
139+
Developers can use an action menu item when they want to execute custom logic that runs when the item is clicked. This kind is similar to the default menu item but does not support `entityType`, and therefore does not automatically link to workspaces or Entity Actions.
140+
141+
{% code title="menu-item.ts" %}
142+
```typescript
143+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
144+
145+
export const menuItemManifest: ManifestMenuItem = {
146+
type: 'menuItem',
147+
kind: 'action',
148+
alias: 'Umb.MenuItem.Tiptap.TableProperties',
149+
name: 'Tiptap Table Menu Item: Table Properties',
150+
api: () => import('./actions/table-properties.action.js'),
151+
weight: 110,
152+
meta: {
153+
label: 'Table properties',
154+
menus: [UMB_MENU_TIPTAP_TABLE_ALIAS],
155+
},
156+
};
157+
```
158+
{% endcode %}
159+
160+
### Tree
161+
162+
Use a tree menu item to show a submenu based on a tree structure. Any existing, registered Tree Repositories can be referenced by its extension alias (`treeAlias` property) in the Menu Item manifest. This will render a fully functional tree-based menu.
163+
164+
{% code title="menu-item.ts" %}
165+
```typescript
166+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
167+
168+
export const menuItemManifest: ManifestMenuItem = {
169+
type: 'menuItem',
170+
kind: 'tree',
171+
alias: UMB_MEDIA_MENU_ITEM_ALIAS,
172+
name: 'Media Menu Item',
173+
weight: 100,
174+
meta: {
175+
label: 'Media',
176+
menus: [UMB_MEDIA_MENU_ALIAS],
177+
treeAlias: UMB_MEDIA_TREE_ALIAS,
178+
hideTreeRoot: true,
179+
},
180+
};
181+
```
182+
{% endcode %}
183+
184+
## Custom Menu Items
185+
186+
{% hint style="info" %}
187+
**Note:** You do not need a custom menu item subclass to display menu item extensions. Creating a custom class is optional.
188+
{% endhint %}
189+
190+
To render custom menu items, developers can use the [Umbraco UI Menu Item component](https://uui.umbraco.com/?path=/docs/uui-menu-item--docs). This component supports nested menu structures with minimal markup.
191+
192+
`<uui-menu-item>` elements accept a `has-children` boolean attribute, which shows a caret icon to indicate nested items. When using Lit, you can bind this with the `?` directive, for example: `?has-children=${boolVariable}`.
193+
194+
```html
195+
<uui-menu-item label="Menu Item 1" has-children>
196+
<uui-menu-item label="Nested Menu Item 1"></uui-menu-item>
197+
<uui-menu-item label="Nested Menu Item 2"></uui-menu-item>
198+
</uui-menu-item>
199+
```
200+
201+
### Custom menu item element example
202+
203+
Custom elements can fetch data and render menu items using markup like the example above. Storing fetched results in a `@state()` property ensures the component re-renders whenever the value changes.
204+
205+
{% tabs %}
206+
{% tab title="my-menu/menu-items.ts" %}
207+
{% code title="menu-items.ts" overflow="wrap" lineNumbers="true" %}
208+
```typescript
209+
import type { UmbMenuItemElement } from '@umbraco-cms/backoffice/menu';
210+
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
211+
import { html, TemplateResult, customElement, state } from '@umbraco-cms/backoffice/external/lit';
212+
import { MyMenuItemResponseModel, MyMenuResource } from '../../../api';
213+
214+
@customElement('my-menu-item')
215+
class MyMenuItems extends UmbLitElement implements UmbMenuItemElement {
216+
@state()
217+
private _items: MyMenuItemResponseModel[] = []; // Store fetched items
218+
219+
@state()
220+
private _loading: boolean = true; // Track loading state
221+
222+
@state()
223+
private _error: string | null = null; // Track any errors
224+
225+
override firstUpdated() {
226+
this.fetchInitialItems(); // Start fetching on component load
227+
}
228+
229+
// Fetch initial items
230+
async fetchInitialItems() {
231+
try {
232+
this._loading = true;
233+
this._items = ((await MyMenuResource.getMenuApiV1()).items); // Fetch root-level items
234+
} catch (e) {
235+
this._error = 'Error fetching items';
236+
} finally {
237+
this._loading = false;
238+
}
239+
}
240+
241+
// Render items
242+
renderItems(items: MyMenuItemResponseModel[]): TemplateResult {
243+
return html`
244+
${items.map(element => html`
245+
<uui-menu-item label="${element.name}" ?has-children=${element.hasChildren}>
246+
${element.type === 1
247+
? html`<uui-icon slot="icon" name="icon-folder"></uui-icon>`
248+
: html`<uui-icon slot="icon" name="icon-autofill"></uui-icon>`}
249+
<!-- recursively render children -->
250+
${element.hasChildren ? this.renderItems(element.children) : ''}
251+
</uui-menu-item>
252+
`)}
253+
`;
254+
}
255+
256+
// Main render function
257+
override render() {
258+
if (this._loading) {
259+
return html`<uui-loader></uui-loader>`;
260+
}
261+
262+
if (this._error) {
263+
return html`<uui-menu-item active disabled label="Could not load form tree!">
264+
</uui-menu-item>`;
265+
}
266+
267+
// Render items if loading is done and no error occurred
268+
return this.renderItems(this._items);
269+
}
270+
}
271+
272+
export { MyMenuItems as element };
273+
274+
declare global {
275+
interface HTMLElementTagNameMap {
276+
['my-menu-item']: MyMenuItems;
277+
}
278+
}
279+
```
280+
{% endcode %}
281+
{% endtab %}
282+
283+
{% tab title="my-menu/manifests.ts" %}
284+
```typescript
285+
import type { ManifestMenuItem } from "@umbraco-cms/backoffice/menu";
286+
287+
export const MyMenuItemManifest: ManifestMenuItem = {
288+
type: "menuItem",
289+
alias: "My.MenuItem.CustomMenuItem",
290+
name: "My Custom Menu Item",
291+
element: () => import("./menu-items.ts"),
292+
meta: {
293+
label: "Smtp",
294+
menus: ["Umb.Menu.Content"],
295+
},
296+
};
297+
```
298+
{% hint style="info" %}
299+
**Note:** Extension authors can use the `kind` property to define the type of menu item. Supported values include `tree` and `list`.
300+
{% endhint %}
301+
{% endtab %}
302+
303+
{% tab title="entrypoints/entrypoints.ts" %}
304+
```typescript
305+
import type {
306+
UmbEntryPointOnInit,
307+
} from "@umbraco-cms/backoffice/extension-api";
308+
import { umbExtensionsRegistry } from "@umbraco-cms/backoffice/extension-registry";
309+
import { MyMenuItemManifest } from "./../my-menu/manifests.ts";
310+
311+
export const onInit: UmbEntryPointOnInit = (_host, _extensionRegistry) => {
312+
console.log("Hello from my extension 🎉");
313+
314+
umbExtensionsRegistry.register(MyMenuItemManifest);
315+
};
316+
```
317+
{% endtab %}
318+
{% endtabs %}
319+
320+
## Adding menu items to an existing menu
321+
322+
Developers can add their own menu items to the built-in Umbraco menus.
323+
324+
Examples of built-in menus include:
325+
326+
* Content - `Umb.Menu.Content`
327+
* Media - `Umb.Menu.Media`
328+
* Settings - `Umb.Menu.StructureSettings`
329+
* Templating - `Umb.Menu.Templating`
330+
* ...
331+
332+
You can find all available Umbraco menus (nine in total) using the Extension Insights browser by selecting **Menu** from the dropdown.
333+
334+
<figure><img src="../../../.gitbook/assets/extension-types-backoffice-browser.png" alt=""><figcaption><p>Backoffice extension browser</p></figcaption></figure>
335+
336+
### Extending Menus
337+
338+
To add a menu item to an existing menu, use the `meta.menus` property.
339+
340+
{% code title="umbraco-package.json" %}
341+
```json
342+
{
343+
"$schema": "../../umbraco-package-schema.json",
344+
"name": "My Package",
345+
"version": "0.1.0",
346+
"extensions": [
347+
{
348+
"type": "menuItem",
349+
"alias": "My.MenuItem",
350+
"name": "My Menu Item",
351+
"meta": {
352+
"label": "My Menu Item",
353+
"menus": ["Umb.Menu.Content"]
354+
},
355+
"element": "menu-items.js"
356+
}
357+
]
358+
}
359+
```
360+
{% endcode %}

‎17/umbraco-cms/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,7 @@
171171
* [Kinds](customizing/extending-overview/extension-types/kind.md)
172172
* [Localization](customizing/extending-overview/extension-types/localization.md)
173173
* [Menu](customizing/extending-overview/extension-types/menu.md)
174+
* [Menu Item](customizing/extending-overview/extension-types/menu-item.md)
174175
* [Modals](customizing/extending-overview/extension-types/modals/README.md)
175176
* [Confirm Dialog](customizing/extending-overview/extension-types/modals/confirm-dialog.md)
176177
* [Custom Modals](customizing/extending-overview/extension-types/modals/custom-modals.md)

‎17/umbraco-cms/customizing/extending-overview/extension-types/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,10 @@ The `localization` extension type is used to register additional languages and f
7373

7474
The `menu` extension type is used to create custom menus. These can be placed in sidebar extensions or displayed as a fly-out from a button, header, or workspace view.
7575

76+
### [Menu Items](menu-item.md)
77+
78+
The `menuItem` extension type is used to create custom menu items. These can be used in conjunction with custom menu extensions or placed in any of the existing/default Umbraco menus.
79+
7680
### [Modals](modals/README.md)
7781

7882
The `modal` extension type is used to configure and present dialogs and sidebars within the Umbraco backoffice.

0 commit comments

Comments
 (0)