diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/_index.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/_index.md index 7748418ea88..ebb151802c9 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/_index.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/_index.md @@ -51,3 +51,6 @@ Below is a list of how-tos for you to begin with: * [How to Exchange Information Between Active Views](/apidocs-mxsdk/apidocs/web-extensibility-api-11/message-passing-api/) * [How to Show Version Control Information](/apidocs-mxsdk/apidocs/web-extensibility-api-11/version-control-api/) * [How to Introduce a New Document Type](/apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/) +* [How to Listen for Connection Changes](/apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-controller-api/) +* [How to Access Runtime Constants](/apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-configuration-api/) +* [How to Use Extension Permissions in Overview Pane](/apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions) diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/permissions.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/permissions.md new file mode 100644 index 00000000000..f8e886ba4f4 --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/permissions.md @@ -0,0 +1,62 @@ +--- +title: "Extension Permissions in Overview Pane" +linktitle: "Extension Permissions" +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions/ +--- + +## Introduction + +This how-to describes how the permission system works for web extensions in Studio Pro. Permissions allow extensions to request access to sensitive APIs or data that require explicit user consent. + +## How Permissions Work + +Web extensions can request permissions to access sensitive functionalities. The permission system follows these principles: + +* **Opt-in by default** — Extensions cannot access protected APIs unless they explicitly request the permission and the user grants it +* **User control** — Users decide which permissions to grant through the Extensions Overview pane in Studio Pro +* **Per-project settings** — Permission grants are stored per project so users can have different permission settings for the same extension across different projects + +## Requesting Permissions + +To request a permission, declare it in your extension's `package.json` file under the `mendix.permissions` object: + +```json +{ + "mendixComponent": { + "entryPoints": { + "main": "main.js", + "ui": { + "tab": "tab.js" + } + }, + "permissions": { + "runtime-configuration-private": true + } + } +} +``` + +Setting a permission to **true** indicates that your extension requests this permission. The user must grant it before your extension can use the protected functionality. + +## Granting Permissions (User Flow) + +When a user installs an extension that requests permissions, they can manage those permissions through the Extensions Overview pane. Follow the steps below: + +1. Open Studio Pro and load a project with the extension installed. +2. Go to **View** > **Extensions Overview** to open the Extensions Overview pane. +3. Find the extension in the list. Under the extension details, the **Permissions** section displays the requested permissions. +4. Check or uncheck the checkbox next to each permission to grant or revoke access. + +## Available Permissions + +Currently, the following permissions are available for web extensions: + +| Permission | Description | +|------------|-------------| +| `runtime-configuration-private` | Allows the extension to access the values of private constants from the active runtime configuration. Without this permission, private constants are returned with `isPrivate: true` and no value. | + +## 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 appreciated. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/runtime-configuration-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/runtime-configuration-api.md new file mode 100644 index 00000000000..b88b7147e6b --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/runtime-configuration-api.md @@ -0,0 +1,120 @@ +--- +title: "Access Runtime Constants Using Web API" +linktitle: "Runtime Constants" +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-configuration-api/ +--- + +## Introduction + +This how-to describes how to create a simple menu that retrieves and displays the runtime constants from the active configuration in a message box. + +## Prerequisites + +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-11/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-11/menu-api/) and message boxes as described in [Show a Message Box Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/messagebox-api/). + +## Set Up the Extension Structure + +Set up the extension structure by following the steps below: + +1. Create a menu that will display the runtime constants in the `loaded` method in the main entry point (`src/main/index.ts`). This can be done by following the steps in [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu-api/). +2. Replace your `src/main/index.ts` file with the following: + +```typescript +import { IComponent, Menu, getStudioProApi } from "@mendix/extensions-api"; + +export const component: IComponent = { + async loaded(componentContext) { + const studioPro = getStudioProApi(componentContext); + const menuApi = studioPro.ui.extensionsMenu; + const runtimeConfigApi = studioPro.runtime.configuration; + const messageBoxApi = studioPro.ui.messageBoxes; + + const menuId = "show-constants-menu"; + const caption = "Show Runtime Constants"; + + // Get and show the constants when the menu item is clicked + const action = async () => { + const constants = await runtimeConfigApi.getConstants(); + + if (constants.length === 0) { + await messageBoxApi.show("info", "No constants found in the active configuration."); + return; + } + + const accessibleConstants = constants.filter(c => c.isPrivate === false); + const privateConstants = constants.filter(c => c.isPrivate === true); + + let message = ""; + + if (accessibleConstants.length > 0) { + message += "Accessible Constants:\n"; + message += accessibleConstants.map(c => ` ${c.constantName}: ${c.value}`).join("\n"); + } + + if (privateConstants.length > 0) { + message += `\n\n${privateConstants.length} private constant(s) not accessible.`; + } + + await messageBoxApi.show("info", `Runtime Constants:\n\n${message}`); + }; + + const menu: Menu = { caption, menuId, action }; + + await menuApi.add(menu); + } +}; +``` + +In this example, you create one menu item that will show a message box with the runtime constants from the active configuration. + +The code uses the: + +* `menuApi` from `studioPro.ui.extensionsMenu` to allow you to use the menu API +* `messageBoxApi` from `studioPro.ui.messageBoxes` to show a dialog +* `runtimeConfigApi` from studioPro.runtime.configuration to retrieve the runtime constants + +{{% alert color="info" %}} The function is `async` in order for you to use `await` when executing the preview action. +{{% /alert %}} + +The `getConstants()` function returns an array of constant objects, each with the following properties: +* `isPrivate` – a boolean indicating whether the constant value is hidden (true) or accessible (false) +* `constantName` – the fully qualified name of the constant (for example, `MyModule.MyConstant`) +* `value` – the constant value as a string (only present when `isPrivate` is false) + +## Accessing Private Constants + +By default, private constants are not accessible and will have `isPrivate` set to true with no value. To access private constant values, your extension must request the `runtime-configuration-private` permission. + +Add the permission to your extension's `package.json` after the entry points: + +```json +{ + "mendixComponent": { + "entryPoints": { + "main": "main.js", + "ui": { + "tab": "tab.js" + } + }, + "permissions": { + "runtime-configuration-private": true + } + } +} + +``` + +You have to set the permission to true if you want the permission to appear in the Extensions Overview pane. + +When a user installs your extension, they can grant this permission through the Extensions Overview pane (**View** > **Extensions**) in Studio Pro. Once granted, private constants will be returned with `isPrivate` set to false and their value included. + +You can read more about permissions in [Extension Permission](/apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions/). + +## 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 appreciated. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/runtime-controller-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/runtime-controller-api.md new file mode 100644 index 00000000000..bb1e0b2fa4e --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/runtime-controller-api.md @@ -0,0 +1,66 @@ +--- +title: "Listen for Connection Changes" +linktitle: "Runtime Controller" +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-controller-api/ +--- + +## Introduction + +This how-to describes how to create a simple menu that displays when the connection changed in a message box. + +## Prerequisites + +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-11/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-11/menu-api/) and message boxes as described in [Show a Message Box Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/messagebox-api/). +* Your app must be running locally in Studio Pro to use the Runtime Controller API. + +## Listening for Connection Changes + +You can listen for runtime connection state changes to know when the app starts or stops running. To do this, follow the steps below: + +1. Add an event listener to respond when the connection state changes. +2. Replace your `src/main/index.ts` file with the following: + +```typescript +import { IComponent, getStudioProApi } from "@mendix/extensions-api"; + +export const component: IComponent = { + async loaded(componentContext) { + const studioPro = getStudioProApi(componentContext); + const runtimeControllerApi = studioPro.runtime.controller; + const messageBoxApi = studioPro.ui.messageBoxes; + + // Listen for connection state changes + runtimeControllerApi.addEventListener("connectionChanged", (args) => { + messageBoxApi.show( + "info", + `Runtime connection: ${args.isConnected ? "Connected" : "Disconnected"}` + ); + }); + } +}; +``` + +The code uses the: + +* `menuApi` from `studioPro.ui.extensionsMenu` to allow you to use the menu API +* `messageBoxApi` from `studioPro.ui.messageBoxes` to show a dialog +* `runtimeControllerApi` from `studioPro.runtime.controller` to check if the connection changed. + +{{% alert color="info" %}} The function is `async` in order for you to use `await` when executing the preview action. +{{% /alert %}} + +The `connectionChanged` event provides an object with: + +* `isConnected` – a boolean indicating whether the runtime is currently connected (true) or disconnected (false) + +{{% alert color="info" %}} The event only detects when the runtime connects or disconnects. It cannot be used to determine when the runtime is completely initialized. +{{% /alert %}} + +## 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 appreciated. diff --git a/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md b/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md index c40fe1c4cfa..21afcf8e9ad 100644 --- a/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md +++ b/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md @@ -8,6 +8,12 @@ numberless_headings: true These release notes cover changes to the [Extensibility API for Web Developers](/apidocs-mxsdk/apidocs/extensibility-api/). +## Version 11.9.0 + +* We introduced a new Runtime Configuration API under `studioPro.runtime.configuration`, which allows you to retrieve runtime constants from the active configuration. For more information, see [Access Runtime Constants Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-configuration-api/). +* We introduced a new Runtime Controller API under `studioPro.runtime.controller`, which allows you to listen for runtime connection state changes to detect when your app starts or stops running. For more information, see [Listen for Connection Changes](/apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-controller-api/). +* We introduced a permission system for web extensions. Extensions can now request access to sensitive APIs and users can grant or revoke permissions through the Extensions Overview pane. For more information, see [Extension Permissions](/apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions/). + ## Version 11.8.0 * We introduced a change in the [Progress Dialog API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/dialog-api/), so when the progress dialog only has one step, only the progress bar is shown.