The dialog platform was introduced in SharePoint 2010 as a way to keep users in context when working with items in lists and document libraries. At its basics, the dialog platform is an HTML IFrame that is loaded on top of a page. The dialog can contain any Web page stored on the Web front end or any HTML specified in a call to the APIs. As a developer you can also leverage the dialog platform. This post will provide a quick overview of this platform.

Hiding User Interface Elements in a Dialog

Dialog pages are accessed both inside a dialog as well as outside of a dialog. Given that these contexts can vary, there is a built-in CSS class used to hide elements when hosted inside a dialog. The s4-notdlg CSS class specifies that an element will not appear in a dialog. This is useful for UI elements that do not work well inside of a dialog but look fine when the page is loaded outside of the dialog. To hide an element that should not be inside a dialog, you simply set the CSS class either using the class attribute for regular HTML elements or the CssClass attribute on .NET controls. Here are a few examples:

Dialog Platform APIs

The dialog platform APIs are all written in EcmaScript (JavaScript, JScript). The API lives in the SP.UI namespace and particularly in the ModalDialog class. The ModalDialog class contains multiple functions that are used to work with dialogs. I’m only going to cover the two most common methods in this post. There is also an API used to define how the dialog behaves.

Specifying Dialog Options

There are two ways to define how a dialog behaves—a specific SP.UI.DialogOptions object or simply a data structure that defines the options. Both of these methods produce the same results. I will illustrate both of these later in this post. For now, here is a table of the available dialog options.

Option	Description
title	Optional string. Contains the title of the dialog.
url	Optional string. Contains the URL of the page that appears in the dialog. If url is specified when html is specified, the url will be used. Either url or html must be specified.
html	Optional string. Contains the HTML of the page that appears in the dialog. If html is specified when url is specified, the url will be used. Either url or html must be specified.
x	Optional integer. Contains the x-offset of the dialog. Works like the CSS left value.
y	Optional integer. Contains the y-offset of the dialog. Works like the CSS top value.
width	Optional integer. Contains the width of the dialog. If width is not specified, it will be autosized by default. If autosizing is off, the default value  of 768 is used for the width.
height	Optional integer. Contains the height of the dialog. If height is not specified, it will be autosized by default. If autosizing is off, the default value of 576 is used for the height.
allowMaximize	Optional Boolean. Contains a Boolean that specifies if the dialog can be maximized. When this is true, the maximize button is shown; otherwise, the maximize button is not shown.
showMaximized	Optional Boolean. Contains a Boolean that specifies if the dialog opens in a maximized state. When this is true, the dialog opens maximized; otherwise, the dialog is opened at (1) the requested sized if specified, (2) the default size, or (3) the autosized size.
showClose	Optional Boolean. Contains a Boolean that specifies if the close button appears on the dialog.
autoSize	Optional Boolean. Contains a Boolean that specifies if the dialog platform handles dialog sizing.
dialogReturnValueCallback	Optional function. Contains the return callback function. The function takes two parameters—a dialogResult of type SP.UI.DialogResult and a returnValue that contains any data contains by the dialog.
args	Optional object. Contains an object or other data that are passed to the dialog.

 

Now, I’ll go over the primary APIs for opening and closing a dialog.

showModalDialog(DialogOptions options)

This method displays a dialog based on the options parameter. The parameter can be built in two ways, which are illustrated below.

//Using the DialogOptions class.var options = SP.UI.$create_DialogOptions();options.title = "My Dialog Title";options.width = 400;options.height = 600;options.url = "/_layouts/DialogPage.aspx";SP.UI.ModalDialog.showModalDialog(options);//Using a generic object.var options = {    title: "My Dialog Title",    width: 400,    height: 600,    url: "/_layouts/DialogPage.aspx" };SP.UI.ModalDialog.showModalDialog(options);

commonModalDialogClose(DialogResult dialogResult, Object returnVal)

This method closes the most recently opened dialog with the specified dialog result and an object that contains return values for the dialogReturnValueCallback method.

RefreshPage(DialogResult dialogResult)

This method is intended to be passed as a callback function when opening a dialog. It will refresh the parent page when the dialog is closed.

Methods Inside a Dialog

When you’re inside a dialog, there are alternate methods to operate on the dialog. The APIs are created dynamically to increase performance and keep from loading the entire SP.UI.Dialog.js file since it is loaded in the parent window. The following methods and properties are available using the window.frameElement class.

window.frameElement.commonModalDialogClose

Closes the most recently opened dialog.

window.frameElement.cancelPopUp

Closes the dialog and passes SP.UI.DialogResult.Cancel as the result.

window.frameElement.commitPopup

Closes the dialog and passes SP.UI.DialogResult.OK as the result.

window.frameElement.overrideDialogResult

Overrides the dialog result that is passed back to the parent window.

window.frameElement.navigateParent

Navigates the parent window to the specified URL.

window.frameElement.dialogArgs

Contains the arguments passed into the dialog.

window.frameElement.autoSize

Autosizes the dialog.