Review

Author: quinntracy

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

@@ -6,38 +6,38 @@ 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" %}}
 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%}}
 
-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/).
+Create a menu item to open the dialog 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 dialog where:
+In a listener event called `menuItemActivated`, the `studioPro.ui.dialogs.showModal(<dialogInfo>, <uiSpec>)` call opens a new dialog. The parameters are:
 
-* `<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:
+* `<dialogInfo>` – 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 you can provide `height` and `width` dimensions for the dialog.
+* `<uiSpec>` – 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:
@@ -76,7 +76,7 @@ export const component: IComponent = {
 
 ## Filling the Dialog With Content
 
-In the previous example, the `uiEntryPoint` property of the `<uispec>` 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 `<uispec>` 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 `<uispec>` 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,16 @@ In the previous example, the `uiEntryPoint` property of the `<uispec>` 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 simple 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
 <button
@@ -224,30 +224,30 @@ 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:
+ To show a progress dialog, call the method `studioPro.ui.dialogs.showProgressDialog(<title>, <steps>)`. The parameters are:
 
-* `<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
+* `<title>` – A string that is displayed in the title bar of the dialog.
+* `<steps>` – An array of `ProgressDialogStep` objects, which run 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 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.
 
-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.
+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.
 
 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
+* `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.
+* `failedStep` (optional) – An object of type `FailedProgressStepResult` that describes the step that 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
+* `stepTitle` – The title of the step that failed, causing the whole process to fail.
+* `error` – A string that describes the error or exception that occurred during 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`).
+The following example creates a menu to show the modal progress dialog and runs three steps inside the `loaded` event in the main entry point (`src/main/index.ts`).
 
 ```typescript
 import { ComponentContext, IComponent, ProgressDialogStep, getStudioProApi } from "@mendix/extensions-api";
@@ -314,7 +314,7 @@ export const component: IComponent = {
 };
 ```
 
-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:
+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
 const step: ProgressDialogStep = {
@@ -331,8 +331,8 @@ const step: ProgressDialogStep = {
         };
 ```
 
-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" >}}
+When running, the progress dialog looks like this:
+{{< figure src="/attachments/apidocs-mxsdk/apidocs/extensibility-api/web/dialogs/sample-progress-dialog.png" alt="Sample progress dialog showing three steps" width="300" >}}
 
 ## Extensibility Feedback