Alternative ways of passing messages to a dialog box from its host page
The recommended way to pass data and messages from a parent page to a child dialog box is with the
messageChild method as described in Use the Office dialog API in your Office Add-ins. If your add-in is running on a platform or host that does not support the DialogApi 1.2 requirement set, there are two other ways that you can pass information to the dialog box:
- Add query parameters to the URL that is passed to
- 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 (the Window.sessionStorage property), but if they have the same domain (including port number, if any), they share a common Local Storage.*
* 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, call the
setItem method of the
window.localStorage object in the host page before the
displayDialogAsync call, as in the following example:
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:
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.
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 (the Window.sessionStorage property). Again, your code should neither read nor write to this value.