Edit

Office.DialogOptions interface

  • Reference
Package:
office

Provides options for how a dialog is displayed.

Properties

asyncContext

A user-defined item of any type that is returned, unchanged, in the asyncContext property of the AsyncResult object that is passed to a callback.
displayInIframe

Determines whether the dialog box should be displayed within an IFrame. This setting is only applicable in Office on the web, and is ignored by other platforms. If false (default), the dialog will be displayed as a new browser window (pop-up). Recommended for authentication pages that cannot be displayed in an IFrame. If true, the dialog will be displayed as a floating overlay with an IFrame. This is best for user experience and performance.
height

Defines the height of the dialog as a percentage of the current display. Defaults to 80%. 250px minimum.
promptBeforeOpen

Determines if the pop-up blocker dialog will be shown to the user. Defaults to true.

true - The framework displays a pop-up to trigger the navigation and avoid the browser's pop-up blocker. false - The dialog will not be shown and the developer must handle pop-ups (by providing a user interface artifact to trigger the navigation).
width

Defines the width of the dialog as a percentage of the current display. Defaults to 80%. 150px minimum.

Property Details

asyncContext

A user-defined item of any type that is returned, unchanged, in the asyncContext property of the AsyncResult object that is passed to a callback.

asyncContext?: any

Property Value

any

displayInIframe

Determines whether the dialog box should be displayed within an IFrame. This setting is only applicable in Office on the web, and is ignored by other platforms. If false (default), the dialog will be displayed as a new browser window (pop-up). Recommended for authentication pages that cannot be displayed in an IFrame. If true, the dialog will be displayed as a floating overlay with an IFrame. This is best for user experience and performance.

displayInIframe?: boolean

Property Value

boolean

height

Defines the height of the dialog as a percentage of the current display. Defaults to 80%. 250px minimum.

height?: number,

Property Value

number

Examples

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog and how to use that handler to close the dialog. The implementation of the processMessage() function is omitted.

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) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

// The following example does the same thing in TypeScript.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult: Office.AsyncResult) => {
        const dialog: Office.Dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

promptBeforeOpen

Determines if the pop-up blocker dialog will be shown to the user. Defaults to true.

true - The framework displays a pop-up to trigger the navigation and avoid the browser's pop-up blocker. false - The dialog will not be shown and the developer must handle pop-ups (by providing a user interface artifact to trigger the navigation).

promptBeforeOpen?: boolean;

Property Value

boolean

width

Defines the width of the dialog as a percentage of the current display. Defaults to 80%. 150px minimum.

width?: number,

Property Value

number

Examples

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog and how to use that handler to close the dialog. The implementation of the processMessage() function is omitted.

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) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

// The following example does the same thing in TypeScript.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult: Office.AsyncResult) => {
        const dialog: Office.Dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
            dialog.close();
            processMessage(arg);
        });
    }
);