Use the Office dialog API in Office Add-ins

You can use the Office dialog API to open dialog boxes in your Office Add-in. This article provides guidance for using the dialog API in your Office Add-in.

Note

For information about where the Dialog API is currently supported, see Dialog API requirement sets. The Dialog API is currently supported for Word, Excel, PowerPoint, and Outlook.

A primary scenario for the Dialog API is to enable authentication with a resource such as Google, Facebook, or Microsoft Graph. For more information, see Authenticate with the Office dialog API after you are familiar with this article.

Consider opening a dialog box from a task pane or content add-in or add-in command to do the following:

  • Display sign in pages that cannot be opened directly in a task pane.
  • 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.

Note

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, see the Excel Add-in JavaScript SalesTracker sample.

The following image shows an example of a dialog box.

Add-in commands

Note that the dialog box always opens in the center of the screen. The user can move and resize it. The window is nonmodal--a user can continue to interact with both the document in the host Office application and with the page in the task pane, if there is one.

Open a dialog box from a host page

The Office JavaScript APIs include a Dialog object and two functions in the Office.context.ui namespace.

To open a dialog box, your code, typically a page in a task pane, calls the displayDialogAsync 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:

Office.context.ui.displayDialogAsync('https://myAddinDomain/myDialog.html');

Note

  • The URL uses the HTTPS protocol. This is mandatory for all pages loaded in a dialog box, not just the first page loaded.
  • The dialog box's domain is the same as the domain of the host page, which can be the page in a task pane or the function file of an add-in command. This is required: the page, controller method, or other resource that is passed to the displayDialogAsync method must be in the same domain as the host page.

Important

The host page and the resource that opens in the dialog box must have the same full domain. If you attempt to pass displayDialogAsync a subdomain of the add-in's domain, it will not work. The full domain, including any subdomain, must match.

After the first page (or other resource) is loaded, a user can use links or other UI to navigate to any website (or other resource) that uses HTTPS. You can also design the first page to immediately redirect to another site.

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:

Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html', {height: 30, width: 20});

For a sample add-in that does this, see Office Add-in Dialog API Example.

Set both values to 100% to get what is effectively a full screen experience. (The effective maximum is 99.5%, and the window is still moveable and resizable.)

Note

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, she cannot 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, 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.

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:

