Menu Items

[bszyman]

📋 Description

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.

📎 Related Issues (if applicable)

#7495

✅ Contributor Checklist

I've followed the Umbraco Documentation Style Guide and can confirm that:

• Code blocks are correctly formatted.
• Sentences are short and clear (preferably under 25 words).
• Passive voice and first-person language (“we”, “I”) are avoided.
• Relevant pages are linked.
• All links work and point to the correct resources.
• Screenshots or diagrams are included if useful.
• Any code examples or instructions have been tested.
• Typos, broken links, and broken images are fixed.

Product & Version (if relevant)

v16

Deadline (if relevant)

N/A

📚 Helpful Resources

• 🧾 Umbraco Contribution Guidelines
• ✍️ Umbraco Documentation Style Guide

[madsrasmussen]

Hi @bszyman

It looks good!

We somehow need to cover that the default manifest has an optional meta field for "entityType". When using this, it will automatically link to a matching workspace and show any registered Entity Actions for that type. It is a bit magical, but I think a lot will look for this setting.

Additionally, I think it would be beneficial to cover some of the different Menu Item kinds we ship out of the box. It might also help make the extension experience better if we can get something to show as fast as possible in the UI. Additionally, when using one of the kinds, the developer gets a lot of functionality out of the box by just filling out the manifest. 

I think these kinds should be mentioned first in the article, then your custom example as the last one.

Example from the codebase:

{
  type: 'menuItem',
  alias: 'Umb.MenuItem.Users',
  name: 'Users Menu Item',
  weight: 200,
  meta: {
    label: '#treeHeaders_users',
    icon: 'icon-user',
    entityType: UMB_USER_ROOT_ENTITY_TYPE,
    menus: [UMB_USER_MANAGEMENT_MENU_ALIAS],
   },
 }

Here are some rough notes about the different kinds:

We currently have 3 different kinds:

• Link: Link to any resource.
• Action: Almost the same as the default behaviour, but do not support the Entity Type and therefore not the entity actions.
• Tree: Render a tree-based sub-menu inside the menu item

The following manifest examples are taken directly from the codebase. Feel free to adjust so it becomes a bit more generic:

Link

Register a menu item that can link to something. Mostly used when linking to something external:

Manifest:

{
  type: 'menuItem',
  kind: 'link',
  alias: 'Umb.MenuItem.Help.LearningBase',
  name: 'Learning Base Help Menu Item',
  weight: 200,
  meta: {
    menus: [UMB_HELP_MENU_ALIAS],
    label: 'Umbraco Learning Base',
    icon: 'icon-movie-alt',
    href: 'https://umbra.co/ulb',
  },
}

Action

A Menu Item with a custom Api Class. An executed method will be triggered when the menu item is clicked. This one is very close to the default menu item but it is not possible to pass in an entityType and therefore won't automatically link to a workspace or support Entity Actions.

Manifest

{
  type: 'menuItem',
  kind: 'action',
  alias: 'Umb.MenuItem.Tiptap.TableProperties',
  name: 'Tiptap Table Menu Item: Table Properties',
  api: () => import('./actions/table-properties.action.js'),
  weight: 110,
  meta: {
    label: 'Table properties',
    menus: [UMB_MENU_TIPTAP_TABLE_ALIAS],
  },
}

Tree

Register a menu item with a sub-menu based on a tree structure. If the developer has already implemented and registered a Tree Repository, they can reference the Tree Repository extension alias in the Menu Item manifest and get a full tree-based menu out of the box.

Manifest

{
  type: 'menuItem',
  kind: 'tree',
  alias: UMB_MEDIA_MENU_ITEM_ALIAS,
  name: 'Media Menu Item',
  weight: 100,
  meta: {
    label: 'Media',
    menus: [UMB_MEDIA_MENU_ALIAS],
    treeAlias: UMB_MEDIA_TREE_ALIAS,
    hideTreeRoot: true,
  },
}

[madsrasmussen]

This line is almost the same as the one above. Can we remove one of them?

"Menu Item extensions can be defined using either JSON in umbraco-package.json or using TypeScript."
"Menu Item extensions can be created using either JSON or TypeScript. Both approaches are shown below."