Dialog framework
Another addition in SharePoint 2010 is the Dialog framework. For the most part, this is encapsulated in the functionality exposed by the SP.UI.Dialog and SP.UI.ModalDialog classes. Although the notifications and status bar functionality is included in the SP.js file, the dialog framework code is included in the SP.UI.Dialog.js file. To get IntelliSense support in Visual Studio when writing JavaScript that targets the dialog framework, add the following reference element to the JavaScript file:
Showing a modal dialog is a relatively straightforward affair. First, we create a DialogOptions object, and then we call the showModalDialog method of the SP.UI.ModalDialog object, as this sample shows:
1 | function ShowDialog_Click() { |
8 | dialogReturnValueCallback: SendNotification_Click }; |
9 | var did = SP.UI.ModalDialog.showModalDialog(options); } |
In this sample, we’re redirecting to an Internet page for the sake of simplicity. In a real-world application, we’d create a custom page that implemented the required functionality. In Chapter 9, you’ll see examples of custom dialogs when we build settings pages for service applications.
The important thing to note about the DialogOptions object is the dialogReturnValueCallback property. This contains details of a callback method that will be called when the dialog is closed. In this callback, we can write code to pick up the dialog result and perform any necessary actions. In this simple example, we’ve generated a notification using our notification sample code.
Creating a new dialog page
One of the first things we want to do when using the dialog framework is to create a new page that will form our dialog. As the short sample above shows, a dialog can be any web page. However, for the sake of consistency, we’ll create a dialog that uses the look and feel of other SharePoint 2010 dialogs.
Using Visual Studio 2010, create a new Empty SharePoint Project as shown.
Set the local site to whatever the url is for your SharePoint 2010 dev server and choose the Deploy as farmsolution option.
Currently there is no SPI for creating dialog pages in Visual Studio. I intend to submit one to the
CKSDev project in the near future so hopefully this will be resolved soon. In the meantime we can manually configure a dialog page using the Application Page SPI as shown. Add a new application page named MyTestDialog.aspx.
Visual Studio will automatically add a mapped folder for the %SPROOT%/Template/Layouts folder and will add our new application page in a folder named after our project. So far, so good!
In SharePoint 2010, all system generated dialogs are based on the dialog.master master page that can be found at %SPROOT%/Template/Layouts/Dialog.master. To ensure consistency with other dialogs we’ll use this master page as the basis for our test dialog.
In the MyTestDialog.aspx page, amend the Page tag as follows:
3 | CodeBehind="MyTestDialog.aspx.cs" |
4 | Inherits="ModalDialogSample.Layouts.ModalDialogSample.MyTestDialog" |
5 | MasterPageFile="~/_layouts/dialog.master" %> |
What’s the difference between MasterPageFile and DynamicMasterPageFile?
Notice the use of the MasterPageFile attribute as opposed to the DynamicMasterPageFile attribute that was inserted by default as part of the application page template. The DynamicMasterPageFile attribute can only reference ~masterurl/default.master or ~masterurl/custom.master and provides a mechanism for SharePoint to dynamically alter the master pages that are applied to a page. Since we’re not using this functionality we must use the standard MasterPageFile attribute and a relative path to our dialog.master file.
Since we’ve changed the master page, the content tags present in the application page template will no longer tie up correctly to Placeholder tags in our dialog.master. Delete the default content tags and replace with the following markup:
01 | <asp:Content ID="Content1" |
02 | ContentPlaceHolderID="PlaceHolderDialogHeaderPageTitle" |
03 | runat="server"> My Test Dialog Title </asp:Content> |
04 | <asp:Content ID="Content2" ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server"> |
05 | <SharePoint:CssRegistration ID="CssRegistration1" runat="server" Name="ows.css" /> |
06 | <SharePoint:ScriptLink ID="ScriptLink1" Language="javascript" Name="core.js" runat="server" /> |
07 | <SharePoint:FormDigest ID="FormDigest1" runat="server" /> |
09 | <asp:Content ID="Content3" ContentPlaceHolderID="PlaceHolderDialogImage" runat="server"> |
10 | <img src="/_layouts/images/allcontent32.png" alt="" /> |
12 | <asp:Content ID="Content5" ContentPlaceHolderID="PlaceHolderDialogBodyHeaderSection"runat="server"> |
14 | <asp:Content ID="Content4" ContentPlaceHolderID="PlaceHolderDialogDescription" runat="server"> |
15 | <div id="selectTermDescription" class="none-wordbreak"> |
16 | <table class="ms-dialogHeaderDescription"> |
19 | <td>This is description text for a custom dialog</td> |
25 | <asp:Content ID="Content8" ContentPlaceHolderID="PlaceHolderHelpLink" runat="server"> |
28 | <asp:Content ID="Content6" ContentPlaceHolderID="PlaceHolderDialogBodyMainSection" runat="server"> |
29 | This is the body section of our test dialog |