Office.context.ui.displayDialogAsync('https://myDomain/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 is not running in Office on the web, the displayInIframe is ignored.

Note

You should not use displayInIframe: true if the dialog box will at any point redirect to a page that cannot be opened in an iframe. For example, the sign in pages of many popular web services, such as Google and Microsoft account, cannot be opened in an iframe.

Send information from the dialog box to the host page

The dialog box cannot communicate with the host page in the task pane unless:

  • The current page in the dialog box is in the same domain as the host page.
  • The Office JavaScript API library is loaded in the page. (Like any page that uses the Office JavaScript API library, script for the page must assign a method to the Office.initialize property, although it can be an empty method. For details, see Initialize your Office Add-in.)

Code in the dialog box uses the messageParent function to send either a Boolean value or a string message to the host page. The string can be a word, sentence, XML blob, stringified JSON, or anything else that can be serialized to a string. The following is an example:

if (loginSuccess) {
    Office.context.ui.messageParent(true);
}

Important

  • The messageParent function can only be called on a page with the same domain (including protocol and port) as the host page.
  • The messageParent function is one of only two Office JS APIs that can be called in the dialog box.
  • The other JS API that can be called in the dialog box is Office.context.requirements.isSetSupported. For information about it, see Specify Office hosts and API requirements. However, in the dialog box, this API isn't supported in Outlook 2016 one-time purchase (that is, the MSI version).

In the next example, googleProfile is a stringified version of the user's Google profile.

if (loginSuccess) {
    Office.context.ui.messageParent(googleProfile);
}

The host page must be configured to receive the message. You do this by adding a callback parameter to the original call of displayDialogAsync. The callback assigns a handler to the DialogMessageReceived event. The following is an example:

var dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html', {height: 30, width: 20},
    function (asyncResult) {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

Note

  • Office passes an AsyncResult object to the callback. It represents the result of the attempt to open the dialog box. It does not represent the outcome of any events in the dialog box. For more on this distinction, see Handle errors and events.
  • The value property of the asyncResult is set to a Dialog object, which exists in the host page, not in the dialog box's execution context.
  • The processMessage is the function that handles the event. You can give it any name you want.
  • The dialog variable is declared at a wider scope than the callback because it is also referenced in processMessage.

The following is a simple example of a handler for the DialogMessageReceived event:

function processMessage(arg) {
    var messageFromDialog = JSON.parse(arg.message);
    showUserName(messageFromDialog.name);
}

Note

  • Office passes the arg object to the handler. Its message property is the Boolean or string sent by the call of messageParent in the dialog box. In this example, it is a stringified representation of a user's profile from a service such as Microsoft account or Google, so it is deserialized back to an object with JSON.parse.
  • The showUserName implementation is not shown. It might display a personalized welcome message on the task pane.

When the user interaction with the dialog box is completed, your message handler should close the dialog box, as shown in this example.

function processMessage(arg) {
    dialog.close();
    // message processing code goes here;
}

Note

  • The dialog object must be the same one that is returned by the call of displayDialogAsync.
  • The call of dialog.close tells Office to immediately close the dialog box.

For a sample add-in that uses these techniques, see Office Add-in Dialog API Example.

If the add-in needs to open a different page of the task pane after receiving the message, you can use the window.location.replace method (or window.location.href) as the last line of the handler. The following is an example:

function processMessage(arg) {
    // message processing code goes here;
    window.location.replace("/newPage.html");
    // Alternatively ...
    // window.location.href = "/newPage.html";
}

For an example of an add-in that does this, see the Insert Excel charts using Microsoft Graph in a PowerPoint add-in sample.

Conditional messaging

Because you can send multiple messageParent calls from the dialog box, but you have only one handler in the host page for the DialogMessageReceived event, the handler must use conditional logic to distinguish different messages. For example, if the dialog box prompts a user to sign in to an identity provider such as Microsoft account or Google, it sends the user's profile as a message. If authentication fails, the dialog box sends error information to the host page, as in the following example:

if (loginSuccess) {
    var userProfile = getProfile();
    var messageObject = {messageType: "signinSuccess", profile: userProfile};
    var jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
} else {
    var errorDetails = getError();
    var messageObject = {messageType: "signinFailure", error: errorDetails};
    var jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Note

  • The loginSuccess variable would be initialized by reading the HTTP response from the identity provider.
  • The the implementation of the getProfile and getError functions are not not shown. They each get data from a query parameter or from the body of the HTTP response.
  • Anonymous objects of different types are sent depending on whether the sign in was successful. Both have a messageType property, but one has a profile property and the other has an error property.

The handler code in the host page uses the value of the messageType property to branch as shown in the following example. Note that the showUserName function is the same as in the previous example and showNotification function displays the error in the host page's UI.

function processMessage(arg) {
    var messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "signinSuccess") {
        dialog.close();
        showUserName(messageFromDialog.profile.name);
        window.location.replace("/newPage.html");
    } else {
        dialog.close();
        showNotification("Unable to authenticate user: " + messageFromDialog.error);
    }
}

Note

The showNotification implementation is not shown in the sample code provided by this article. For an example of how you might implement this function within your add-in, see Office Add-in Dialog API Example.

Pass information to the dialog box

Sometimes the host page needs to pass information to the dialog box. You can do this in two primary ways:

  • Add query parameters to the URL that is passed to displayDialogAsync.
  • Store the information somewhere that is accessible to both the host window and dialog box. The two windows do not share a common session storage, but if they have the same domain (including port number, if any), they share a common Local Storage.*

Note

* There is a bug that will effect your strategy for token handling. If the add-in is running in Office on the web in either the Safari or Edge browser, the dialog box and task pane do not share the same Local Storage, so it cannot be used to communicate between them.

Use local storage

To use local storage, your code calls the setItem method of the window.localStorage object in the host page before the displayDialogAsync call, as in the following example:

localStorage.setItem("clientID", "15963ac5-314f-4d9b-b5a1-ccb2f1aea248");

Code in the dialog box reads the item when it's needed, as in the following example:

var clientID = localStorage.getItem("clientID");
// You can also use property syntax:
// var clientID = localStorage.clientID;

Use query parameters

The following example shows how to pass data with a query parameter:

Office.context.ui.displayDialogAsync('https://myAddinDomain/myDialog.html?clientID=15963ac5-314f-4d9b-b5a1-ccb2f1aea248');

For a sample that uses this technique, see Insert Excel charts using Microsoft Graph in a PowerPoint add-in.

Code in your dialog box can parse the URL and read the parameter value.

Important

Office automatically adds a query parameter called _host_info to the URL that is passed to displayDialogAsync. (It is appended after your custom query parameters, if any. It is not appended to any subsequent URLs that the dialog box navigates to.) Microsoft may change the content of this value, or remove it entirely, in the future, so your code should not read it. The same value is added to the dialog box's session storage. Again, your code should neither read nor write to this value.

Note

There is now in preview a messageChild API that the parent page can use to send messages to the dialog just as the messageParent API described above sends messages from the dialog. For more about it, see Passing data and messages to a dialog box from its host page. We encourage you to try it out, but for production add-ins, we recommend that you use the techniques described in this section.

Closing the dialog box

You can implement a button in the dialog box that will close it. To do this, the click event handler for the button should use messageParent to tell the host page that the button has been clicked. The following is an example:

function closeButtonClick() {
    var messageObject = {messageType: "dialogClosed"};
    var jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

The host page handler for DialogMessageReceived would call dialog.close, as in this example. (See previous examples that show how the dialog object is initialized.)

function processMessage(arg) {
    var messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "dialogClosed") {
       dialog.close();
    }
}

Even when you don't have your own close-dialog UI, an end user can close the dialog box by choosing the X in the upper-right corner. This action triggers the DialogEventReceived event. If your host pane needs to know when this happens, it should declare a handler for this event. See the section Errors and events in the dialog box for details.

Advanced topics and special scenarios

Use the Dialog API to show a video

See Use the Office dialog box to show a video.

Use the Dialog APIs in an authentication flow

See Authenticate with the Office dialog API.

Using the Office dialog API with single-page applications and client-side routing

SPAs and client-side routing need to be handled with care when you are using the Office dialog API. Please see Best practices for using the Office dialog API in an SPA.

Error and event handling

See Handling errors and events in the Office dialog box.

Next steps

Learn about gotchas and best practices for the Office dialog API in Best practices and rules for the Office dialog API.