Overview
Modal Dialogs are one of the new features provided by SharePoint 2010. It's the dialog framework provided by the JavaScript client object model. Modal Dialogs can fetch data from anywhere and display it over the page. One good feature about the Modal Dialogs is, there won't be any navigation to another page, making the user to stay in the context of the current page. The number of post backs will also be reduced by using modal dialogs. These dialogs are used in a large scale in many of the OOB operations, like creating a page, viewing/editing item properties etc., These dialogs are JavaScript pop up dialogs with an iFrame in which the data is displayed.
Using the Client Object Model
'SP.UI' namespace from the client object model provides a static class 'SP.UI.ModalDialog' with many methods which are used for creating dialogs and controlling their behavior. Basically, for creating a custom modal dialog, we need to call a JavaScript method. This JavaScript call can be added wherever required, may be in a web part canvas, in content editor web part etc.,
Code Snippet
The method 'showModalDialog()' of the 'SP.UI.ModalDialog' class creates the dialog. It requires one parameter of an object called options. This parameter is set with the properties and settings needed for the dialog, like the URL to be opened by the dialog, its title, height & width etc.,
var options ={
url: '/_layouts/spd/welcome.aspx',
title:'Welcome to SharePoint Developers Hub',
width:100,
height:150,
dialogReturnValueCallback: ShowStatus
};
The options object should be prepared with the required attributes for the dialog as shown above. Now this object should be passed to the function 'SP.UI.ModalDialog.showModalDialog()', then a modal dialog is created. Below is the complete code snippet for a demo modal dialog.
<script type="text/javascript">
function ShowWelcomeDialog()
{
var htmlP = document.createElement('p');
var htmlMsg = document.createTextNode('For articles on SharePoint 2010, visit SharePoint Developers Hub - http://www.spdeveloper.co.in');
htmlP.appendChild(htmlMsg);
var options ={
html: htmlP,
title:'Welcome to SharePoint Developers Hub',
width:400,
height:75,
dialogReturnValueCallback: ShowStatus
};
SP.UI.ModalDialog.showModalDialog(options);
}
function ShowStatus(dialogResult, retValue)
{
SP.UI.Notify.addNotification("The dialog is closed");
}
</script>
<a title="Open Dialog" href="javascript:ShowWelcomeDialog();">Open Dialog</a>
In the above snippet, I created an object for options with some properties for the dialog box. I have assigned a call back function to the dialog through 'dialogReturnValueCallback' property. This function gets called when the dialog is closed. After the <script> is closed, I created an anchor tag setting its href attribute to the JavaScript function 'ShowWelcomeDialog()'.
In the callback function for the dialog I have created a simple Notification to be displayed on the page. For getting it into action, paste the above code in a Content Editor Web Part (in HTML View) in a SharePoint page, and on clicking the link a pop up should be opened. This JavaScript function can be called from anywhere (from a webpart, a button on ribbon menu etc., ) based on the requirement.
Different Properties
There are various properties the showModalDialog() method accepts through the options object. Below is the list of these properties
| Property Name | Type | Description |
|---|---|---|
| allowMaximize | boolean (true/false) | Determines the visibility of the maximize button (at top right corner) for the modal dialog |
| args | object | The args property allows us to pass arbitrary properties into our dialog. |
| autoSize | boolean (true/false) | |
| dialogReturnValueCallback | function | This property accepts a callback function which gets executed when the dialog is closed. |
| height | numeric | The height of the dialog |
| html | HTML Element | The HTML to be rendered in the window (when the URL property is not specified) |
| showClose | boolean (true/false) | Determines the visibility of the close button (at top right corner) for the modal dialog |
| showMaximized | boolean (true/false) | If set to true, the dialog will render maximized, ie., it fills the available screen space. |
| title | string | Title of the modal dialog. When no title is specified, the title of the document referred to by the Url property is used instead. |
| url | string | The URL of the page to be shown in the dialog. |
| width | numeric | The width of the dialog to be displayed |
| x | numeric | Specifies the starting position from the left, where the dialog is to be rendered |
| y | numeric | Specifies the starting position from the bottom, where the dialog is to be rendered |
The URL for the modal dialog can be anything, a publishing page or application page etc., We can close the dialog using the function 'commonModalDialogClose()' method of the SP.UI.ModalDialog class. There might be scenarios where we need to close the dialog through code behind (like in the click event of a Button), then pass the following JavaScript through the response object to close the dialog.
this.Page.Response.Clear();
this.Page.Response.Write("<script type=\"text/javascript\">window.frameElement.
commonModalDialogClose(1, 'Success');</script>");
this.Page.Response.End();
So, for creating a modal dialog we need to call a JavaScript function (it's mostly specified in the anchor tag's href attribute). By following this approach, we are creating modal dialogs which lack accessibility. What if the end user disables JavaScript? This anchor tag will not open the dialog. I have written an article on creating accessible modal dialogs, which you can go through once you are comfortable with creating basic dialogs.