Skip to content

Commit 352d4ff

Browse files
eshanrnheshanrnh
authored
Merge pull request #7496 from bszyman/menu-items
Menu Items
2 parents 6170613 + ac2defb commit 352d4ff

File tree

6 files changed

+766
-0
lines changed

6 files changed

+766
-0
lines changed

‎16/umbraco-cms/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@
172172
* [Kinds](customizing/extending-overview/extension-types/kind.md)
173173
* [Localization](customizing/extending-overview/extension-types/localization.md)
174174
* [Menu](customizing/extending-overview/extension-types/menu.md)
175+
* [Menu Item](customizing/extending-overview/extension-types/menu-item.md)
175176
* [Modals](customizing/extending-overview/extension-types/modals/README.md)
176177
* [Confirm Dialog](customizing/extending-overview/extension-types/modals/confirm-dialog.md)
177178
* [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: 378 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,378 @@
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 JavaScript/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": "./my-menu-item.element.js",
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+
element: './my-menu-item.element.ts',
61+
meta: {
62+
label: 'My Menu Item',
63+
icon: 'icon-wand',
64+
menus: ["My.Menu"]
65+
},
66+
};
67+
```
68+
{% endcode %}
69+
70+
{% code title="entrypoints/entrypoints.ts" %}
71+
```typescript
72+
import type {
73+
UmbEntryPointOnInit,
74+
} from "@umbraco-cms/backoffice/extension-api";
75+
import { umbExtensionsRegistry } from "@umbraco-cms/backoffice/extension-registry";
76+
import { menuItemManifest } from "./../my-menu/manifests.ts";
77+
78+
export const onInit: UmbEntryPointOnInit = (_host, _extensionRegistry) => {
79+
console.log("Hello from my extension 🎉");
80+
81+
umbExtensionsRegistry.register(menuItemManifest);
82+
};
83+
```
84+
{% endcode %}
85+
{% endtab %}
86+
{% endtabs %}
87+
88+
## Associate Menu Items with Entities
89+
90+
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.
91+
92+
{% code title="menu-item.ts" %}
93+
```typescript
94+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
95+
96+
export const menuItemManifest: ManifestMenuItem = {
97+
type: 'menuItem',
98+
alias: 'My.MenuItem',
99+
name: 'My Menu Item',
100+
meta: {
101+
label: 'My Menu Item',
102+
icon: 'icon-wand',
103+
entityType: 'my-entity-type',
104+
menus: ["My.Menu"]
105+
},
106+
};
107+
```
108+
{% endcode %}
109+
110+
## Menu Item Kinds
111+
112+
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`.
113+
114+
### Links
115+
116+
Use a link menu item to navigate to another location, typically external URLs.
117+
118+
{% code title="menu-item.ts" %}
119+
```typescript
120+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
121+
122+
export const menuItemManifest: ManifestMenuItem = {
123+
type: 'menuItem',
124+
kind: 'link',
125+
alias: 'My.MenuItem.ExternalLink',
126+
name: 'My External Link Menu Item',
127+
weight: 200,
128+
meta: {
129+
label: 'My Link Menu Item',
130+
icon: 'icon-link',
131+
href: 'https://',
132+
menus: ["My.Menu"],
133+
},
134+
};
135+
```
136+
{% endcode %}
137+
138+
### Action
139+
140+
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.
141+
142+
{% code title="menu-item.ts" %}
143+
```typescript
144+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
145+
146+
export const menuItemManifest: ManifestMenuItem = {
147+
type: 'menuItem',
148+
kind: 'action',
149+
alias: 'My.MenuItem.Action',
150+
name: 'My Action Menu Item',
151+
api: () => import('./my-action-menu-item.api.js'),
152+
meta: {
153+
label: 'My Action Menu Item',
154+
icon: 'icon-hammer',
155+
menus: ["My.Menu"],
156+
},
157+
};
158+
```
159+
{% endcode %}
160+
161+
{% code title="menu-item.api.ts" %}
162+
```typescript
163+
import { UmbMenuItemActionApiBase } from '@umbraco-cms/backoffice/menu';
164+
165+
export class MyActionMenuItemApi extends UmbMenuItemActionApiBase<never> {
166+
/**
167+
* This method is executed when the menu item is clicked
168+
*/
169+
override async execute() {
170+
console.log('Hello world');
171+
}
172+
}
173+
174+
// Declare an `api` export so the Extension Registry can initialize this class
175+
export { MyActionMenuItemApi as api };
176+
```
177+
{% endcode %}
178+
179+
### Tree
180+
181+
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.
182+
183+
{% code title="menu-item.ts" %}
184+
```typescript
185+
import type { ManifestMenuItem } from '@umbraco-cms/backoffice/menu';
186+
187+
export const menuItemManifest: ManifestMenuItem = {
188+
type: 'menuItem',
189+
kind: 'tree',
190+
alias: 'My.MenuItem.Tree',
191+
name: 'My Tree Menu Item',
192+
meta: {
193+
label: 'My Tree Menu Item',
194+
icon: 'icon-hammer',
195+
treeAlias: 'My.Repository.Tree',
196+
menus: ["My.Menu"],
197+
},
198+
};
199+
```
200+
{% endcode %}
201+
202+
## Custom Menu Items
203+
204+
{% hint style="info" %}
205+
**Note:** You do not need a custom menu item subclass to display menu item extensions. Creating a custom class is optional.
206+
{% endhint %}
207+
208+
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.
209+
210+
`<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}`.
211+
212+
```html
213+
<uui-menu-item label="Menu Item 1" has-children>
214+
<uui-menu-item label="Nested Menu Item 1"></uui-menu-item>
215+
<uui-menu-item label="Nested Menu Item 2"></uui-menu-item>
216+
</uui-menu-item>
217+
```
218+
219+
### Custom menu item element example
220+
221+
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.
222+
223+
{% tabs %}
224+
{% tab title="my-menu/menu-items.ts" %}
225+
{% code title="menu-items.ts" overflow="wrap" lineNumbers="true" %}
226+
```typescript
227+
import type { UmbMenuItemElement } from '@umbraco-cms/backoffice/menu';
228+
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
229+
import { html, TemplateResult, customElement, state } from '@umbraco-cms/backoffice/external/lit';
230+
import { MyMenuItemResponseModel, MyMenuResource } from '../../../api';
231+
232+
@customElement('my-menu-item')
233+
class MyMenuItems extends UmbLitElement implements UmbMenuItemElement {
234+
@state()
235+
private _items: MyMenuItemResponseModel[] = []; // Store fetched items
236+
237+
@state()
238+
private _loading: boolean = true; // Track loading state
239+
240+
@state()
241+
private _error: string | null = null; // Track any errors
242+
243+
override firstUpdated() {
244+
this.fetchInitialItems(); // Start fetching on component load
245+
}
246+
247+
// Fetch initial items
248+
async fetchInitialItems() {
249+
try {
250+
this._loading = true;
251+
this._items = ((await MyMenuResource.getMenuApiV1()).items); // Fetch root-level items
252+
} catch (e) {
253+
this._error = 'Error fetching items';
254+
} finally {
255+
this._loading = false;
256+
}
257+
}
258+
259+
// Render items
260+
renderItems(items: MyMenuItemResponseModel[]): TemplateResult {
261+
return html`
262+
${items.map(element => html`
263+
<uui-menu-item label="${element.name}" ?has-children=${element.hasChildren}>
264+
${element.type === 1
265+
? html`<uui-icon slot="icon" name="icon-folder"></uui-icon>`
266+
: html`<uui-icon slot="icon" name="icon-autofill"></uui-icon>`}
267+
<!-- recursively render children -->
268+
${element.hasChildren ? this.renderItems(element.children) : ''}
269+
</uui-menu-item>
270+
`)}
271+
`;
272+
}
273+
274+
// Main render function
275+
override render() {
276+
if (this._loading) {
277+
return html`<uui-loader></uui-loader>`;
278+
}
279+
280+
if (this._error) {
281+
return html`<uui-menu-item active disabled label="Could not load form tree!">
282+
</uui-menu-item>`;
283+
}
284+
285+
// Render items if loading is done and no error occurred
286+
return this.renderItems(this._items);
287+
}
288+
}
289+
290+
export { MyMenuItems as element };
291+
292+
declare global {
293+
interface HTMLElementTagNameMap {
294+
['my-menu-item']: MyMenuItems;
295+
}
296+
}
297+
```
298+
{% endcode %}
299+
{% endtab %}
300+
301+
{% tab title="my-menu/manifests.ts" %}
302+
```typescript
303+
import type { ManifestMenuItem } from "@umbraco-cms/backoffice/menu";
304+
305+
export const MyMenuItemManifest: ManifestMenuItem = {
306+
type: "menuItem",
307+
alias: "My.MenuItem.CustomMenuItem",
308+
name: "My Custom Menu Item",
309+
element: () => import("./menu-items.ts"),
310+
meta: {
311+
label: "Smtp",
312+
menus: ["Umb.Menu.Content"],
313+
},
314+
};
315+
```
316+
{% hint style="info" %}
317+
**Note:** Extension authors can use the `kind` property to define the type of menu item. Supported values include `tree` and `list`.
318+
{% endhint %}
319+
{% endtab %}
320+
321+
{% tab title="entrypoints/entrypoints.ts" %}
322+
```typescript
323+
import type {
324+
UmbEntryPointOnInit,
325+
} from "@umbraco-cms/backoffice/extension-api";
326+
import { umbExtensionsRegistry } from "@umbraco-cms/backoffice/extension-registry";
327+
import { MyMenuItemManifest } from "./../my-menu/manifests.ts";
328+
329+
export const onInit: UmbEntryPointOnInit = (_host, _extensionRegistry) => {
330+
console.log("Hello from my extension 🎉");
331+
332+
umbExtensionsRegistry.register(MyMenuItemManifest);
333+
};
334+
```
335+
{% endtab %}
336+
{% endtabs %}
337+
338+
## Adding menu items to an existing menu
339+
340+
Developers can add their own menu items to the built-in Umbraco menus.
341+
342+
Examples of built-in menus include:
343+
344+
* Content - `Umb.Menu.Content`
345+
* Media - `Umb.Menu.Media`
346+
* Settings - `Umb.Menu.StructureSettings`
347+
* Templating - `Umb.Menu.Templating`
348+
* And so on.
349+
350+
You can find all available Umbraco menus (nine in total) using the Extension Insights browser by selecting **Menu** from the dropdown.
351+
352+
<figure><img src="../../../.gitbook/assets/extension-types-backoffice-browser.png" alt=""><figcaption><p>Backoffice extension browser</p></figcaption></figure>
353+
354+
### Extending Menus
355+
356+
To add a menu item to an existing menu, use the `meta.menus` property.
357+
358+
{% code title="umbraco-package.json" %}
359+
```json
360+
{
361+
"$schema": "../../umbraco-package-schema.json",
362+
"name": "My Package",
363+
"version": "0.1.0",
364+
"extensions": [
365+
{
366+
"type": "menuItem",
367+
"alias": "My.MenuItem",
368+
"name": "My Menu Item",
369+
"meta": {
370+
"label": "My Menu Item",
371+
"menus": ["Umb.Menu.Content"]
372+
},
373+
"element": "menu-items.js"
374+
}
375+
]
376+
}
377+
```
378+
{% endcode %}

0 commit comments

Comments
 (0)