diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/_index.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/_index.md index 8ad0c9d44c8..7bf01fe152d 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/_index.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/_index.md @@ -20,6 +20,6 @@ For information on new releases of the Extensibility API see: ## Introduction -Extensions are self-contained modules which users can add to Studio Pro. This means that with extensibility you can add new features and functionality to Studio Pro. The Extensibility API is an API that allows developers to interact with a curated list of internal systems of Studio Pro. This documentation provides guides and reference documentation for the Extensibility API. +Extensions are self-contained modules that enhance Studio Pro by adding new features and functionality. The Extensibility API allows you to interact with a curated set of internal systems, extending Studio Pro’s capabilities with functionality you can define yourself. -The API is provided in two flavors, depending which language you are developing in. C# and web based (via Typescript): +The API is provided in two versions, depending on the language you are developing in: diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/packaging-your-extension.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/packaging-your-extension.md index f93cd635ef2..9a9601704a7 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/packaging-your-extension.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/packaging-your-extension.md @@ -4,26 +4,32 @@ url: /apidocs-mxsdk/apidocs/extensibility-api-10/packaging-your-extension weight: 30 --- -# Packaging your extension +# Packaging Your Extension -Once you have finished development on your extension, you might want to package it into an add-on module so that others can start using it. Once you have created the add-on module, it can then be published to the Mendix Marketplace for your extension users to download into their Studio Pro app. +After completing development on your extension, you can package it into an add-on module so others can use it. Once packaged, the module can be published to the Mendix Marketplace, allowing other users to download it into their Studio Pro apps. -To package your extension, you will still need the `--enable-extension-development` command line option turned on. Create a new module in your Studio Pro app containing your dev extension, give it an appropriate name. Open the module's settings form and set it to be an Add-on module. In the `Extension name` dropdown, select the extension you want to package into it. +To package your extension, follow the steps below: + +1. Make sure the `--enable-extension-development` command-line option is enabled. +2. In your Studio Pro app, create a new module and include your development extension. +3. Give the module a name. +4. Open the module's settings and in the **Export** tab, choose **Add-on module**. +5. In the **Extension name** drop-down, select the extension you want to package into it. ![Extension Add-on Module](/attachments/apidocs-mxsdk/apidocs/extensibility-api/extensionAddOnModule.png) -After you've created your add-on module with its extension, you can now export it, by right-clicking the module in the App Explorer and choosing `Export add-on module package`, as shown below. +After you have created your add-on module with its extension, you can export it by right-clicking the module in the App Explorer and selecting **Export add-on module package**. ![Export Module](/attachments/apidocs-mxsdk/apidocs/extensibility-api/exportAddOnModule.png) You can now save the add-on module to a location of your choice. -# Importing the extension add-on module +# Importing the Extension Add-on Module -Once the add-on module is available to a Studio Pro user, they are now able to add it in their application. They can so so by right-clicking the app in the App Explorer and choosing `Import module package`, as shown below. +When the add-on module is available to a Studio Pro user, they are now able to add it in their application. This is done by right-clicking the app in the **App Explorer** and selecting **Import module package**. ![Import Module](/attachments/apidocs-mxsdk/apidocs/extensibility-api/importAddOnModule.png) -Once an add-on module containing an extension is imported in the app, Studio Pro will show a warning to the user, asking to trust the extension contained in it. If the user does not choose to trust, the module will still be imported but the extension inside it won't be loaded. +When an add-on module containing an extension is imported in the app, Studio Pro will show a warning to the user, asking to trust the extension contained in it. If the user does not choose to trust, the module will still be imported but the extension inside it will not be loaded. ![Trust Extension](/attachments/apidocs-mxsdk/apidocs/extensibility-api/trustExtension.png) diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/_index.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/_index.md index 8c3716120e6..ec0ad3767fe 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/_index.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/_index.md @@ -13,23 +13,25 @@ weight: 20 ## Introduction -Extensions can be written in Typescript or other web languages, described here, or using a C# API which is documented separately in [Extensibility API for C# Developers](/apidocs-mxsdk/apidocs/csharp-extensibility-api-10/). +Extensions can be written in TypeScript or other web languages, described here, or using a C# API, which is documented in [Extensibility API for C# Developers](/apidocs-mxsdk/apidocs/csharp-extensibility-api-10/). For more detailed information on the web API, see the [Mendix Studio Pro Web Extensibility API reference documentation](http://apidocs.rnd.mendix.com/10/extensions-api/index.html). ## Prerequisites -* You need at least a basic understanding of the Mendix platform. -* You need some understanding of the Mendix Model. -* You need to have some TypeScript development experience. +To use the Web Extensibility API, you must have: + +* A basic understanding of the Mendix platform +* Some understanding of the Mendix Model +* Some TypeScript development experience ## Getting Started -For detailed explanation on how to get started with extensions, check out [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/getting-started/). +For detailed information on how to get started with extensions, see [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/getting-started/). ## How-tos -Here is a list of how-tos for you to begin with: +Below is a list of how-tos for you to begin with: * [How to Create a Dockable Pane Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/dockable-pane-api/) * [How to Interact With Local App Files Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/local-app-files-api/) diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/get-started.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/get-started.md index a145aaeffe6..11b52078396 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/get-started.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/get-started.md @@ -7,7 +7,7 @@ weight: 2 ## 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. +Studio Pro extensions can be developed using TypeScript and use standard web development technologies to extend the Studio Pro development environment. This document describes how to set up a basic development environment for building an extension using the web extensibility API. For more information see the [Mendix Studio Pro Web Extensibility API](http://apidocs.rnd.mendix.com/10/extensions-api/index.html). @@ -15,10 +15,9 @@ For more information see the [Mendix Studio Pro Web Extensibility API](http://ap You will need the following prerequisites: -* Mendix Studio Pro version 10.21.0 or higher [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro). -* Install the latest Studio Pro version from the Mendix [Marketplace](https://marketplace.mendix.com/link/studiopro/). -* A development IDE to develop your extensions. We recommend using [Visual Studio Code](https://code.visualstudio.com/). -* Install the latest version 22.x.x of Node: https://nodejs.org/en/download. +* [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro) version 10.21.0 or higher +* A development IDE to develop your extensions. Mendix recommends using [Visual Studio Code](https://code.visualstudio.com/) +* Install the latest version 22.x.x of Node: https://nodejs.org/en/download {{% alert color="info" %}} Extensions can be built on any operating system as the underlying framework is cross-platform. @@ -35,96 +34,84 @@ This section will show you how to build and test an extension. ### Building the Extension -From within Visual Studio Code: +Follow the below steps from within Visual Studio Code. -1. Select **File** -> **Open Folder** -1. Navigate to the folder you just extracted your extension source code to. -1. Click **Select Folder**. -1. Select **Yes** if you are asked whether you trust this folder. -1. Now open a Terminal by selecting **Terminal** -> **New Terminal** from the top menu. -1. From the Terminal type `npm install`. This installs all dependencies for the extension -1. Build your extension using the command `npm run build` in the terminal. +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. -Once completed you should now have a build artifact which we can deploy to your Mendix app. +Once completed, you should now have a build artifact which we can deploy to your Mendix app. -You can explore the extension a bit more to understand what it will do when it is installed. Do the following: +### Exploring the Created Extension -1. From the Explorer window navigate to `src/main/index.ts` select it to open the file. +You can explore the extension to understand what it does when it is installed. Do the following: + +1. From the Explorer window, navigate to `src/main/index.ts` and select it to open the file. Reading through the source code you should see the following: -1. Line 7 adds a menu - - ```typescript - await studioPro.ui.extensionsMenu.add({ - menuId: "myextension.MainMenu", - caption: "MyExtension Menu", - subMenus: [{ menuId: "myextension.ShowTabMenuItem", caption: "Show tab" }], - }); - ``` - -1. Line 14 opens a tab - - ```typescript - // Open a tab when the menu item is clicked - studioPro.ui.extensionsMenu.addEventListener("menuItemActivated", (args) => { - if (args.menuId === "myextension.ShowTabMenuItem") { - studioPro.ui.tabs.open( - { - title: "My Extension Tab", - }, - { - componentName: "extension/myextension", - uiEntrypoint: "tab", + a. Line 7 adds a menu + + ```typescript + await studioPro.ui.extensionsMenu.add({ + menuId: "myextension.MainMenu", + caption: "MyExtension Menu", + subMenus: [{ menuId: "myextension.ShowTabMenuItem", caption: "Show tab" }], + }); + ``` + + 2. Line 14 opens a tab + + ```typescript + // Open a tab when the menu item is clicked + studioPro.ui.extensionsMenu.addEventListener("menuItemActivated", (args) => { + if (args.menuId === "myextension.ShowTabMenuItem") { + studioPro.ui.tabs.open( + { + title: "My Extension Tab", + }, + { + componentName: "extension/myextension", + uiEntrypoint: "tab", + } + ); } - ); - } - }); - ``` + }); + ``` -When you install the extension you will see a new menu item within Studio Pro. +When you install the extension, you will see a new menu item within Studio Pro. ### Testing the Extension To test the extension, do the following in File Explorer. 1. Navigate to the folder where you extracted the extension source code. -1. Open the `dist` folder. -1. Copy the `myextension` folder. -1. Navigate to the folder where you created your app. -1. Create a new folder called `webextensions`. -1. Paste the `myextension` folder into the `webextensions` folder you just created. - - The extension files have now been added to the app. - -1. Start Studio Pro with the following command line parameters to tell it to use the extensions in the folder. +2. Open the `dist` folder. +3. Copy the `myextension` folder. +4. Navigate to the folder where you created your app. +5. Create a new folder called `webextensions`. +6. Paste the `myextension` folder into the `webextensions` folder you just created. This adds the extension files to the app. +7. Start Studio Pro with the following command-line parameters to tell it to use the extensions in the folder: `--enable-extension-development --webview-remote-debugging` These flags instruct Studio Pro to do the following: * Load extensions from the `webextensions` folder - * Enable web debugging tools which will be useful when developing your extension - -1. In Studio Pro, open the new app. + * Enable web debugging tools - You will see a new `Extensions` item in the top menu. +8. In Studio Pro, open the new app. You will see a new `Extensions` item in the top menu. {{% alert color="warning" %}} Extension names used in place of `myextension` must only contain digits, letters, dashes, and underscores. Extensions with an invalid name will not be loaded and will display an error. {{% /alert %}} -## Conclusion - -Using this guide we have: - -* Created a new app -* Downloaded a new extension from GitHub -* Built the extension and installed it in our app -* Tested our extension from within Studio Pro. - ## 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. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/dockable-pane-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/dockable-pane-api.md index 826c0a178e6..63d35b611f2 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/dockable-pane-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/dockable-pane-api.md @@ -7,7 +7,7 @@ weight: 10 ## Introduction -This guide explains how to create and manage a dockable pane using the web extensions API. A Dockable pane allows you to create a web view that can be docked and moved within the Studio Pro user interface. Examples of dockable panes in Studio Pro are: +This how-to describes how to create and manage a dockable pane using the web extensions API. A dockable pane allows you to create a web view that can be docked and moved within the Studio Pro user interface. Examples of dockable panes in Studio Pro are: * Marketplace * Errors @@ -16,11 +16,11 @@ This guide explains how to create and manage a dockable pane using the web exten ## Prerequisites -This guide uses the app created in [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/getting-started/). Please complete that how-to before starting this one. +This guide uses the app created in [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/getting-started/). Make sure to complete that how-to before starting this one. ## Creating a Dockable Pane -To open a dockable pane you must first register the dockable pane handle with the API. To do this, add a call to register the pane to the extension loaded method in the `src/main/index.ts`. +To open a dockable pane you must first register the dockable pane handle with the API. To do this, add a call to register the pane to the extension loaded method in the `src/main/index.ts`. Use the `paneHandle` you registered to interact with the dockable pane. ```typescript const paneHandle = await studioPro.ui.panes.register( @@ -34,9 +34,7 @@ To open a dockable pane you must first register the dockable pane handle with th }); ``` -Use the 'paneHandle' you registered to interact with the dockable pane. - -After adding this call the `loaded()` method looks like this: +After adding this call, the `loaded()` method looks like this: ```typescript {hl_lines=["11-19"]} async loaded() { @@ -81,9 +79,9 @@ After adding this call the `loaded()` method looks like this: ## Adding a Menu To Open the Dockable Pane -You will now add a menu that will open the pane when it is selected. +Add a menu that will open the pane when it is selected. -1. Add a new submenu to the existing `extensionsMenu.add()` method on line 10. +1. Add a new sub-menu to the existing `extensionsMenu.add()` method on line 10. ```typescript {linenos=table linenostart=10} // Add a menu item to the Extensions menu @@ -97,7 +95,7 @@ You will now add a menu that will open the pane when it is selected. }); ``` -1. Add lines to the `addEventListener()` call to handle opening the dockable pane once the menu has been selected, as follows: +2. Add lines to the `addEventListener()` call that will open the pane when the menu is selected. ```typescript // Open a tab when the menu item is clicked @@ -173,10 +171,10 @@ Your `loaded()` method should now look like this: ### Adding New Endpoint Handlers -You must now create a new web view endpoint where the user interface to be rendered within the pane is defined. You can use the existing endpoint and rename it to something more appropriate. +Create a new web view endpoint where you define the user interface that will be rendered within the pane. You can use and rename the existing endpoint. Follow the steps below: -1. Rename `ui/index.tsx` to `ui/tab.tsx` -1. Add the new endpoint file, `ui/dockablepane.tsx` by copying `ui/tab.tsx`. +1. Rename `ui/index.tsx` to `ui/tab.tsx`. +1. Add the new endpoint file, `ui/dockablepane.tsx`, by copying `ui/tab.tsx`. You must also alter the `vite.config.ts` and `manifest.json` files to bind to the correct endpoint, as described in the following sections: @@ -192,7 +190,7 @@ Replace the entry section of `vite.config.js` with the following: } ``` -This instructs vite that the tab endpoint is connected to `src/ui/tab.tsx` and the dockable pane endpoint is connected to `src/ui/dockablepane.tsx`. +This tells vite that the tab endpoint is connected to `src/ui/tab.tsx` and the dockable pane endpoint is connected to `src/ui/dockablepane.tsx`. `vite.config.js` should now look like this: @@ -219,9 +217,12 @@ export default defineConfig({ ### Altering `public/manifest.json` -You also need to instruct Studio Pro to load the endpoint that you just created. To do this, modify the manifest file `public/manifest.json`. +You also musr instruct Studio Pro to load the endpoint that you just created. To do this, modify the manifest file `public/manifest.json`. + +Alter the "ui" section by: -Alter the "ui" section by changing the `tab` endpoint and adding the `dockablepane` endpoint. +* Changing the `tab` endpoint +* Adding the `dockablepane` endpoint. ```typescript "ui": { @@ -248,17 +249,17 @@ The `manifest.json file` should now look like this: ## Closing the Dockable Pane -Now that you have registered a pane and can open, it would also be a good idea to close it. +Now that you have registered a pane and created a way to open it, it is important to provide a way to close it, too. -You will close your pane using a new menu item. +You will close your pane using a new menu item. Follow the steps below: -First add a new sub menu item to the menu on line 11. +1. Add a new sub-menu item to the menu on line 11. ```typescript {linenos=table linenostart=11} { menuId: "myextension.HideDockMenuItem", caption: "Hide dock pane" }, ``` -You must also alter the event handler for the new menu at the end of the loaded method: +2. Alter the event handler for the new menu at the end of the loaded method: ```typescript // Open a tab when the menu item is clicked @@ -337,13 +338,8 @@ The loaded method should now look like this: } ``` -## Conclusion - -You now have a new dockable pane with its own user interface which you can modify as you like. -You can also open and close the dockable pane from a menu. - ## 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. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/local-app-files-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/local-app-files-api.md index 3c104381a73..5c035c165c1 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/local-app-files-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/local-app-files-api.md @@ -7,18 +7,21 @@ weight: 20 ## Introduction -This how-to shows you how to interact with local application files from within an extension. It adds three new buttons to the tab and three new event handlers for saving, loading, and deleting a file called `HelloWorld.txt`. +This how-to describes how to interact with local application files from within an extension. In this example, you will: + +* Add three new buttons to a tab +* Add three new event handlers for saving, loading, and deleting a file called `HelloWorld.txt` ## Prerequisites -This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/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-10/getting-started/). Make sure to complete that how-to before starting this one. -## Adding Some Interactivity +## Adding Interactivity -First, you will add all the code. The changes will then be explained so that you can understand what the code does. +Implement the code described in the [Code Descriptions](#code-descriptions) section by following the steps below: 1. Open `src/ui/index.tsx`. -1. Replace the contents of the file with the following code: +2. Replace the contents of the file with the following code: ```typescript import { studioPro } from "@mendix/extensions-api"; @@ -59,13 +62,13 @@ createRoot(document.getElementById("root")!).render( ); ``` -## What Does the Code Do? +## Code Descriptions {#code-descriptions} The following sections explain the various parts of the code. ### saveFile -The `saveFile` callback calls the `putFile` API setting the filename to `HelloWorld.txt` and the content to `Hello world from a file!`. +The `saveFile` callback calls the `putFile` API. It sets the file name to `HelloWorld.txt` and the content to `Hello world from a file!`. ```typescript const saveFile = async () => { @@ -79,7 +82,7 @@ const saveFile = async () => { ### loadFile -The loadFile callback calls the getFile API requesting to load `HelloWorld.txt`. It then shows message box displaying the content of the file. +The loadFile callback calls the getFile API. It requests to load `HelloWorld.txt`, then shows a message box that displays the content of the file. ```typescript const loadFile = async () => { @@ -93,7 +96,7 @@ const loadFile = async () => { ### deleteFile -The deleteFile callback calls the deleteFile API requesting to delete `HelloWorld.txt` +The `deleteFile` callback calls the `deleteFile` API. It requests to delete `HelloWorld.txt`. ```typescript const deleteFile = async () => { @@ -102,7 +105,7 @@ const deleteFile = async () => { }; ``` -### Adding the Buttons +### Adding Buttons The final part of the code adds three new buttons which, when clicked, call the callbacks described above. @@ -120,19 +123,15 @@ createRoot(document.getElementById("root")!).render( ); ``` -## Some Restrictions - -The App files API allows you to modify files within your application's folder. It will not: - -* serve restricted files such as the `.mpr` file or the contents of some folders such as the `.git` folder. -* allow access to files outside of the app folder. +## Restrictions -## Conclusion +The app files API allows you to modify files within your application's folder. It will not: -You can now create and extension which save, load, and delete files within the app folder. +* Serve restricted files such as the `.mpr` file, or the contents of some folders, such as the `.git` folder +* Allow access to files outside of the app folder ## 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. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/menu-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/menu-api.md index 6a95549b04b..fcf8197af56 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/menu-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/menu-api.md @@ -13,14 +13,29 @@ This how-to shows you how to create both a simple menu item and a menu item with This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/getting-started/). Please complete that how-to before starting this one. -## Creating a Simple Menu +## Menu Properties + +A menu has the following properties: + +| 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`
(default: `false`) | Adds a visual separator before the item | +| `hasSeparatorAfter`
(default: `false`) | Adds a visual separator after the item | +| `enabled`
(default: `true`) | Indicates that the menu item notifies the listener when clicked | -In this section, you will add a simple menu to your extension. +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/grouped_menus.png" width="200" >}} -The code below will: +## 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 +* 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: @@ -57,43 +72,28 @@ class Main implements IComponent { export const component: IComponent = new Main(); ``` -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. - -It starts listening to the `menuItemActivated` endpoint which will notify the extension when **My First Menu** is clicked. +When this code is added, it does the following: -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" >}} +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/my_first_menu.png" width="200" >}} -## 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" >}} - -## Creating a Menu with Submenus +## Creating a Menu with Sub-menus You can also have a number of submenus that branch out your menu. -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, studioPro } from "@mendix/extensions-api"; @@ -143,21 +143,21 @@ class Main implements IComponent { export const component: IComponent = new Main(); ``` -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" >}} +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/child_menus.png" width="400" >}} -## 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. {{% /alert %}} -You can test it by the following code as the contents of `src/main/index.ts`. +You can test it by the following code as the contents of `src/main/index.ts`. ```typescript import { IComponent, Menu, studioPro } from "@mendix/extensions-api"; @@ -194,15 +194,10 @@ export const component: IComponent = new Main(); The disabled state is shown in the image below. -{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/disabled_menu.png" >}} - -## 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. +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/disabled_menu.png" width="200" >}} ## 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. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/messagebox-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/messagebox-api.md index a5a1aebb745..3137c47fe60 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/messagebox-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/messagebox-api.md @@ -7,35 +7,23 @@ weight: 50 ## Introduction -This how-to shows you how to show a message box to the Studio Pro user. +This how-to describes how to show a message box to a user. In this example, you will create three menu items that will display a dialog with text. ## Prerequisites -This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/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-10/getting-started/). Make sure to complete that how-to before starting this one. ## Showing a Message Box -Firstly, you need to create a menu which will display a dialog with text. This is done in the `loaded` event in `Main`. +Create a menu that will display a dialog with text. This is done in the `loaded` method of your main entry point (`src/main/index.ts`). For more information on how to do this, see [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/menu-api/). -You can learn how to do that in [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/menu-api/). - -In this example you create three menu items: - -* Show Info -* Show Error -* Show Warning - -You then need to add event listeners to receive and act upon the notifications generated by the menu items. Here the listener events show a different message box, depending on which menu item is selected. The message has the following format: - -`messageBoxApi.show(, , )` - -where +Add event listeners to receive and act upon the notifications generated by the menu items. The listener events show a different message box, depending on which menu item is selected. The message has the format `messageBoxApi.show(, , )`, where: * `` is the type of message, indicated in the pane title and indicated by an icon. Values are "information" {{% icon name="info-circle" color="blue" %}}, "warning" {{% icon name="alert-triangle" color="yellow" %}}, and "error" {{% icon name="remove-circle" color="red" %}}. * `` is the message to display. -* `` is an optional extended message which is displayed in an expandable area which is initially collapsed. +* `` is an optional extended message which is displayed in an expandable area that is initially collapsed. -The full typescript file to implement these three menu items and message boxes is as follows. +The full TypeScript file (`src/main/index.ts`) to implement these three menu items and message boxes is as follows: ```typescript import { IComponent, Menu, studioPro } from "@mendix/extensions-api"; @@ -85,16 +73,12 @@ class Main implements IComponent { export const component: IComponent = new Main(); ``` -For example, the **Show Info** menu item will display the following message box. - -{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/messageBoxes/info.png" >}} - -## Conclusion +For example, the **Show Info** menu item will display the following message box: -You have seen how to implement message boxes triggered by menu items. +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/messageBoxes/info.png" width="400" >}} ## 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. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/model-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/model-api.md index bf635357d69..78ec5ad0516 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/model-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/model-api.md @@ -7,12 +7,7 @@ weight: 40 ## Introduction -The Model Access API allow access to the Mendix model. This how-to provides guidance on using the Model Access API. It is split into the following sections: - -* [Using the Model Access API](#using-api) -* [Reading the Units Info and Loading Units](#units-info-load) -* [Reading the Unit Content](#read) -* [Modifying the Unit Content](#modify) +This how-to describes how to use the Model Access API, which allows access to the Mendix model. ## Using the Model Access API {#using-api} @@ -32,7 +27,7 @@ const { pages, domainModels } = studioPro.app.model; ## Reading the Units Info and Loading Units {#units-info-load} -A unit is a Mendix document (for example, a page or a domain model) containing elements. Each element is within a container element and may contain other elements. An element is part of a Mendix model and all elements together form the logic of the model. For more information see [Mendix Metamodel](/apidocs-mxsdk/mxsdk/mendix-metamodel/). +A unit is a Mendix document (for example, a page or a domain model) containing elements. Each element resides within a container element and can itself contain other elements. Together, these elements form the logic of a Mendix model. For more information, see [Mendix Metamodel](/apidocs-mxsdk/mxsdk/mendix-metamodel/). Each component, for example pages (`studioPro.app.model.pages`) exposes the units it is responsible for. You can only access all the content of a unit once you have loaded the unit info for that unit. @@ -57,13 +52,15 @@ A unit can be loaded by supplying a function, `fn` to `component.loadAll(fn)`. T Loading units is a resource intensive process. Only load units when you need them. {{% /alert %}} -For example, the following snippet loads the `domainModel` for the module named `MyFirstModule`: +## Examples + +The following snippet loads the `domainModel` for the module named `MyFirstModule`: ```ts const [domainModel] = await domainModels.loadAll((info: Primitives.UnitInfo) => info.moduleName === 'MyFirstModule'); ``` -And this example snippet loads the page named `Home_Web` in the module named `MyFirstModule`: +The next snippet loads the page named `Home_Web` in the module named `MyFirstModule`: ```ts const [page] = await pages.loadAll((info: Primitives.UnitInfo) => info.moduleName === 'MyFirstModule' && info.name === 'Home_Web') @@ -97,12 +94,8 @@ newEntity.documentation = "New documentation"; await domainModels.save(domainModel); ``` -## Conclusion - -You now know how to interact with units and elements in the Mendix model. - ## 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. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/tab-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/tab-api.md index 3be1c9038e3..9383babe7d8 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/tab-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-10/extensibility-api/web/web-extensions-howtos/tab-api.md @@ -7,29 +7,32 @@ weight: 60 ## Introduction -This how-to shows you how to open a tab in Studio Pro from an extension. This tab will contain your web content. +This how-to describes how to open a tab in Studio Pro from an extension. This tab will contain your web content. ## Prerequisites -This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/getting-started/). Please complete that how-to before starting this one. You should also be familiar with creating menus as described in [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/menu-api/). +Before starting this how-to, make sure you have completed the following prerequisites: + +* This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/getting-started/). Complete that how-to before starting this one. +* Make sure you are familiar with creating menus as described in [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/menu-api/). ## Opening a Tab -Firstly, create a menu item to open the tab. This is done inside the `loaded` event in `Main`. For more information see [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/menu-api/). +Create a menu item to open the tab. This is done inside the `loaded` event in `Main`, as described below. For more information. see [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-10/menu-api/). -In a listener event called `menuItemActivated` the `studioPro.ui.tabs.open(, )` call opens a new tab where: +In a listener event called `menuItemActivated`, the `studioPro.ui.tabs.open(, )` call opens a new tab where: -* `` is an object containing the `title` of the tab, which will be shown in the title bar of your tab in Studio Pro. +* `` is an object containing the `title` of the tab, which will be shown in the title bar of your tab in Studio Pro * `` is an object containing two required properties: - * `componentName` which is the name of the extension prefixed with "extension/". For example "extension/myextension" in the following example. - * `uiEntryPoint` which is the name mapped from the `manifest.json` file. See below for examples with multiple tabs. + * `componentName` – the name of the extension prefixed with "extension/"; for example,"extension/myextension" in the following example + * `uiEntryPoint` – the name mapped from the `manifest.json` file {{% alert color="info" %}} -Whenever the tabs API `open` method is called, the `TabHandle` returned must be tracked by the extension so that it can be closed later by calling the `close` method. +Whenever the tabs API `open` method is called, the `TabHandle` returned must be tracked by the extension so it can be closed later by calling the `close` method. {{% /alert %}} -An example of the class `Main` to open a tab called **My Extension Tab** looks similar to the following: +To open a tab called *My Extension Tab*, add the following code to the main entry point: ```typescript import { IComponent, studioPro, TabHandle } from "@mendix/extensions-api"; @@ -88,11 +91,9 @@ export const component: IComponent = new Main(); ## Filling the Tabs With Content -In the previous example, the `uiEntryPoint` property of the `` object had the value "tab". This value must match the one from the manifest. - -If you want to have multiple tabs in your extension, you need to structure the folders and set up the manifest file correctly. +In the previous example, the `uiEntryPoint` property of the `` object had the value `tab`. This value must match the one from the manifest. -To do this, follow these steps: +If you want multiple tabs in your extension, you need to structure the folders and set up the manifest file correctly. To do this, follow these steps: 1. Add a new method `createTabSpec` in your `Main` class. @@ -108,9 +109,9 @@ To do this, follow these steps: } ``` -1. Add three folders inside the `ui` folder, one for each tab you want to display contents for. -1. Create an `index.tsx` file in each folder. -1. Put the following code in each `index.tsx` file (this example is for **tab3**): +2. Add three folders inside the `ui` folder, one for each tab you want to display contents for. +3. Create an `index.tsx` file in each folder. +4. Put the following code in each `index.tsx` file (this example is for **tab3**): ```typescript import { StrictMode } from "react"; @@ -127,7 +128,7 @@ To do this, follow these steps: {{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/tabs/ui_folder_structure.png" >}} -1. Create listener events in the `Main` class to open each of the three tabs. The `Main` class will then look like this: +5. Create listener events in the `Main` class to open each of the three tabs. The `Main` class will then look like this: ```typescript import { IComponent, studioPro, TabInfo, UISpec } from "@mendix/extensions-api"; @@ -179,7 +180,7 @@ To do this, follow these steps: export const component: IComponent = new Main(); ``` -1. Ensure the tabs are added to the `manifest.json` file. Here is an example of three tabs under the `ui` property. +6. Ensure the tabs are added to the `manifest.json` file. Below is an example of three tabs under the `ui` property. ```json { @@ -196,7 +197,7 @@ To do this, follow these steps: } ``` -1. Update `vite.config` to match the manifest with an entry for each tab. For example: +7. Update `vite.config` to match the manifest with an entry for each tab. For example: ```typescript import { defineConfig, ResolvedConfig, UserConfig } from "vite"; @@ -220,14 +221,10 @@ To do this, follow these steps: } satisfies UserConfig); ``` -After building and installing the extension in our Studio Pro app, each tab will display the content specified in the related `index.tsx` file. - -## Conclusion - -You now know how to create tabs and populate them with content. +After building and installing the extension in your Studio Pro app, each tab will display the content specified in the related `index.tsx` file. ## 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.