A problem with Windows SharePoint Services 3.0 was that every time a user clicked something, they were redirected to another page. Many users found this confusing; especially when they didn’t know what to do on the new page—should they click the browser’s back button or the Cancel button on the new page?
Microsoft has rewritten the interface to display information in a modal window by using Ajax so that the user never really leaves the page to complete most tasks. This reduces the number of page refreshes and round trips to the server. Now, much of the information that was displayed on page redirects and dialog boxes is displayed in the modal window, called modal dialogs. These are created by using the modal dialog framework that creates an overlay with a grayed background and provides the code that is needed for the different browsers that SharePoint supports.
Note
You can find information about the browsers that SharePoint 2010 supports in Chapter 2, and Chapter 4.
The modal dialog is really a <DIV> tag that is embedded in the SharePoint page, and the technology involved in creating modal dialog is part of the SharePoint 2010 Client Object Model (COM).
Tip
INSIDE OUT The three SharePoint 2010 COMs
You can use the SharePoint 2010 COM to create client applications for SharePoint. There are three COMs, JavaScript, Silverlight and ASP.NET CLR. If you use JavaScript and JQuery, use the JavaScript object model; for Silverlight, use the Silverlight object model; and if you are creating PowerShell, command prompt, and Windows Presentation Foundation (WPF) applications, use the ASP.NET CLR object model. More information about COM is available in Part Three: Client Models of the Patterns and Practices of “Developing Applications for SharePoint 2010,” which you can find at http://msdn.microsoft.com/en-us/library/ff770300.aspx. You can also obtain this in print and eBook from Microsoft Press at http://oreilly.com/catalog/9780735656086.
You can pass parameters to the modal dialogs as you would to a real browser window, and as far as users are concerned, it can be thought of as another page. You can create modal windows by using Visual Studio’s design window. You can also create them dynamically from your own code by using JavaScript and HTML tags.
The namespace in the object model that is used to create modal dialogs is SP.UI.ModalDialog, which takes one parameter, an options dialog object. There are many ways of using the modal dialog, some of which are described next.
Note
You can prevent the use of modal dialogs for forms on a list-by-list or library-by-library basis. On the List Settings page, under General Settings, click Advanced Settings. On the Advanced Settings page, scroll to the bottom of the page, and then in the Dialogs section, select No. The New, Edit, and Display forms will no longer be displayed in a dialog. The user will be redirected to the full page view for these forms.
The modal dialog can be defined inline by creating a <DIV> tag within your webpage and then placing the content that you want to see in the modal dialog within the <DIV> tags. Configure the <DIV> tag so that when the page is displayed the contents within the <DIV> tag are not displayed, similar to the following code:
<div id="SPFIO_div" style="display:none; padding:5px"> Modal dialog content Click button to close dialog <input type="button" value="Close" onclick="closeSPFIO_Dialog()" /> </div>
Next, create two JavaScript functions, one to display the contents within the <DIV> tags in a modal dialog, and then a function to close the model dialog:
<script language="ecmascript" type="textecmascript" >
var vSPFIO_dialog;
function showSPFIO_Dialog(){
var vSPFIO_div = document.getElementById("SPFIO_div");
SPFIO_div.style.display = "block";
var vOptions = { html:vSPFIO_div, width: 150, height: 150};
vSPFIO_dialog = SP.UI.ModalDialog.showModalDialog(vOptions);
}
function closeSPFIO_Dialog() {
SPFIO_dialog.close();
}
</script>To call the JavaScript showSPFIO_dialog function, place code elsewhere on the page or as a command on the ribbon. You can also dynamically create the HTML that you want to display in the modal dialog by assigning it to the html attribute in the options parameter, for example:
html: '<html><body>dynamic content</body></html>'
You can display an image or a webpage by replacing the code within the showSPFIO_Dialog function with the following code:
var vOptions = {
url: 'http://wideworldimporters/SitePages/NewPage.aspx',
title: 'SPFIO New Page',
allowMaximize: true,
showClose: true,
width:200,
height:200
};
vSPFIO_dialog = SP.UI.ModalDialog.showModalDialog(vOptions);The dialog options object has a number of properties such as the allowMaximize property that specifies whether to display the Maximize icon in the upper-right corner. The showClose property specifies whether to display the close icon in the upper-right corner, and if you want the dialog to fill all the space in the window, set the showMaximized property to true. If you do not specify the width and or height property, the dialog is automatically sized to fit the browser window.
On the dialog options object you can register a function, known as a callback function, that is called when the modal dialog is closed. Thereby, you can perform any actions that are needed, including retrieving the result of the dialog. You register the callback function by using the dialogReturnValueCallback options property, as shown in the following code:
<script language="ecmascript" type="textecmascript" >
function showSPFIO_Dialog() {
var vOptions = SP.UI.$create_DialogOptions();
vOptions.url = "http://wideworldimporters/SitePages/NewPage.aspx";
vOptions.width = 150;
vOptions.height = 400;
vOptions.dialogReturnValueCallback =
Function.createDelegate(null, SPFIO_callback);
SP.UI.ModalDialog.showModalDialog(vOptions);
}
function SPFIO_callback(result, target) {
if(result === SP.UI.DialogResult.OK)
{
alert("OK clicked");
}
}
</script>The callback function consists of two parameters, result and target. The result parameter is a number that contains one of the SP.UI.DialogResult enumerations. You use the target parameter to pass values from the page displayed in the modal dialog and the callback function. For example, the NewPage.aspx could contain a text box, and when the user clicks the OK button on the NewPage.aspx, then the following code would be called, returning the result and target parameters:
SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, textBoxValue);
Note
MSDN offers a How-To topic called “How to: Display a Page as a Modal Dialog box” which you can read at http://msdn.microsoft.com/en-us/library/ff798390.aspx.