Merge pull request #11555 from ester-nl/appext/1415-update-progress-dialog-behavior

Add explanation for `resolveImmediatelyOnCancel` for progress dialogs

Author: ConnorLand

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

@@ -230,6 +230,7 @@ To show a progress dialog, call the method `studioPro.ui.dialogs.showProgressDia
     * `title` – The title of the step, which is highlighted when the step runs.
     * `description` – The description of the step, which shows at the bottom of the dialog next to the progress bar.
     * `action` – The action the step performs that returns `Promise<true | string>`, where `string` indicates the reason for failure if the step fails, and `true` is returned otherwise.
+* `<resolveImmediatelyOnCancel>` – An optional boolean that, if provided, can only be `true`. By default, the canceled step finishes and the dialog returns the state that exists when the step completes. Pass `true` to instead return the state at the exact moment of cancellation.
 
 A checkmark icon appears next to the step title when the step completes successfully. If one of the steps fails, the dialog closes and the remaining steps do not run.
 
@@ -238,9 +239,11 @@ The `showProgressDialog` method returns a `Promise<ProgressDialogResult>`. `Prog
 * `result` – A string that is either `Success`, `Failure`, or `UserCancelled`:
     * `Success` – Returned when all steps return `true`.
     * `Failure` – Returned when one step fails, causing the dialog to close.
-    * `UserCancelled` – Returned when the user closes the dialog and interrupts the process.
+    * `UserCancelled` – Returned when the user closes the dialog and interrupts the process. By default, the canceled step finishes and the result reflects the state when it completes; if `resolveImmediatelyOnCancel` is `true`, the result reflects the state at the moment of cancellation.
 * `failedStep` (optional) – An object of type `FailedProgressStepResult` that describes the step that failed.
 
+If the last step is canceled but completes successfully, the overall result is `Success`.
+
 The `FailedProgressStepResult` object contains the following properties:
 
 * `stepTitle` – The title of the step that failed, causing the whole process to fail.
@@ -313,6 +316,60 @@ export const component: IComponent = {
 };
 ```
 
+To see how `resolveImmediatelyOnCancel` influences the result, consider a modified version of the example above that sets a value twice per step into a dictionary called `state`. By default (when `resolveImmediatelyOnCancel` is omitted), the canceled step finishes executing and the result has a value of `2` for the dictionary entry set at that step.
+
+To capture the state before the canceled step completes, pass `true` for `resolveImmediatelyOnCancel`. The `state` dictionary then contains a value of `1` instead of `2` for the canceled step.
+
+```typescript
+const state: { [step: string]: number } = {};
+
+        const step1: ProgressDialogStep = {
+            title: "Step 1",
+            description: "Executing Step 1",
+            action: async () => {
+                // perform action
+                state["step1"] = 1;
+                // other things happening...
+                await sleep(5000);
+                state["step1"] = 2;
+                return true;
+            }
+        };
+
+        const step2: ProgressDialogStep = {
+            title: "Step 2",
+            description: "Executing Step 2",
+            action: async () => {
+                // perform action
+                state["step2"] = 1;
+                // other things happening...
+                await sleep(5000);
+                state["step2"] = 2;
+
+                return true;
+            }
+        };
+
+        const step3: ProgressDialogStep = {
+            title: "Step 3",
+            description: "Executing Step 3",
+            action: async () => {
+                // perform action
+                state["step3"] = 1;
+                // other things happening...
+                await sleep(5000);
+                state["step3"] = 2;
+                return true;
+            }
+        };
+
+        const resolveImmediatelyOnCancel = true;
+        const result = await studioPro.ui.dialogs.showProgressDialog("Cancel This Progress", [step1, step2, step3], resolveImmediatelyOnCancel);
+
+        if (result.result === "Success") await studioPro.ui.messageBoxes.show("info", "Process completed successfully");
+        if (result.result === "UserCancelled") await studioPro.ui.messageBoxes.show("info", "Process was cancelled. Result: " + JSON.stringify(state));
+```
+
 Mendix recommends wrapping your step action body in a `try/catch` block so you can control the error that is returned to the user:
 
 ```typescript

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.12.2
+
+* We fixed a bug where the Extensions Overview page would not open if the user was not signed in.
+* We fixed a bug where reloading a Dev extension would cause a crash if extension tabs were still open.
+* We fixed an issue where progress dialogs did not behave like their C# counterpart. Canceling a step now waits for it to finish and return its result. To exit the step and return its result immediately on cancel, pass `resolveImmediatelyOnCancel` to `IDialogApi.showProgressDialog`.
+
 ## Version 11.12.1
 
 * We removed timeouts for Custom Blob Document consistency checks instead of showing a generic error in the **Errors** pane. We also added analytics to identify extensions that exceed the previous timeout.