diff --git a/.claude/scripts/resolve-doc-url.sh b/.claude/scripts/resolve-doc-url.sh index 4af6c42229e..80951fc244f 100644 --- a/.claude/scripts/resolve-doc-url.sh +++ b/.claude/scripts/resolve-doc-url.sh @@ -1,6 +1,6 @@ #!/bin/bash # Resolve a documentation URL to its source markdown file -# Usage: resolve-doc-url.sh "/path/to/page/" +# Usage: resolve-doc-url.sh "/url/path/" if [ -z "$1" ]; then echo "Usage: resolve-doc-url.sh " diff --git a/.claude/skills/docs-alt-text/SKILL.md b/.claude/skills/docs-alt-text/SKILL.md new file mode 100644 index 00000000000..efe9b575706 --- /dev/null +++ b/.claude/skills/docs-alt-text/SKILL.md @@ -0,0 +1,71 @@ +--- +name: docs-alt-text +description: Generates W3C-compliant alt text for images in documentation pages. Analyzes each image's purpose and adds descriptive alt text for informative images or empty alt for decorative images, improving accessibility and SEO. +user-invocable: true +disable-model-invocation: false +--- + +> **Accessibility skill:** Generates alt text following W3C/WCAG 2.1 guidelines. Analyzes actual image content plus context to create concise, meaningful descriptions. + +## Workflow + +Follow this order for each image: + +1. **STEP 1 - View the image file** (REQUIRED) + - Extract image src path from figure shortcode + - Convert path: `src="/attachments/path/file.png"` → `static/attachments/path/file.png` + - Use Read tool to view the actual image + - Understand what the image shows BEFORE reading context + +2. **STEP 2 - Read surrounding context** + - Read the heading, preceding/following text, list item, or numbered step + - Understand the image's purpose within the documentation + - Consider if context + image together make the image informative or decorative + +3. **STEP 3 - Determine if informative or decorative** + - **Technical docs assumption:** Images are informative unless obviously decorative + - **Informative:** Images that convey information → write descriptive alt text + - **Decorative:** Images where the information is already given in adjacent text, or pure visual styling with no informational value → use `alt=""` + +4. **STEP 4 - Generate alt text** + - **If decorative, use `alt=""`.** Never omit the alt attribute entirely. + - **If informative, generate descriptive alt text:** + - Focus on the information the image communicates, not what it looks like + - Give the most concise description possible + - Maximum 30 words (flag complex images needing longer descriptions for body text) + - Don't include "screenshot of", "image of", or "picture of" (screen readers already announce it's an image) + - Use Mendix terminology + - Avoid redundancy with nearby text + - **Based on surrounding context:** + - In a procedure: emphasize the action/element relevant to the step (e.g., "Download button in Registration dialog") + - Showing UI elements: name the relevant elements (e.g., "Properties pane") + - Showing structure or relationships: describe what entities/components are connected (e.g., "Domain model with Customer and Order entities connected by one-to-many association") + - Showing logic or process flow: describe what the flow accomplishes (e.g., "Microflow that retrieves FileDocument list and updates encryption keys") + +5. **STEP 5 - Edit the figure shortcode** + - Use Edit tool to add/update only the `alt` attribute + - Preserve all other attributes: `class`, `width`, `max-width`, `link` + - Maintain exact indentation and spacing + +## Special Cases + +- **Images in numbered lists:** Common in procedures—describe the procedural step shown +- **Before/after sequences:** Describe what changed or the state shown +- **Existing alt text:** May update if it's empty, generic, or poor quality (e.g., `alt=""`, `alt="button"`, `alt="before"`) +- **File format icons:** Use format name (e.g., "PDF", "ZIP", "Word document") +- **Complex diagrams:** If needs >30 words, flag to user and suggest adding description to body text + +## What NOT to do + +- Don't modify `src` path or attributes other than `alt` +- Don't change surrounding text or document structure +- Don't process images outside the determined scope +- Don't generate alt text based solely on filename—always view the image first + +## After Processing + +Report summary: +- How many images processed +- How many updated + +**Always suggest user review:** Recommend that the user review the images themselves to confirm alt text accuracy, as AI-generated descriptions may miss important nuances or context-specific details. diff --git a/.claude/skills/docs-polish/SKILL.md b/.claude/skills/docs-polish/SKILL.md index e1caba5f525..2a7cdc71e95 100644 --- a/.claude/skills/docs-polish/SKILL.md +++ b/.claude/skills/docs-polish/SKILL.md @@ -1,18 +1,18 @@ --- name: docs-polish -description: Proofreads a single documentation page and improves clarity, readability, and word choice without changing meaning or reorganizing structure. Simplifies complex sentences, applies style guide standards, and converts passive voice to active voice. Use when the user wants to polish, improve language and clarity, make more readable, check style guide compliance, or clean up documentation while preserving its structure. +description: Applies style guide standards to a documentation page without changing meaning or reorganizing structure. This includes fixing grammar, improving clarity and readability, simplifying complex sentences, using active voice, and standardizing terminology and formatting. Use when the user wants to polish, check style guide compliance, improve language, or clean up documentation while preserving its structure. user-invocable: true disable-model-invocation: false --- -> **Skill progression:** This does everything `/docs-proofread` does plus clarity improvements and style guide enforcement. If only grammar and spelling fixes are needed, use `/docs-proofread`. For deeper reorganization, suggest `/docs-enhance`. +> **Skill progression:** This does everything `/docs-proofread` does plus style guide enforcement including clarity improvements. If only grammar and spelling fixes are needed, use `/docs-proofread`. For deeper reorganization, suggest `/docs-enhance`. If missing alt text is found, suggest `/docs-alt-text`. Improve clarity and readability without changing meaning, structure, or paragraph order: **docs-polish should**: * Read Mendix style guides first (in parallel): `grammar-formatting.md`, `terminology.md`, and `product-naming-guide.md` from `/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/` * Fix all spelling, grammar, and punctuation errors -* Add missing alt text to images (use simple, factual descriptions) +* Check all figure shortcodes for missing alt text. If the alt text parameter is missing, insert `alt=""` as a placeholder. * Ensure required front matter fields are present (title, url, description) and make descriptions concise and action-oriented * Fix broken Markdown syntax * Fix capitalization and terminology inconsistencies @@ -24,10 +24,15 @@ Improve clarity and readability without changing meaning, structure, or paragrap * Apply Mendix style guide standards (overrides the Microsoft Writing Style Guide) * Apply Microsoft Writing Style Guide standards, unless they conflict with the Mendix style guide standards +**After completing edits**: +* Report what was changed in a concise summary +* If any images were found with missing or empty alt text, state "I found [N] image(s) with missing alt text. Consider running `/docs-alt-text` to generate alt text." + **docs-polish should NOT**: * Move paragraphs or restructure sections (that's `/docs-enhance`) * Change technical meaning or accuracy * Significantly increase document length +* Generate alt text for images * Change command syntax, code identifiers, variable names, placeholders, or any other text that appears in code formatting (inline backticks or code blocks). Code-formatted text represents literal technical content that must remain unchanged. If you notice an issue with code-formatted text, flag it in the chat but don't edit it directly. Every edit should serve a clear purpose in making the text easier to read, scan, and understand. diff --git a/CLAUDE.md b/CLAUDE.md index acd302592d0..f8f16033de0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,7 +81,7 @@ Before creating a new file, use Glob to explore the directory structure and unde * **Headings** – H1 is generated from the front‑matter title. Subsequent headings increment by one level at a time. Don't use bold or italics as a replacement for headings. Use title case. Never start headings with numerals. * **Lists and tables** – Bullet lists use asterisks; ordered lists use numbers followed by a period. If there are more than three data points per item, use a table instead. Use the same syntax and structure for all list items in a given list. Use complete sentences to introduce lists and tables, not partial sentences completed with the list items. * **Indentation** – Four spaces for sub-lists and nested content. Alerts in lists are an exception: don't indent alert lines but do omit preceding blank line. -* **Links** – Use absolute paths starting with a leading slash (`/deployment/`). Use descriptive link text such as the page title, not "click here". To link to a heading, add an anchor ID (`{#anchor-id}`) next to the heading and use that ID in the URL (for example, `[Section title](/path/to/page#anchor-id)` to link to a heading in another page or `[Section title](#anchor-id)` to link to a heading in the same page). +* **Links** – Link using the target page's `url` front matter field, not its file system path (e.g., `/deployment/` from front matter, not `content/en/docs/deployment/_index.md`). Use descriptive link text such as the page title, not "click here". To link to a heading, add an anchor ID (`{#anchor-id}`) next to the heading and use that ID in the URL (for example, `[Prerequisites](/deployment/mendix-cloud/#prerequisites)` to link to a heading in another page or `[Prerequisites](#prerequisites)` to link to a heading in the same page). * **Images** – Always include `alt` text (or `alt=""` if decorative). Use W3C guidelines. Reference images with the `figure` shortcode. * **Code** – Use fenced code blocks with language specifier. Do not modify text that appears in code formatting (inline backticks or code blocks), even to fix apparent inconsistencies or apply naming conventions. @@ -105,18 +105,18 @@ Call tools in parallel for independent operations (reading multiple files, multi ### Tool Selection +* **Helper Scripts** + * For URL resolution, use `bash .claude/scripts/resolve-doc-url.sh` instead of spawning agents. This resolves documentation URLs (e.g., `/community-tools/contribute-to-mendix-docs/`) to their source Markdown files and ensures Grep uses efficient flags consistently. * **Read** – Use to view specific files you know the path to * **Edit** – Use to modify existing files with targeted changes * **Glob** – Use to find files by pattern (e.g., `*.md`, `**/*config*`) * **Grep** – Use to search file contents for specific text or patterns * **Write** – Use only for creating new files (prefer Edit for existing files) -* **Helper Scripts** – Use `.claude/scripts/resolve-doc-url.sh` to resolve documentation URLs (e.g., `/path/to/page/`) to their source markdown files. This is faster and more token-efficient than using Grep to search front matter. ### Cross-Reference Verification When following or verifying documentation links: -* Use `.claude/scripts/resolve-doc-url.sh "/path/to/page/"` to quickly find the source file for a URL -* This is more efficient than Grep for URL-to-file lookups +* Use `bash .claude/scripts/resolve-doc-url.sh "/url/path/"` to quickly find the source file for a URL When modifying URLs or anchor IDs: 1. Use Grep to search for the old URL/anchor across all documentation files diff --git a/branch-cleanup-timestamp.txt b/branch-cleanup-timestamp.txt index d2e1b55ccff..8c6d339efbd 100644 --- a/branch-cleanup-timestamp.txt +++ b/branch-cleanup-timestamp.txt @@ -1 +1 @@ -Last scan for stale merged branches: 2026-04-02 00:41:32 CEST (UTC+02:00) +Last scan for stale merged branches: 2026-05-02 00:53:35 CEST (UTC+02:00) diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/packaging-your-extension.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/packaging-your-extension.md index 459e68830b1..7b937ddff98 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/packaging-your-extension.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/packaging-your-extension.md @@ -1,35 +1,36 @@ --- title: "Packaging Your Extension" -url: /apidocs-mxsdk/apidocs/extensibility-api-11/packaging-your-extension +url: /apidocs-mxsdk/apidocs/extensibility-api-11/packaging-your-extension/ weight: 30 +description: "Explains how to package extensions into add-on modules and publish them to the Mendix Marketplace." --- # Packaging Your Extension -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. +After you complete development on your extension, you can package it into an add-on module so others can use it. You can then publish the module to the Mendix Marketplace so other users can download it into their apps. -To package your extension, follow the steps below: +To package your extension, follow these steps: -1. Make sure you have enabled the [Extension Development](/refguide/preferences-dialog/#extension-development) setting in your app's Preferences. Alternatively, you can start Studio Pro with the `--enable-extension-development` command-line option. -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. +1. Verify that you have enabled the [Extension Development](/refguide/preferences-dialog/#extension-development) setting in your app's **Preferences**. Alternatively, start Studio Pro with the `--enable-extension-development` command-line option. +2. In your app, create a new module and include your development extension. +3. Name the module. +4. Open the module's settings and on the **Export** tab, select **Add-on module**. +5. In the **Extension name** list, select the extension you want to package. -![Extension Add-on Module](/attachments/apidocs-mxsdk/apidocs/extensibility-api/extensionAddOnModule.png) +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/extensionAddOnModule.png" alt="Extension settings showing Add-on module selected with Extension name dropdown" width="400" >}} -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**. +After you create your add-on module with its extension, 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) +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/exportAddOnModule.png" width="400" >}} You can now save the add-on module to a location of your choice. # Importing the Extension Add-on Module -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**. +When the add-on module is available to a Studio Pro user, they can add to their app. 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) +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/importAddOnModule.png" width="400" >}} -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. +When an add-on module containing an extension is imported in the app, Studio Pro displays a warning to the user, asking to trust the extension contained in it. If the user does not choose to trust the extension, the module is still imported but the extension inside it will not be loaded. -![Trust Extension](/attachments/apidocs-mxsdk/apidocs/extensibility-api/trustExtension.png) +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/trustExtension.png" width="400" >}} 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 9138ee05b3e..a097a53bc59 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 @@ -35,7 +35,7 @@ For detailed information on how to get started with extensions, see [Get Started ## How-tos -Below is a list of how-tos for you to begin with: +The following how-tos help you get started: * [How Menus Work](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu/) * [How to Create a Dockable Pane](/apidocs-mxsdk/apidocs/web-extensibility-api-11/dockable-pane-api/) diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/get-started.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/get-started.md index 41d7dc7956d..e920fdc81db 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/get-started.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/get-started.md @@ -7,17 +7,17 @@ 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 document describes 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 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 detailed information, see the [Mendix Studio Pro Web Extensibility API reference documentation](http://apidocs.rnd.mendix.com/11/extensions-api/index.html). ### Prerequisites -You will need the following prerequisites: +You need the following prerequisites: -* [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro) version 11.2.0 or higher. -* A development IDE to develop your extensions. Mendix recommends using [Visual Studio Code](https://code.visualstudio.com/). -* The latest version 22.x.x of Node: https://nodejs.org/en/download. +* [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro) version 11.2.0 or above +* A development IDE to develop your extensions; Mendix recommends using [Visual Studio Code](https://code.visualstudio.com/) +* The latest version 22.x.x of Node from [nodejs.org](https://nodejs.org/en/download/) {{% alert color="info" %}} Extensions can be built on any operating system, as the underlying framework is cross-platform. @@ -29,13 +29,13 @@ Extension development is only possible by enabling the [Extension Development](/ ## Creating Your First Extension -This section will show you how to build and test an extension. +This section shows you how to build and test an extension. ### Create a Test App Create a new app using the **Blank Web App** template. -You can also open the application directory containing the application `.mpr` file by clicking the **App** menu > **Show App Directory in Explorer** (or **Show App Directory in Finder**) in Studio Pro. +You can also open the app directory containing the app `.mpr` file by clicking **App** > **Show App Directory in Explorer** (or **Show App Directory in Finder**) in Studio Pro. ### Creating the Extension @@ -43,18 +43,18 @@ To accelerate your extension development, Mendix provides an extension generator To use the generator, navigate to your desired source code directory and run the command `npm create @mendix/extension@latest`. 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: +The generator asks the following questions: * Select the programming language (TypeScript is used in the 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: +The next two questions are optional but 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) +* Specify the location of the app `.mpr` package (this allows automatic deployment of your extension build to your app) - The last question allows you to select the Studio Pro version you are targeting; Mendix recommends choosing version 11. + The last question allows you to select the Studio Pro version you are targeting. Mendix recommends choosing version 11. {{% alert color="info" %}} On a Windows machine, the Studio Pro executable is typically located at `C:\Program Files\Mendix\\modeler\studiopro.exe`. To find the exact path, follow these steps: @@ -64,14 +64,13 @@ On a Windows machine, the Studio Pro executable is typically located at `C:\Prog 3. Select **Properties**. The **Target** field displays the executable path. {{% /alert %}} -Once you have completed the setup, a new directory named after your extension will be created, -containing the source code of the extension. +Once you complete the setup, a new directory named after your extension is 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. +Before you begin, your extension must 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: @@ -109,13 +108,13 @@ In the source code, you should see the following: }); ``` -3. If you navigate to `build-extension.mjs`, you can choose the directory where the extension will be installed to after being built by changing line 6: +3. If you navigate to `build-extension.mjs`, you can choose the directory where the extension will be installed after being built by changing line 6: ```typescript const appDir = "C:\\TestApps\\AppTestExtensions" ``` -4. The file `.vscode\launch.json` specifies the launch configuration and enables debugging. The following lines specify how Studio Pro will be run: +4. The file `.vscode\launch.json` specifies the launch configuration and enables debugging. The following lines specify how Studio Pro will run: ```json … @@ -124,27 +123,27 @@ In the source code, you should see the following: … ``` -When you install the extension, you will see a new menu item within Studio Pro. +When you install the extension, you see a new menu item in Studio Pro. ### Building, Installing, and Debugging the Extension -The following steps occur within Visual Studio Code: +Complete the following steps in 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. +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 the `.mpr` file in the previous step, this installs the extension into the app 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: +If you answered the last two questions of the extension generator and have built and installed the extension, you can debug it by completing the following steps: 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). +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. +This runs Studio Pro in extension development mode and opens the configured app. You see a new **Extensions** item in the top menu. ## Extensibility Feedback diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/migration-guide.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/migration-guide.md index c822053e280..2438c9d47ce 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/migration-guide.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/migration-guide.md @@ -7,11 +7,11 @@ weight: 2 ## Introduction -A breaking change in the Web Extensibility API was introduced in Studio Pro 11.6, which changed the way [menus](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu/) are created. This guide explains how to update your extension code after upgrading to Studio Pro 11.6 from an earlier version. +Studio Pro 11.6 introduced a breaking change in the Web Extensibility API that changed the way [menus](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu/) are created. This guide explains how to update your extension code after you upgrade to Studio Pro 11.6 from an earlier version. ## `MenuItemActivated` Event -If your extension created menus using the `menuId` and the `menuItemActivated` event to trigger actions, you can now use the action that was called when the event was triggered as the actual `action` property of your menu. +If your extension created menus using `menuId` and the `menuItemActivated` event to trigger actions, you can now use the action that was called when the event was triggered as the `action` property of your menu. For example, if your code looked like this: @@ -44,7 +44,7 @@ await studioPro.ui.extensionsMenu.add({ }); ``` -The `menuItemActivated` event no longer exists, so you cannot listen to it anymore. +The `menuItemActivated` event no longer exists. ## Registering Commands @@ -52,7 +52,7 @@ The `menuItemActivated` event no longer exists, so you cannot listen to it anymo The command registration API has been removed and is no longer available for Studio Pro 11.6 and above. {{% /alert%}} -If your extension created menus by using a command Id of a pre-registered command, the action that is sent to the command registration API when registering the command can now be used directly as the action of the menu. +If your extension created menus using a command ID of a pre-registered command, the action sent to the command registration API when registering the command can now be used directly as the action of the menu. For example, if your code looked like this: @@ -66,7 +66,7 @@ await studioPro.app.commands.registerCommand( await studioPro.ui.extensionsMenu.add({ caption: "My Menu", menuId: "myextension.menu", commandId }); ``` -The same action sent to the command registration API can now instead become the `action` property value on the menu: +The same action sent to the command registration API can now become the `action` property value on the menu: ```typescript await studioPro.ui.extensionsMenu.add({ @@ -78,4 +78,4 @@ await studioPro.ui.extensionsMenu.add({ ## Action Arguments -Action arguments are also possible in the new Menu API. Review the [Menus documentation](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu/) for a detailed explanation. +Action arguments are also possible in the new Menu API. For a detailed explanation, review [Menus](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu/). diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/app-explorer-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/app-explorer-api.md index d5a8fd1d801..f7f785675a8 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/app-explorer-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/app-explorer-api.md @@ -2,19 +2,20 @@ title: "Using the App Explorer API" linktitle: "App Explorer API" url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/app-explorer-api/ +description: "Describes how to use the App Explorer API in Studio Pro to create a context menu for microflows." --- ## Introduction -This how-to describes how to interact with the App Explorer in Studio Pro. In this example, you create a menu which will show for each microflow in the App Explorer. +This how-to describes how to interact with the App Explorer in Studio Pro. In this example, you create a context menu that displays for each microflow in the App Explorer. ## Prerequisites -{{% alert="info" %}} -If you are using Studio Pro 11.0–11.5 and your extension includes menus, your existing menu code will not work when you upgrade to Studio Pro 11.6. To restore full functionality and support, upgrade to the Extensibility API 11.6 and follow the steps in the [Migration Guide](/apidocs-mxsdk/apidocs/web-extensibility-api-11/migration-guide/). -{{% /alert%}} +{{% alert color="info" %}} +If you are using Studio Pro 11.0–11.5 and your extension includes menus, your existing menu code will not work when you upgrade to Studio Pro 11.6. To restore full functionality and support, upgrade to Extensibility API 11.6 and follow the steps in the [Migration Guide](/apidocs-mxsdk/apidocs/web-extensibility-api-11/migration-guide/). +{{% /alert %}} -Before starting this how-to, make sure you have completed the following prerequisites: +Before starting this how-to, complete the following prerequisites: * Review [how menus work](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu/) in the Web Extensibility API * 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. @@ -25,7 +26,7 @@ Before starting this how-to, make sure you have completed the following prerequi Use the full name of the document type to specify which type of document a menu should belong to (for example, `Microflows$Microflow` for microflows or `Pages$Page` for pages). For more information about these document type names, see [Access a Mendix Model Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/model-api/). {{% /alert %}} -The code below uses the `appExplorer` API's `addContextMenu` method to add the menu to all `Microflow` document nodes. When this menu is clicked, the document's Id is sent as an argument through the `DocumentContext` argument parameter of the menu. +The code below uses the `appExplorer` API `addContextMenu` method to add the context menu to all `Microflow` document nodes. When you click this menu, the document ID is sent as an argument through the `DocumentContext` argument parameter. ```typescript import { ComponentContext, DocumentContext, IComponent, Menu, getStudioProApi } from "@mendix/extensions-api"; @@ -53,12 +54,12 @@ export const component: IComponent = { }; ``` -The `DocumentContext` payload for the menu action is an object containing a document Id (`{ documentId: string }`). When creating a menu for the `appExplorer`'s `addContextMenu` method, the `DocumentContext` should be used as the context of your menu. The `documentId` will be the Id of the document the menu is attached to (in this example, the exact `Microflow` node in the App Explorer). +The `DocumentContext` payload for the menu action is an object containing a document ID (`{ documentId: string }`). When you create a menu for the `appExplorer` `addContextMenu` method, use `DocumentContext` as the context of your menu. The `documentId` is the ID of the document the menu is attached to (in this example, the specific `Microflow` node in the App Explorer). -As explained in the [menu documentation](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu/), the `DocumentContext` is not necessary to add your menu to Studio Pro. However, if it is not used, the menu will not receive the clicked document's ID. +As explained in the [menu documentation](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu/), `DocumentContext` is not required to add your menu to Studio Pro. However, if you do not use it, the menu will not receive the clicked document ID. ## Extensibility Feedback -If you would like to provide 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 short [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/custom-blob-document-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/custom-blob-document-api.md index 21cb88a4031..a7d3fbfad42 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/custom-blob-document-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/custom-blob-document-api.md @@ -2,6 +2,7 @@ title: "Register New Document Types With a Corresponding Editor" linktitle: "Introduce New Document Types" url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/custom-blob-document-api/ +description: "Describes how to introduce a new document type and set up a custom editor that allows users to edit documents of that type." --- ## Introduction @@ -12,17 +13,17 @@ This how-to describes how to introduce a new document type and set up a custom e Before starting this how-to, make sure you have completed the following prerequisites: -* [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). +* [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/) ## Custom Document Model -Studio Pro allows you to extend its metamodel by adding custom document types. These documents can store arbitrary data that can be serialized as strings. If you register an editor (a user-defined UI component) for a specific document type, documents of that type will be displayed in the UI alongside any other built-in document type, such as constants, Java Actions, and pages. Specifically, they will appear in the **New Document** and **Find Advanced** dialogs, context menus for adding documents, the App Explorer, and other UI elements that show Studio Pro documents. You can register custom editors to appear either as tabs or as modal dialogs. +Studio Pro allows you to extend its metamodel by adding custom document types. These documents can store arbitrary data that can be serialized as strings. When you register an editor (a user-defined UI component) for a specific document type, documents of that type appear in the UI alongside built-in document types such as constants, Java actions, and pages. They appear in the **New Document** and **Find Advanced** dialogs, context menus for adding documents, the App Explorer, and other UI elements that display Studio Pro documents. You can register custom editors to appear as tabs or as modal dialogs. ## Registering a New Document Type -To register a new document type, follow the steps below: +To register a new document type, do the following: -1. Generate a new extension named `myextension` as described in the [Get Started](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/) guide. +1. Generate a new extension named `myextension` as described in [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). 2. Replace the contents of `src/main/index.ts` with the code below: ```typescript {hl_lines=["8-24"]} @@ -63,7 +64,7 @@ To register a new document type, follow the steps below: export const personDarkThemeIcon = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABHNCSVQICAgIfAhkiAAAAWdJREFUSIm1ljFuwkAQRd/giFTkABS5gMsolBRcIFBwCOTGNUfgDtDRJ9yDioaCKlJ8B0dYmyLjZGLtrh0Jj7SyNPP3f894dtbinHP0aIM+yQHuYkERuQdegDnwBIw1VABH4BV4c86VQRIXMGABXADXsi7AIsjjIR4AG0NwAnIgBUa6UvWdDG4DDLoI1OQlkAFJJMtEMWUtEhXQstTksxCxR2hmRP6UCwMamppnXcnN/sx8k6FPYGlqHixLRCAx32RZ++05mOtz65y7Btsu3I1XYNvgwmZwJty1XbNINYOzL4MxgIg8/Pftjb1bLmgZFSJSiAgiMvHEJhorYhxWoAY+Gt9RnyvP3lUDY/f+ipr67fmuX258U6ACPoEd8Kxrp74KmBp8rhz7H58JetsUWCtRcwZVwLqtTTsdNM3kAHzoOtg3V0z8oCmov1FhwP0NO93U77g2Qje5cETJvHaLKzMqcAvr/a/iC+JcVEP5CMhEAAAAAElFTkSuQmCC'; ``` -4. Add another file `src/model/PersonInfo.ts` in the same directory: +4. Add another file, `src/model/PersonInfo.ts`, in the same directory: ```typescript export type PersonInfo = { @@ -244,33 +245,34 @@ To register a new document type, follow the steps below: ### Register the Document Type -In `src/main/index.ts`, you begin by registering a new document type. Once registered, you can perform all CRUD operations on it. However, it will not appear in the UI until an editor is also registered. +In `src/main/index.ts`, you register a new document type. After you register the document type, you can perform all create, read, update, and delete (CRUD) operations on it. However, the document type does not appear in the UI until you also register an editor. -Optionally, you can provide a `readableTypeName` to display a user-friendly name in logs and the Studio Pro UI instead of the full type name. You can also customize serialization of the document contents to a string. By default, the API uses `JSON.stringify` for serialization and `JSON.parse` for deserialization. +Optionally, you can provide a `readableTypeName` to display a user-friendly name in logs and the Studio Pro UI instead of the full type name. You can also customize how the document contents serialize to a string. By default, the API uses `JSON.stringify` for serialization and `JSON.parse` for deserialization. ### Register the Editor The next call to the Studio Pro API in `src/main/index.ts` registers an editor for the document type. This does the following: -* It registers the `editor` entry point of the extension to the document type, so the editor is shown when users interacts with the document in Studio Pro (for example, through the **App Explorer** or **Find Results**). -* This editor is shown as a tab, but you can also configure it to be shown as a modal dialog. -* Icons for both the light and dark themes are registered; these icons appear wherever a document icon is needed. -* Note that this editor will behave like editors for other, built-in document types. For example, the `studioPro.ui.editors.editDocument` call will open the registered editor for custom documents. +* Registers the `editor` entry point of the extension to the document type, so the editor appears when users interact with the document in Studio Pro (for example, through the **App Explorer** or **Find Results**) +* Displays the editor as a tab, though you can also configure it to display as a modal dialog +* Registers icons for both the light and dark themes; these icons appear wherever a document icon is needed + +This editor behaves like editors for other built-in document types. For example, the `studioPro.ui.editors.editDocument` call opens the registered editor for custom documents. ### Changes in the Editor -In `src/ui/editor.tsx`, the first highlighted block of code listens for changes to documents to ensure the most recent version of the currently active document is shown. Note that the document can be changed outside the currently open editor, either by calls to the custom blob document API, or by Studio Pro operations like **Undo**. +In `src/ui/editor.tsx`, the first highlighted block of code listens for changes to documents. This ensures the most recent version of the currently active document appears. The document can change outside the currently open editor, either through calls to the custom blob document API or through Studio Pro operations like **Undo**. -In the next highlighted block, document contents are fetched whenever a new document is opened or an existing document is updated. +In the next highlighted block, document contents are fetched whenever a new document opens or an existing document updates. -We then provide a way to save changes. +The code then provides a way to save changes. ### Update Build and Manifest Files -Highlighted text in `build-extension.mjs` and `manifest.json` shows changes necessary to ensure the `editor` entry point is built and loaded properly. +The highlighted text in `build-extension.mjs` and `manifest.json` shows the changes necessary to ensure the `editor` entry point builds and loads properly. ## Extensibility Feedback -If you would like to provide us with additional feedback, you can complete a small [survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback). +If you would like to provide us with additional feedback, you can complete a short [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/dialog-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/dialog-api.md index 872c83b92ef..b4017c74264 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/dialog-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/dialog-api.md @@ -6,41 +6,41 @@ url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/dialog-api/ ## Introduction -This how-to describes how to open a modal dialog in Studio Pro from an extension, allowing you to display web content. +This how-to describes how to open a modal dialog in Studio Pro from an extension. You can use this dialog to display web content. -It also describes how to show a progress dialog that follows a sequence of steps and returns a result upon completion. +It also describes how to show a progress dialog that follows a sequence of steps and returns a result when complete. ## Prerequisites -{{% alert="info" %}} +{{% alert color="info" %}} If you are using Studio Pro 11.0–11.5 and your extension includes menus, your existing menu code will not work when you upgrade to Studio Pro 11.6. To restore full functionality and support, upgrade to the Extensibility API 11.6 and follow the steps in the [Migration Guide](/apidocs-mxsdk/apidocs/web-extensibility-api-11/migration-guide/). -{{% /alert%}} +{{% /alert %}} -Before starting this how-to, make sure you have completed the following prerequisites: +Before starting this how-to, complete 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/). +* Be familiar with creating menus as described in [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu-api/). ## Opening a Modal Dialog -Create a menu item to open the dialog. This is done inside the `loaded` event in the main entry point (`src/main/index.ts`). For more information, see [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu-api/). +To open a modal dialog, create a menu item inside the `loaded` event in the main entry point (`src/main/index.ts`). For more information, see [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu-api/). -In a listener event called `menuItemActivated`, the `studioPro.ui.dialogs.showModal(, )` call opens a new dialog where: +In the `menuItemActivated` listener event, call `studioPro.ui.dialogs.showModal(, )` to open a new dialog. The parameters are: -* `` is an object containing the `title` of the dialog, which is shown in the title bar of your dialog in Studio Pro. It also contains the `contentSize` object, where `height` and `width` dimensions for the dialog can be provided. -* `` is an object containing two required properties and one optional property: +* `` – An object containing the `title` of the dialog (shown in the title bar of your dialog in Studio Pro) and the `contentSize` object, where you can provide `height` and `width` dimensions for the dialog. +* `` – An object containing two required properties and one optional property: - * `componentName` — the name of the extension prefixed with `extension/`; for example, `extension/myextension` - * `uiEntryPoint` — the name mapped from the `manifest.json` file - * `queryParams` (optional) — a key-value pair object for passing data to your web content inside the dialog + * `componentName` – The name of the extension prefixed with `extension/`. For example, `extension/myextension`. + * `uiEntryPoint` – The name mapped from the `manifest.json` file. + * `queryParams` (optional) – A key-value pair object for passing data to your web content inside the dialog. {{% alert color="info" %}} -When the dialog's API `showModal` method is called, a `Promise` of `unknown` or `null` is returned. This return value represents anything the web content determines should be returned when the dialog is closed. It is currently unknown by the API, since it can be anything. +When the `showModal` method is called, it returns a `Promise` of `unknown` or `null`. This return value represents anything the web content determines should be returned when the dialog closes. The API cannot determine the type in advance, since it can be anything. -In the example below, the dialog will contain a form where an object is modified, then returned at closing time. +In the example below, the dialog contains a form where an object is modified and then returned when the dialog closes. {{% /alert %}} -An example of the main entry point (`src/main/index.ts`) to open a modal dialog called *My Extension Dialog* looks similar to the following: +The following example shows the main entry point (`src/main/index.ts`) that opens a modal dialog: ```typescript import { IComponent, getStudioProApi } from "@mendix/extensions-api"; @@ -74,9 +74,9 @@ export const component: IComponent = { }; ``` -## Filling the Dialog With Content +## Filling the Dialog with Content -In the previous example, the `uiEntryPoint` property of the `` object had the value `dialog`. This value must match the one from the manifest. Below is an example of the dialog under the `ui` property: +In the previous example, the `uiEntryPoint` property of the `` object has the value `dialog`. This value must match the one in the manifest. The following example shows the dialog under the `ui` property: ```json { @@ -91,7 +91,7 @@ In the previous example, the `uiEntryPoint` property of the `` object ha } ``` -1. Update `build-extension.mjs` to match the manifest with an entry for the new dialog entry point. Specifically, add the `src/ui/dialog.tsx` endpoint to your build script and make sure the variable `appDir` stays unaltered. For example: +1. Update `build-extension.mjs` to match the manifest with an entry for the new dialog entry point. Add the `src/ui/dialog.tsx` endpoint to your build script and make sure the variable `appDir` remains unchanged: ```typescript{hl_lines=["16-19"]} import * as esbuild from 'esbuild' @@ -195,16 +195,15 @@ In the previous example, the `uiEntryPoint` property of the `` object ha }; ``` -Notice the `dialogId` property retrieved from the query parameters of the web page. This value is generated once the dialog API is first called. It is then passed back to the web content so the `close` or `closeWithResult` methods can be called successfully. The dialog's API needs this Id to close the correct dialog. +The `dialogId` property is retrieved from the query parameters of the web page. This value is generated when the dialog API is first called. It is then passed back to the web content so the `close` or `closeWithResult` methods can be called successfully. The dialog API needs this ID to close the correct dialog. -This simple form contains two text boxes for `firstName` and `lastName`. When submitting the form, it closes the dialog by passing along the content of the object modified by the form. -It also contains a simple `Close` button, which calls the API's `close` method without any extra data, apart from the required `dialogId`. +This form contains two text boxes for `firstName` and `lastName`. When you submit the form, it closes the dialog and passes the content of the object modified by the form. The form also contains a **Close** button, which calls the `close` method without any extra data, except the required `dialogId`. -After building and installing the extension in Studio Pro, the dialog opens when the menu is clicked and will display the web content from the `dialog.tsx` file. +After you build and install the extension in Studio Pro, the dialog opens when you click the menu and displays the web content from the `dialog.tsx` file. ## Modifying a Modal Dialog -You can modify the dimensions of a dialog using the dialog API's `update` method. To do this, add a button to the form contained in `dialog.tsx` file, as follows: +You can modify the dimensions of a dialog using the `update` method. To do this, add a button to the form in the `dialog.tsx` file: ```typescript