|
| 1 | + --- |
| 2 | +title: "Show a Progress Dialog Using Web API" |
| 3 | +linktitle: "Show a Progress Dialog" |
| 4 | +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/progress-dialogs/ |
| 5 | +--- |
| 6 | + |
| 7 | + ## Showing a Progress Dialog |
| 8 | + First, create a menu that you will use to open the progress dialog. |
| 9 | + |
| 10 | + To show a progress dialog, you will need to call the method `studioPro.ui.dialogs.showProgressDialog(<title>, <steps>)`, where: |
| 11 | + |
| 12 | +* `<title>` is a string which will be displayed in the title bar of the dialog. |
| 13 | +* `<steps>` is an array of `ProgressDialogStep`, which will run in the same order provided in the array. A `ProgressDialogStep` object containing the following properties: |
| 14 | + * `title` — the title of the step. It is highlighted when the step is running |
| 15 | + * `description` — the description of the step. It will show at the bottom of the dialog next to the progress bar |
| 16 | + * `action` — the action that the step will perform. It returns `Promise<true | string>`. If the step fails, string should be the reason for the failure. Otherwise, `true` will be returned. |
| 17 | + |
| 18 | +A checkmark icon will be shown next to the step title after the step has completed successfully. But if one of the steps fails, the dialog will close and the remaining steps will not be executed. |
| 19 | + |
| 20 | +The `showProgressDialog` method returns a `Promise<ProgressDialogResult>`. `ProgressDialogResult` is an object that contains the following properties: |
| 21 | +* `result` - a string that is either `Success`, `Failure` or `UserCancelled` |
| 22 | + * `Success` is returned when all the steps have returned true |
| 23 | + * `Failure` is returned when one step has failed, causing the dialog to close |
| 24 | + * `UserCancelled` is returned when the user closes the dialog themselves and interrupts the process |
| 25 | +* `failedStep` (optional) - it is an object of type `FailedProgressStepResult` which describes the actual step that has failed |
| 26 | + |
| 27 | +The `FailedProgressStepResult` object contains the following properties: |
| 28 | +* `stepTitle` - the title of the step that has failed, causing the whole process to fail |
| 29 | +* `error` - a string which describes the error or exception that has occurred during the step execution |
| 30 | + |
| 31 | +In this example, we will 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`). For more information, see [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu-api/). |
| 32 | + |
| 33 | +```typescript |
| 34 | +import { ComponentContext, IComponent, ProgressDialogStep, getStudioProApi } from "@mendix/extensions-api"; |
| 35 | + |
| 36 | +export const component: IComponent = { |
| 37 | + async loaded(componentContext: ComponentContext) { |
| 38 | + const studioPro = getStudioProApi(componentContext); |
| 39 | + |
| 40 | + const step1: ProgressDialogStep = { |
| 41 | + title: "Step 1", |
| 42 | + description: "Executing Step 1", |
| 43 | + action: async () => { |
| 44 | + // perform action |
| 45 | + return true; |
| 46 | + } |
| 47 | + }; |
| 48 | + |
| 49 | + const step2: ProgressDialogStep = { |
| 50 | + title: "Step 2", |
| 51 | + description: "Executing Step 2", |
| 52 | + action: async () => { |
| 53 | + // perform action |
| 54 | + return true; |
| 55 | + } |
| 56 | + }; |
| 57 | + |
| 58 | + const step3: ProgressDialogStep = { |
| 59 | + title: "Step 3", |
| 60 | + description: "Executing Step 3", |
| 61 | + action: async () => { |
| 62 | + // perform action |
| 63 | + return true; |
| 64 | + } |
| 65 | + }; |
| 66 | + |
| 67 | + // menu to call `showProgressDialog` method |
| 68 | + await studioPro.ui.extensionsMenu.add({ |
| 69 | + caption: "Sample Progress Dialog", |
| 70 | + menuId: `myextension.start-progress-menu`, |
| 71 | + action: async () => { |
| 72 | + const steps = [step1, step2, step3]; |
| 73 | + const progressDialogResult = await studioPro.ui.dialogs.showProgressDialog("Sample Progress Dialog", steps); |
| 74 | + |
| 75 | + switch (progressDialogResult.result) { |
| 76 | + case "Success": |
| 77 | + await studioPro.ui.messageBoxes.show("info", "Process completed successfully"); |
| 78 | + break; |
| 79 | + |
| 80 | + case "UserCancelled": |
| 81 | + await studioPro.ui.messageBoxes.show("info", "Process was cancelled by the user"); |
| 82 | + break; |
| 83 | + |
| 84 | + case "Failure": { |
| 85 | + const errorMessage = `Step '${progressDialogResult.failedStep?.stepTitle}' has failed'`; |
| 86 | + const errorDetails = progressDialogResult.failedStep?.error ?? ""; |
| 87 | + |
| 88 | + await studioPro.ui.messageBoxes.show("error", errorMessage, errorDetails); |
| 89 | + break; |
| 90 | + } |
| 91 | + } |
| 92 | + } |
| 93 | + }); |
| 94 | + } |
| 95 | +}; |
| 96 | +``` |
| 97 | + |
| 98 | +It is recommended to always wrap your step action body in a `try/catch` block so that you can be in control of the error that gets returned to the user: |
| 99 | +```typescript |
| 100 | +const step: ProgressDialogStep = { |
| 101 | + title: "Step X", |
| 102 | + description: "Executing Step X", |
| 103 | + action: async () => { |
| 104 | + try { |
| 105 | + // perform action |
| 106 | + return true; |
| 107 | + } catch (error: Error | unknown) { |
| 108 | + return error instanceof Error ? error.message : "An error occurred while performing Step X"; |
| 109 | + } |
| 110 | + } |
| 111 | + }; |
| 112 | +``` |
| 113 | + |
| 114 | +When running, the progress dialog will look like this: |
| 115 | +{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/dialogs/sample-progress-dialog.png" >}} |
| 116 | + |
| 117 | +## Extensibility Feedback |
| 118 | + |
| 119 | +If you would like to provide us with additional feedback, you can complete a small [survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback). |
| 120 | + |
| 121 | +Any feedback is appreciated. |
0 commit comments