Merge pull request #10197 from ester-nl/appext/922-progress-dialog-docs

Add doc and sample code for showing a progress dialog.

Author: quinntracy

content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/command-api.md

@@ -29,28 +29,25 @@ To register commands, use the Commands API `registerCommand`.
 In the sample code below, we register a command, then attach it to a menu by setting the property `commandId` to the `Menu` object.
 
 ```typescript
-import { ComponentContext, IComponent, Menu, StudioProApi, getStudioProApi } from "@mendix/extensions-api";
-
+import { ComponentContext, IComponent, StudioProApi, getStudioProApi } from "@mendix/extensions-api";
 const extensionId = "myextension";
 
 export const component: IComponent = {
     async loaded(componentContext: ComponentContext) {
         const studioPro = getStudioProApi(componentContext);
 
-        await this.createMenuWithCommand(studioPro);
-    }
-
-    async createMenuWithCommand(studioPro: StudioProApi) {
-        const commandId = `${extensionId}.menu-command`;
-        const menuId = `${commandId}.menu`;
-
-        await studioPro.app.commands.registerCommand<void>(
-            commandId,
-            async () => await studioPro.ui.messageBoxes.show("info", `This menu executed a command with id '${commandId}'`)
-        );
-
-        await studioPro.ui.extensionsMenu.add({ caption: "Menu with command", menuId, commandId });
+        await createMenuWithCommand(studioPro);
     }
+};
+async function createMenuWithCommand(studioPro: StudioProApi) {
+    const commandId = `${extensionId}.menu-command`;
+    const menuId = `${commandId}.menu`;
+
+    await studioPro.app.commands.registerCommand(
+        commandId,
+        async () => await studioPro.ui.messageBoxes.show("info", `This menu executed a command with id '${commandId}'`)
+    );
+    await studioPro.ui.extensionsMenu.add({ caption: "Menu with command", menuId, commandId });
 }
 ```
 

content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/dialog-api.md

@@ -6,7 +6,9 @@ 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. This dialog will contain your web content.
+This how-to describes how to open a modal dialog in Studio Pro from an extension, allowing you 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.
 
 ## Prerequisites
 
@@ -19,7 +21,7 @@ Before starting this how-to, make sure you have completed the following prerequi
 
 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/).
 
-In a listener event called `menuItemActivated`, the `studioPro.ui.dialogs.showModal(<dialogInfo>, <uiSpec>)` call opens a new tab where:
+In a listener event called `menuItemActivated`, the `studioPro.ui.dialogs.showModal(<dialogInfo>, <uiSpec>)` call opens a new dialog where:
 
 * `<dialogInfo>` 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.
 * `<uiSpec>` is an object containing two required properties and one optional property:
@@ -227,6 +229,118 @@ You can modify the dimensions of a dialog using the dialog API's `update` method
 
 You can also modify the dialog's dimensions while it is open.
 
