Add explanation for resolveImmediatelyOnCancel for progress dialogs

Author: ester-nl

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`. It is only required if the progress dialog gets cancelled and the developer needs the result of the cancelled step at the exact time of the cancellation. The default behavior is that the cancelled step will finish, and the whole dialog will return the state that exists when the cancelled step is completed. If the developer needs the state that exists at the exact time of cancellation, then they can pass `true` for this parameter.
 
 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. The cancelled step still finishes executing, and unless `resolveImmediatelyOnCancel` is `true`, the final state of the result will contain the changes performed by the step.
 * `failedStep` (optional) – An object of type `FailedProgressStepResult` that describes the step that failed.
 
+If the last step is cancelled, but it completed successfully, the whole result of the progress dialog will be `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,59 @@ export const component: IComponent = {
 };
 ```
 
+To see how `resolveImmediatelyOnCancel` influences the final state of the result, let's use the example above modified to set a value twice for each step into a dictionary called `state`. If `resolveImmediatelyOnCancel` is omitted when calling `showProgressDialog` (which is the default behavior), then the cancelled step will finish executing and the final result will have a value of `2` for the dictionary value set at that step.
+If however, the developer needs the cancelled step to not influence the final result, they should pass `true` for `resolveImmediatelyOnCancel`, and once the user cancels the progress dialog, the `state` dictionary will contain a value of `1` instead of `2` for the cancelled 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