[All hosts] (dialog) Update Dialog API articles (#5061)

samantharamon · Rick-Kirkham · web-flow · commit 919d98e31ac8 · 2025-02-24T16:55:24.000-08:00
* Update dialog articles

* Apply suggestion from review

Co-authored-by: Rick Kirkham &lt;Rick-Kirkham@users.noreply.github.com&gt;

* Correct function

---------

Co-authored-by: Rick Kirkham &lt;Rick-Kirkham@users.noreply.github.com&gt;
diff --git a/docs/develop/dialog-api-in-office-add-ins.md b/docs/develop/dialog-api-in-office-add-ins.md
@@ -1,7 +1,7 @@
 ---
 title: Use the Office dialog API in your Office Add-ins
 description: Learn the basics of creating a dialog box in an Office Add-in.
-ms.date: 02/12/2025
+ms.date: 02/25/2025
 ms.topic: how-to
 ms.localizationpriority: medium
 ---
@@ -12,10 +12,16 @@ Use the [Office dialog API](/javascript/api/office/office.ui) to open dialog box
 
 - Sign in a user with a resource such as Google, Facebook, or Microsoft identity. For more information, see [Authenticate with the Office dialog API](auth-with-office-dialog-api.md).
 - Provide more screen space, or even a full screen, for some tasks in your add-in.
-- Host a video that would be too small if confined to a task pane.
+- [Host a video that would be too small if confined to a task pane](dialog-video.md).
+- Show an error, progress, or input screen.
 
 > [!TIP]
-> Because overlapping UI elements are discouraged, avoid opening a dialog box from a task pane unless your scenario requires it. When you consider how to use the surface area of a task pane, note that task panes can be tabbed. For an example of a tabbed task pane, see the [Excel Add-in JavaScript SalesTracker](https://github.com/OfficeDev/Excel-Add-in-JavaScript-SalesTracker) sample.
+>
+> - We recommend that you don't use a dialog box to interact with a document. Use a task pane instead. For guidance, see [Task panes in Office Add-ins](../design/task-pane-add-ins.md).
+>
+> - Because overlapping UI elements are discouraged, avoid opening a dialog box from a task pane unless your scenario requires it. When you consider how to use the surface area of a task pane, note that task panes can be tabbed. For an example of a tabbed task pane, see the [Excel Add-in JavaScript SalesTracker](https://github.com/OfficeDev/Excel-Add-in-JavaScript-SalesTracker) sample.
+>
+> To learn more about best practices for implementing a dialog, see [Best practices and rules for the Office dialog API](dialog-best-practices.md).
 
 The following image shows an example of a dialog box.
 
@@ -32,10 +38,10 @@ The Office JavaScript APIs include a [Dialog](/javascript/api/office/office.dial
 
 To open a dialog box, your code, typically a page in a task pane, calls the [displayDialogAsync](/javascript/api/office/office.ui#office-office-ui-displaydialogasync-member(1)) method and passes to it the URL of the resource that you want to open. The page on which this method is called is known as the "host page". For example, if you call this method in script on index.html in a task pane, then index.html is the host page of the dialog box that the method opens.
 
-The resource that is opened in the dialog box is usually a page, but it can be a controller method in an MVC application, a route, a web service method, or any other resource. In this article, 'page' or 'website' refers to the resource in the dialog box. The following code is a simple example.
+The resource that is opened in the dialog box is usually a page, but it can be a controller method in an MVC application, a route, a web service method, or any other resource. In this article, "page" or "website" refers to the resource in the dialog box. The following code is a simple example.
 
 ```javascript
-Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html');
+Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html");
 ```
 
 - The URL uses the HTTP**S** protocol. This is mandatory for all pages loaded in a dialog box, not just the first page loaded.
@@ -49,7 +55,7 @@ After the first page (or other resource) is loaded, a user can use links or othe
 By default, the dialog box will occupy 80% of the height and width of the device screen, but you can set different percentages by passing a configuration object to the method, as shown in the following example.
 
 ```javascript
-Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', { height: 30, width: 20 });
+Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });
 ```
 
 For a sample add-in that does this, see [Build Office Add-ins for Excel](https://github.com/OfficeDev/TrainingContent/tree/master/OfficeAddin/02%20Building%20Add-ins%20for%20Microsoft%20Excel). For more samples that use `displayDialogAsync`, see [Code samples](#code-samples).
@@ -58,12 +64,15 @@ Set both values to 100% to get what is effectively a full screen experience. The
 
 You can open only one dialog box from a host window. An attempt to open another dialog box generates an error. For example, if a user opens a dialog box from a task pane, they can't open a second dialog box from a different page in the task pane. However, when a dialog box is opened from an [add-in command](../design/add-in-commands.md), the command opens a new (but unseen) HTML file each time it is selected. This creates a new (unseen) host window, so each such window can launch its own dialog box. For more information, see [Errors from displayDialogAsync](dialog-handle-errors-events.md#errors-from-displaydialogasync).
 
+> [!NOTE]
+> In Outlook on the web and new Outlook on Windows, don't set the [window.name](https://developer.mozilla.org/docs/Web/API/Window/name) property when configuring a dialog in your add-in. The `window.name` property is used by these Outlook clients to maintain functionality across page redirects.
+
 ### Take advantage of a performance option in Office on the web
 
 The `displayInIframe` property is an additional property in the configuration object that you can pass to `displayDialogAsync`. When this property is set to `true`, and the add-in is running in a document opened in Office on the web, the dialog box will open as a floating iframe rather than an independent window, which makes it open faster. The following is an example.
 
 ```javascript
-Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', { height: 30, width: 20, displayInIframe: true });
+Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20, displayInIframe: true });
 ```
 
 The default value is `false`, which is the same as omitting the property entirely. If the add-in isn't running in Office on the web, the `displayInIframe` is ignored.
@@ -109,7 +118,7 @@ The host page must be configured to receive the message. You do this by adding a
 
 ```javascript
 let dialog; // Declare dialog as global for use in later functions.
-Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', { height: 30, width: 20 },
+Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
     (asyncResult) => {
         dialog = asyncResult.value;
         dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
@@ -146,7 +155,7 @@ function processMessage(arg) {
 The `dialog` object must be the same one that is returned by the call of `displayDialogAsync`. You need to declare the `dialog` object as a global variable. Or you can scope the `dialog` object to the `displayDialogAsync` call with an anonymous callback function as shown in the following example. In the example, `processMessage` doesn't need to close the dialog since the `close` method is called in the anonymous callback function.
 
 ```javascript
-Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', { height: 30, width: 20 },
+Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
     (asyncResult) => {
         const dialog = asyncResult.value;
         dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
@@ -255,7 +264,7 @@ When you call the Office dialog API to open a dialog box, a [Dialog](/javascript
 
 ```javascript
 let dialog; // Declare as global variable.
-Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html',
+Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html",
     (asyncResult) => {
         dialog = asyncResult.value;
         dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
@@ -356,7 +365,7 @@ If the message doesn't include sensitive data, you can set the `targetOrigin` to
 dialog.messageChild(messageToDialog, { targetOrigin: "*" });
 ```
 
-The add-in's manifest specifies trusted domains. In the unified manifest for Microsoft 365, this is specified in the "validDomains" property. In the add-in only manifest, this is specified in the **\<AppDomains\>** element. 
+The add-in's manifest specifies trusted domains. In the unified manifest for Microsoft 365, this is specified in the "validDomains" property. In the add-in only manifest, this is specified in the **\<AppDomains\>** element.
 
 [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)]
 
diff --git a/docs/develop/dialog-best-practices.md b/docs/develop/dialog-best-practices.md
@@ -1,33 +1,38 @@
 ---
-title: Best practices and rules for the Office dialog API
-description: Provides rules and best practices for the Office dialog API, such as best practices for a single-page application (SPA).
-ms.date: 05/16/2024
+title: Best practices and rules for the Office Dialog API
+description: Provides rules, limitations, and best practices for the Office Dialog API, such as best practices for a single-page application (SPA).
+ms.date: 02/25/2025
 ms.topic: best-practice
 ms.localizationpriority: medium
 ---
 
-# Best practices and rules for the Office dialog API
+# Best practices and rules for the Office Dialog API
 
-This article provides rules, gotchas, and best practices for the Office dialog API, including best practices for designing the UI of a dialog and using the API within a single-page application (SPA).
+This article provides rules, limitations, and best practices for the Office Dialog API, including best practices for designing the UI of a dialog and using the API within a single-page application (SPA).
 
 > [!NOTE]
-> To familiarize yourself with the basics of using the Office dialog API, see [Use the Office dialog API in your Office Add-ins](dialog-api-in-office-add-ins.md).
+> To familiarize yourself with the basics of using the Office Dialog API, see [Use the Office Dialog API in your Office Add-ins](dialog-api-in-office-add-ins.md).
 >
 > See also [Handling errors and events with the Office dialog box](dialog-handle-errors-events.md).
 
-## Rules and gotchas
+## Rules and limitations
 
-- The dialog box can only navigate to HTTPS URLs, not HTTP.
+- A dialog box can only navigate to HTTPS URLs, not HTTP.
 - The URL passed to the [displayDialogAsync](/javascript/api/office/office.ui) method must be in the exact same domain as the add-in itself. It can't be a subdomain. However, the page that is passed to it can redirect to a page in another domain.
-- A host page can have only one dialog box open at a time. The host page could be either a task pane or the [function file](/javascript/api/manifest/functionfile) of a [function command](../design/add-in-commands.md#types-of-add-in-commands).
+- A host page can have only one dialog box open at a time. The host page could be either a task pane or the [function file](/javascript/api/manifest/functionfile) of a [function command](../design/add-in-commands.md#types-of-add-in-commands). Multiple dialogs can be open at the same time from custom ribbon buttons or menu items.
 - Only two Office APIs can be called in the dialog box,
   - [Office.context.ui.messageParent](/javascript/api/office/office.ui#office-office-ui-messageparent-member(1))
   - `Office.context.requirements.isSetSupported` (For more information, see [Specify Office applications and API requirements](specify-office-hosts-and-api-requirements.md).)
 - The [messageParent](/javascript/api/office/office.ui#office-office-ui-messageparent-member(1)) function should usually be called from a page in the exact same domain as the add-in itself, but this isn't mandatory. For more information, see [Cross-domain messaging to the host runtime](dialog-api-in-office-add-ins.md#cross-domain-messaging-to-the-host-runtime).
+- When a dialog box opens, it's centered on the screen on top of the Office application.
+- A dialog box can be moved and resized by the user.
+- A dialog box appears in the order in which it was created.
 
   > [!TIP]
   > In Office on the web and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627), if the domain of your dialog is different from that of your add-in and it enforces the [Cross-Origin-Opener-Policy: same-origin](https://developer.mozilla.org/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) response header, your add-in will be blocked from accessing messages from the dialog and your users will be shown [error 12006](dialog-handle-errors-events.md#errors-and-events-in-the-dialog-box). To prevent this, you must set the header to `Cross-Origin-Opener-Policy: unsafe-none` or configure your add-in and dialog to be in the same domain.
 
+- In Outlook on the web and new Outlook on Windows, don't set the [window.name](https://developer.mozilla.org/docs/Web/API/Window/name) property when configuring a dialog in your add-in. The `window.name` property is used by these Outlook clients to maintain functionality across page redirects.
+
 ## Best practices
 
 ### Avoid overusing dialog boxes
@@ -74,29 +79,33 @@ The `close` method doesn't accept a callback parameter, and it doesn't return a
 
 ```javascript
 function openFirstDialog() {
-  Office.context.ui.displayDialogAsync("https://MyDomain/firstDialog.html", { width: 50, height: 50},
-     (result) => {
-      if(result.status === Office.AsyncResultStatus.Succeeded) {
+  Office.context.ui.displayDialogAsync(
+    "https://MyDomain/firstDialog.html",
+    { width: 50, height: 50 },
+    (result) => {
+      if (result.status === Office.AsyncResultStatus.Succeeded) {
         const dialog = result.value;
         dialog.close();
         openSecondDialog();
       }
       else {
-         // Handle errors
+         // Handle errors.
       }
     }
   );
 }
  
 function openSecondDialog() {
-  Office.context.ui.displayDialogAsync("https://MyDomain/secondDialog.html", { width: 50, height: 50},
+  Office.context.ui.displayDialogAsync(
+    "https://MyDomain/secondDialog.html",
+    { width: 50, height: 50 },
     (result) => {
-      if(result.status === Office.AsyncResultStatus.Failed) {
+      if (result.status === Office.AsyncResultStatus.Failed) {
         if (result.error.code === 12007) {
-          openSecondDialog(); // Recursive call
+          openSecondDialog(); // Recursive call.
         }
         else {
-         // Handle other errors
+         // Handle other errors.
         }
       }
     }
@@ -108,33 +117,39 @@ Alternatively, you could force the code to pause before it tries to open the sec
 
 ```javascript
 function openFirstDialog() {
-  Office.context.ui.displayDialogAsync("https://MyDomain/firstDialog.html", { width: 50, height: 50},
-     (result) => {
-      if(result.status === Office.AsyncResultStatus.Succeeded) {
+  Office.context.ui.displayDialogAsync(
+    "https://MyDomain/firstDialog.html",
+    { width: 50, height: 50 },
+    (result) => {
+      if (result.status === Office.AsyncResultStatus.Succeeded) {
         const dialog = result.value;
         dialog.close();
         setTimeout(() => { 
-          Office.context.ui.displayDialogAsync("https://MyDomain/secondDialog.html", { width: 50, height: 50},
-             (result) => { /* callback body */ }
+          Office.context.ui.displayDialogAsync(
+            "https://MyDomain/secondDialog.html",
+            { width: 50, height: 50 },
+            (result) => {
+              // Callback body.
+            }
           );
         }, 1000);
       }
       else {
-         // Handle errors
+         // Handle errors.
       }
     }
   );
 }
 ```
 
-### Best practices for using the Office dialog API in an SPA
+### Best practices for using the Office Dialog API in an SPA
 
 If your add-in uses client-side routing, as single-page applications (SPAs) typically do, you have the option to pass the URL of a route to the [displayDialogAsync](/javascript/api/office/office.ui) method instead of the URL of a separate HTML page. *We recommend against doing so for the reasons given below.*
 
 > [!NOTE]
 > This article isn't relevant to *server-side* routing, such as in an Express-based web application.
 
-#### Problems with SPAs and the Office dialog API
+#### Problems with SPAs and the Office Dialog API
 
 The Office dialog box is in a new window with its own instance of the JavaScript engine, and hence it's own complete execution context. If you pass a route, your base page and all its initialization and bootstrapping code run again in this new context, and any variables are set to their initial values in the dialog box. So this technique downloads and launches a second instance of your application in the  box window, which partially defeats the purpose of an SPA. In addition, code that changes variables in the dialog box window doesn't change the task pane version of the same variables. Similarly, the dialog box window has its own session storage (the [Window.sessionStorage](https://developer.mozilla.org/docs/Web/API/Window/sessionStorage) property), which isn't accessible from code in the task pane. The dialog box and the host page on which `displayDialogAsync` was called look like two different clients to your server. (For a reminder of what a host page is, see [Open a dialog box from a host page](dialog-api-in-office-add-ins.md#open-a-dialog-box-from-a-host-page).)
 
@@ -145,4 +160,9 @@ So, if you passed a route to the `displayDialogAsync` method, you wouldn't reall
 Instead of passing a client-side route to the `displayDialogAsync` method, we recommend that you do one of the following:
 
 - If the code that you want to run in the dialog box is sufficiently complex, create two different SPAs explicitly; that is, have two SPAs in different folders of the same domain. One SPA runs in the dialog box and the other in the dialog box's host page where `displayDialogAsync` was called.
-- In most scenarios, only simple logic is needed in the dialog box. In such cases, your project will be greatly simplified by hosting a single HTML page, with embedded or referenced JavaScript, in the domain of your SPA. Pass the URL of the page to the `displayDialogAsync` method. While this means that you are deviating from the literal idea of a single-page app; you don't really have a single instance of an SPA when you are using the Office dialog API.
+- In most scenarios, only simple logic is needed in the dialog box. In such cases, your project will be greatly simplified by hosting a single HTML page, with embedded or referenced JavaScript, in the domain of your SPA. Pass the URL of the page to the `displayDialogAsync` method. While this means that you are deviating from the literal idea of a single-page app; you don't really have a single instance of an SPA when you are using the Office Dialog API.
+
+## See also
+
+- [Use the Office Dialog API in Office Add-ins](dialog-api-in-office-add-ins.md)
+- [Handle errors and events in the Office dialog box](dialog-handle-errors-events.md)