+## Showing a Progress Dialog {#process-dialog}
+
+ To show a progress dialog, call the method `studioPro.ui.dialogs.showProgressDialog(<title>, <steps>)`, where:
+
+* `<title>` is a string that is displayed in the title bar of the dialog
+* `<steps>` is an array of `ProgressDialogStep`, which runs in the same order provided in the array; a `ProgressDialogStep` object contains the following properties:
+    * `title` – the title of the step, which is highlighted when the step is running
+    * `description` –  the description of the step, which shows at the bottom of the dialog next to the progress bar
+    * `action` – the action the step will perform that returns `Promise<true | string>`, where `string` indicates the reason for failure if the step fails, and `true` is returned otherwise
+
+A checkmark icon will be shown next to the step title once step has completed successfully. If one of the steps fails, the dialog will close and the remaining steps will not be executed.
+
+The `showProgressDialog` method returns a `Promise<ProgressDialogResult>`. `ProgressDialogResult` is an object that contains the following properties:
+
+* `result` – a string that is either `Success`, `Failure`, or `UserCancelled`
+    * `Success` – returned when all the steps have returned true
+    * `Failure` – returned when one step has failed, causing the dialog to close
+    * `UserCancelled` – returned when the user closes the dialog themselves and interrupts the process
+* `failedStep` (optional) – an object of type `FailedProgressStepResult` which describes the actual step that has failed
+
+The `FailedProgressStepResult` object contains the following properties:
+
+* `stepTitle` – the title of the step that has failed, causing the whole process to fail
+* `error` – a string which describes the error or exception that has occurred during the step execution
+
+In the example below, you create a menu to show the modal progress dialog, and run three steps. This is done inside the `loaded` event in the main entry point (`src/main/index.ts`).
+
+```typescript
+import { ComponentContext, IComponent, ProgressDialogStep, getStudioProApi } from "@mendix/extensions-api";
+
+export const component: IComponent = {
+    async loaded(componentContext: ComponentContext) {
+        const studioPro = getStudioProApi(componentContext);
+
+        const step1: ProgressDialogStep = {
+            title: "Step 1",
+            description: "Executing Step 1",
+            action: async () => {
+                // perform action
+                return true;
+            }
+        };
+
+        const step2: ProgressDialogStep = {
+            title: "Step 2",
+            description: "Executing Step 2",
+            action: async () => {
+                // perform action
+                return true;
+            }
+        };
+
+        const step3: ProgressDialogStep = {
+            title: "Step 3",
+            description: "Executing Step 3",
+            action: async () => {
+                // perform action
+                return true;
+            }
+        };
+
+        // menu to call `showProgressDialog` method
+        await studioPro.ui.extensionsMenu.add({
+            caption: "Sample Progress Dialog",
+            menuId: `myextension.start-progress-menu`,
+            action: async () => {
+                const steps = [step1, step2, step3];
+                const progressDialogResult = await studioPro.ui.dialogs.showProgressDialog("Sample Progress Dialog", steps);
+
+                switch (progressDialogResult.result) {
+                    case "Success":
+                        await studioPro.ui.messageBoxes.show("info", "Process completed successfully");
+                        break;
+
+                    case "UserCancelled":
+                        await studioPro.ui.messageBoxes.show("info", "Process was cancelled by the user");
+                        break;
+
+                    case "Failure": {
+                        const errorMessage = `Step '${progressDialogResult.failedStep?.stepTitle}' has failed'`;
+                        const errorDetails = progressDialogResult.failedStep?.error ?? "";
+
+                        await studioPro.ui.messageBoxes.show("error", errorMessage, errorDetails);
+                        break;
+                    }
+                }
+            }
+        });
+    }
+};
+```
+
+It is recommended to always wrap your step action body in a `try/catch` block so you can be in control of the error that is returned to the user:
+
+```typescript
+const step: ProgressDialogStep = {
+            title: "Step X",
+            description: "Executing Step X",
+            action: async () => {
+                try {
+                    // perform action
+                    return true;
+                } catch (error: Error | unknown) {
+                    return error instanceof Error ? error.message : "An error occurred while performing Step X";
+                }
+            }
+        };
+```
+
+When running, the progress dialog will look like this:
+{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/dialogs/sample-progress-dialog.png" width="300" >}}
+
 ## Extensibility Feedback
 
 If you would like to provide additional feedback, you can complete a small [survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback).

content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/menu-api.md

@@ -28,6 +28,8 @@ A menu has the following properties:
 | `hasSeparatorBefore` <br> (default: `false`)  | Adds a visual separator before the item              |
 | `hasSeparatorAfter` <br> (default: `false`)  | Adds a visual separator after the item                |
 | `enabled`  <br> (default: `true`)  | Indicates that the menu item notifies the listener when clicked |
+| `commandId` (optional) | The id of the previously registered command, which executes when the menu is clicked |
+| `action` (optional) | The action that executes when the menu is clicked |
 
 {{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/menus/grouped_menus.png" width="300" >}}
 
@@ -205,6 +207,37 @@ Instead of listening to the `menuItemActivated` event, it is possible to registe
 
 For more information on how to register commands, see the [Commands API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/command-api/).
 
+## Setting the Action Property on the Menu
+
+You can also set the `action` property on the menu directly.
+
+```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 menuId = "my-menu-unique-id";
+        const caption = "Menu with Action";
+
+        const menu: Menu = {
+            caption: caption,
+            menuId: menuId,
+            action: async () => {
+                await menuApi.update(menuId, {
+                    caption: `${caption} (Disabled)`,
+                    enabled: false
+                });
+            }
+        };
+
+        await menuApi.add(menu);
+    }
+}
+```
+
 ## Extensibility Feedback
 
 If you would like to provide additional feedback, you can complete a small [survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback).