Get Started with the Web Extensibility API

Introduction

Studio Pro extensions can be developed using TypeScript and use standard web development technologies to extend the Studio Pro development environment. This guide shows you how to set up a basic development environment for building an extension using the web extensibility API.

For more detailed information, see the Mendix Studio Pro Web Extensibility API reference documentation.

Prerequisites

You will need the following prerequisites:

• Mendix Studio Pro version 11.2.0 or higher.
• A development IDE to develop your extensions. We recommend using Visual Studio Code.
• Install the latest version 22.x.x of Node: https://nodejs.org/en/download.

Creating Your First Extension

This section will show you how to build and test an extension.

Create a Test App

Create a new app using the Blank Web App template.

Creating the Extension

To accelerate your extension development, we provide an extension generator that creates a customizable sample extension.

To use the generator, navigate to your desired source code directory and run the command npm create @mendix/extension. You may be prompted by npm to grant permission to install the generator. After installation, you will be guided through a series of questions to help configure your extension.

You will be asked the following:

• Select the programming language (TypeScript is used in our tutorials)
• Specify the extension name
• Choose if you will use React for the extension’s UI

The next two questions, while optional, are highly recommended, as they enable direct debugging and deployment from Visual Studio Code.

• Specify the path to the Studio Pro executable (this allows Visual Studio Code to automatically attach to Studio Pro for debugging)
• Specify the location of the application .mpr package. (This allows for automatic deployment of your extension build to your app)

The final question allows you to select the Studio Pro version you are targeting; we recommend you choose version 11.

Once you have completed the setup, a new directory named after your extension will be created, containing the source code of the extension.

Exploring the Created Extension

In the following example, the name of your extension is myextension and you are exploring it using Visual Studio Code.

Before you begin, your extension will have to get an instance of the Studio Pro API. to do this, from the Explorer window, navigate to src/main/index.ts and select it to open the file.

In the source code, you should see the following:

1. Line 6 gets an instance of the Studio Pro API by calling getStudioProApi.

   export const component: IComponent = {
       async loaded(componentContext) {
           const studioPro = getStudioProApi(componentContext);

2. Line 7 adds a menu:

   await studioPro.ui.extensionsMenu.add({
       menuId: "myextension.MainMenu",
       caption: "MyExtension Menu",
       subMenus: [
           { menuId: "myextension.ShowMenu", caption: "Show tab" },
       ],
   });

3. Line 16 opens a tab.

   // Open a tab when the menu item is clicked
   studioPro.ui.extensionsMenu.addEventListener(
       "menuItemActivated",
       (args) => {
           if (args.menuId === "myextension.ShowMenu") {
               studioPro.ui.tabs.open(
                   {
                       title: "MyExtension Tab"
                   },
                   {
                       componentName: "extension/myextension",
                       uiEntrypoint: "tab",
                   }
               );
           }
       }
   );

4. If you navigate to build-extension.mjs, you can choose the directory to which the extension will be installed to after being built by changing line 6:

   const appDir = "C:\\TestApps\\AppTestExtensions"

5. The file .vscode\launch.json specifies the launch configuration and enables debugging. The following lines specify how Studio Pro will be run:

   …
   "runtimeExecutable": "C:\\Program Files\\Mendix\\11.2.0\\modeler\\studiopro.exe",
   "runtimeArgs": ["C:\\TestApps\\AppTestExtensions\\AppTestExtensions.mpr", "--enable-extension-development", "--enable-web-extensions"],
   …

When you install the extension, you will see a new menu item within Studio Pro.

Building, Installing, and Debugging the Extension

The following steps occur within Visual Studio Code:

1. Select File > Open Folder.
2. Navigate to the folder where you created your extension.
3. Click Select Folder.
4. Select Yes if you are asked whether you trust this folder.
5. Open a Terminal from the top menu by clicking Terminal > New Terminal.
6. From the Terminal, type npm install. This installs all dependencies for the extension.
7. Build your extension using the command npm run build in the terminal. If you provided the path to .mpr file in the previous step, this will install the extension into the application directory.

If the last two questions of the extension generator were answered and you have built and installed the extension, you can debug it by following the steps below:

1. Open the extension source code in Visual Studio Code and set breakpoints.
2. Select Run and Debug from the side panel.
3. Click the play button on the top of the panel (or press F5).

This will run Studio Pro in extension development mode and open the configured application. You will see a new Extensions item in the top menu.

Conclusion

Using this guide we have:

• Created a new app
• Used the extension generator to get started with extension development
• Built the extension and installed it in our app
• Tested and debugged our extension from within Visual Studio Code

Extensibility Feedback

If you would like to provide us with some additional feedback you can complete a small Survey

Any feedback is much appreciated.