Skip to content

Review Menu API #10237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 16, 2025
Merged

Review Menu API #10237

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 46 additions & 46 deletions ...k/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/menu-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,40 @@ url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/menu-api/

## Introduction

This how-to shows you how to create both a simple menu item and a menu item with subsidiary items beneath it using the web extension API.
This how-to describes how to create menus using the web extensibility API. In this example, you will:

* Create a simple menu item
* Add menu items with sub-menus
* Update a menu

## Prerequisites

This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). Please complete that how-to before starting this one.
This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). Make sure to complete that how-to before starting this one.

## Creating a Simple Menu
## Menu Properties

In this section, you will add a simple menu to your extension.
A menu has the following properties:

The code below will:
| Property | Description |
|----------------------|-------------------------------------------------------------------------------|
| `caption` | The text of the menu item |
| `menuId` | A unique identifier for the menu item |
| `subMenus` | A list of sub-menu items |
| `hasSeparatorBefore` <br> (default: `false`) | Adds a visual separator before the item |
| `hasSeparatorAfter` <br> (default: `false`) | Adds a visual separator after the item |
| `enabled` <br> (default: `true`) | Indicates that the menu item notifies the listener when clicked |

* create a menu item with the caption "My First Menu"
* show a dialog when the menu is clicked

{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/grouped_menus.png" width="300" >}}

## Creating a Simple Menu

The code below adds a simple menu to your extension. The code will:

* Create a menu item with the caption *My First Menu*
* Show a dialog when the menu is clicked
* Import `menuApi` from `studioPro.ui.extensionsMenu` to allow you to use the menu API
* Import `messageBoxApi` from `studioPro.ui.messageBoxes` to show a dialog

Replace your `src/main/index.ts` file with the following:

Expand Down Expand Up @@ -56,43 +76,28 @@ export const component: IComponent = {
}
```

The code imports the following:

* `menuApi` from `studioPro.ui.extensionsMenu` to allow you to use the menu API
* `messageBoxApi` from `studioPro.ui.messageBoxes` to show a dialog.
When this code is added, it does the following:

It starts listening to the `menuItemActivated` endpoint which will notify the extension when **My First Menu** is clicked.

The `menuItemActivated` listener event handles the actual function of the menu. The arguments `args` contain the data returned by Studio Pro to the extension, notifying it which menu item was activated (clicked). This is passed as the `menuId` that was used when creating the menu item and the `menuId` in the `if` statement is used to identify this. In this example it is `"my-menu-unique-id"` and the handler calls the `messageBoxApi` to show an information dialog.
1. Studio Pro starts listening to the `menuItemActivated` endpoint. This notifies the extension when **My First Menu** is clicked.
2. The `args` parameter contains the information sent from Studio Pro to the extension, indicating which menu item was clicked.
3. The listener checks if the clicked `menuId` matches your defined ID. If it does, it calls `messageBoxApi.show()`.
4. Studio Pro displays an information dialog with the message you provided.

Your extensions should now appear like this:

{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/my_first_menu.png" >}}

## Menu Properties

The menu has the following properties:

* `caption` – the text of the menu item
* `menuId` – a unique id for the menu item
* `subMenus` – a list of menus subsidiary to this menu item
* `hasSeparatorBefore` (default: `false`) – shows a visual separator before this menu item
* `hasSeparatorAfter` (default: `false`) – shows a visual separator after this menu item
* `enabled` (default: `true`) – indicates that this menu item notifies the listener when clicked

{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/grouped_menus.png" >}}
{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/my_first_menu.png" width="200" >}}

## Creating a Menu with Submenus

You can also have a number of submenus that branch out your menu.
You can also include multiple sub-menus to expand your menu structure.

To do so, add additional menu items to your code and add these to the `subMenus` array for the relevant menu item. These child menus can in turn have their own submenus, and so on. Only parent menus (menus that are not sub menus to any others) should be added through the `await menuApi.add()` call, as shown in the code sample below.
To do this, add additional menu items to your code and add them to the `subMenus` array for the relevant menu item. These child menus can have their own sub-menus, and so on. Only parent menus (menus that are not sub-menus to any others) should be added through the `await menuApi.add()` call, as shown in the code sample below.

{{% alert color="info" %}}
Parent menus (with `subMenus`) do not create `menuItemActivated` events. These only get sent when a leaf menu (a menu that does not have any submenus) is clicked.
Parent menus (with `subMenus`) do not create `menuItemActivated` events. These are only sent when a leaf menu (a menu that does not have any sub-menus) is clicked.
{{% /alert %}}

The following `src/main/index.ts` generates one menu item with sub menus and one menu item without sub menus.
The following `src/main/index.ts` generates one menu item with sub-menus, and one menu item without sub-menus.

```typescript
import { IComponent, Menu, getStudioProApi } from "@mendix/extensions-api";
Expand Down Expand Up @@ -142,15 +147,15 @@ export const component: IComponent = {
}
```

The menu hierarchy will then be displayed like this:
The menu hierarchy will be displayed like this:

{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/child_menus.png" >}}

## Updating a menu
## Updating a Menu

Sometimes you might want to disable a menu or update its caption depending on a condition. You can do so by calling the menu API's `updateMenu` method.
You can disable a menu or update its caption, depending on a condition. You can do this by calling the menu API's `updateMenu` method.

An example is shown in the code below. If you click on the menu item, it will be disabled and its caption will be updated.
An example is shown in the code below. If you click the menu item, it will be disabled and its caption will be updated.

{{% alert color="info" %}}
Only `caption` and `enabled` can be updated.
Expand Down Expand Up @@ -191,23 +196,18 @@ export const component: IComponent = {
}
```

The disabled state is shown in the image below.
The disabled state is shown in the image below:

{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/disabled_menu.png" >}}
{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/disabled_menu.png" width="300" >}}

## Attaching a Command to the Menu

Instead of listening to the `menuItemActivated` event, it is possible to register a command, then attach the `commandId` of the new command to your menu. When the menu is clicked, if its `commandId` property has been set, the backend will execute the command instead of firing the `menuItemActivated` event.

For a full explanation on how to register commands, see the [Commands API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/command-api/).

## Conclusion

You have seen how to create simple menu items and menu items with sub menus.
You can also dynamically change the enabled status and caption of a menu item.
For more information on how to register commands, see the [Commands API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/command-api/).

## Extensibility Feedback

If you would like to provide us with some additional feedback you can complete a small [Survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback)
If you would like to provide additional feedback, you can complete a small [survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback).

Any feedback is much appreciated.
Any feedback is appreciated.