|
| 1 | +--- |
| 2 | +title: "Access Runtime Constants Using Web API" |
| 3 | +linktitle: "Runtime Constants" |
| 4 | +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-configuration-api/ |
| 5 | +--- |
| 6 | + |
| 7 | +## Introduction |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +{{% alert color="info" %}} |
| 12 | +Access to runtime constants using the web API was introduced in version 11.9.0. |
| 13 | +{{% /alert %}} |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +Before starting this how-to, make sure you have completed the following prerequisites: |
| 18 | + |
| 19 | +* 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. |
| 20 | +* 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/). |
| 21 | + |
| 22 | +## Set Up the Extension Structure |
| 23 | + |
| 24 | +Set up the extension structure by following the steps below: |
| 25 | + |
| 26 | +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/). |
| 27 | +2. Replace the contents of your `src/main/index.ts` file with the following: |
| 28 | + |
| 29 | +```typescript |
| 30 | +import { IComponent, Menu, getStudioProApi } from "@mendix/extensions-api"; |
| 31 | + |
| 32 | +export const component: IComponent = { |
| 33 | + async loaded(componentContext) { |
| 34 | + const studioPro = getStudioProApi(componentContext); |
| 35 | + const menuApi = studioPro.ui.extensionsMenu; |
| 36 | + const runtimeConfigApi = studioPro.runtime.configuration; |
| 37 | + const messageBoxApi = studioPro.ui.messageBoxes; |
| 38 | + |
| 39 | + const menuId = "show-constants-menu"; |
| 40 | + const caption = "Show Runtime Constants"; |
| 41 | + |
| 42 | + // Get and show the constants when the menu item is clicked |
| 43 | + const action = async () => { |
| 44 | + const constants = await runtimeConfigApi.getConstants(); |
| 45 | + |
| 46 | + if (constants.length === 0) { |
| 47 | + await messageBoxApi.show("info", "No constants found in the active configuration."); |
| 48 | + return; |
| 49 | + } |
| 50 | + |
| 51 | + const accessibleConstants = constants.filter(c => c.isPrivate === false); |
| 52 | + const privateConstants = constants.filter(c => c.isPrivate === true); |
| 53 | + |
| 54 | + let message = ""; |
| 55 | + |
| 56 | + if (accessibleConstants.length > 0) { |
| 57 | + message += "Accessible Constants:\n"; |
| 58 | + message += accessibleConstants.map(c => ` ${c.constantName}: ${c.value}`).join("\n"); |
| 59 | + } |
| 60 | + |
| 61 | + if (privateConstants.length > 0) { |
| 62 | + message += `\n\n${privateConstants.length} private constant(s) not accessible.`; |
| 63 | + } |
| 64 | + |
| 65 | + await messageBoxApi.show("info", `Runtime Constants:\n\n${message}`); |
| 66 | + }; |
| 67 | + |
| 68 | + const menu: Menu = { caption, menuId, action }; |
| 69 | + |
| 70 | + await menuApi.add(menu); |
| 71 | + } |
| 72 | +}; |
| 73 | +``` |
| 74 | + |
| 75 | +In this example, you create one menu item that will show a message box with the runtime constants from the active configuration. |
| 76 | + |
| 77 | +The code uses the: |
| 78 | + |
| 79 | +* `menuApi` from `studioPro.ui.extensionsMenu` to allow you to use the menu API |
| 80 | +* `messageBoxApi` from `studioPro.ui.messageBoxes` to show a dialog |
| 81 | +* `runtimeConfigApi` from studioPro.runtime.configuration to retrieve the runtime constants |
| 82 | + |
| 83 | +{{% alert color="info" %}} The function is `async` in order for you to use `await` when executing the preview action. |
| 84 | +{{% /alert %}} |
| 85 | + |
| 86 | +The `getConstants()` function returns an array of constant objects, each with the following properties: |
| 87 | + |
| 88 | +* `isPrivate` – a boolean indicating whether the constant value is hidden (true) or accessible (false) |
| 89 | +* `constantName` – the fully qualified name of the constant (for example, `MyModule.MyConstant`) |
| 90 | +* `value` – the constant value as a string (only present when `isPrivate` is false) |
| 91 | + |
| 92 | +## Accessing Private Constants |
| 93 | + |
| 94 | +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. |
| 95 | + |
| 96 | +Add the permission to your extension's `package.json` after the entry points: |
| 97 | + |
| 98 | +```json |
| 99 | +{ |
| 100 | + "mendixComponent": { |
| 101 | + "entryPoints": { |
| 102 | + "main": "main.js", |
| 103 | + "ui": { |
| 104 | + "tab": "tab.js" |
| 105 | + } |
| 106 | + }, |
| 107 | + "permissions": { |
| 108 | + "runtime-configuration-private": true |
| 109 | + } |
| 110 | + } |
| 111 | +} |
| 112 | + |
| 113 | +``` |
| 114 | + |
| 115 | +You have to set the permission to true if you want the permission to appear in the Extensions Overview pane. |
| 116 | + |
| 117 | +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. |
| 118 | + |
| 119 | +You can read more about permissions in [Extension Permissions in Overview Pane](/apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions/). |
| 120 | + |
| 121 | +## Extensibility Feedback |
| 122 | + |
| 123 | +If you would like to provide additional feedback, you can complete a small [survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback). |
| 124 | + |
| 125 | +Any feedback is appreciated. |
0 commit comments