Guest Author: Lee Richardson
http://rapidapplicationdevelopment.blogspot.com/

A significant portion of SharePoint 2010’s Web 2.0 look and feel derives from its use of modal popups.  This post deviates briefly from the ASP.Net AJAX Templating discussion to explore how to open remote pages as modal dialogs, how to open dialogs based on local HTML, and how to respond to OK or Cancel events.

Modaling to Another Page

To get started let’s throw an edit icon onto the index cards we’ve built previously that will open a modal dialog:

<div class="userStoryTitle">
    {{ Title }}
    <span class="userStoryButtons" sys:command="select">
        <a href="#" onclick="javascript:openDialog(); return false;">
            <img src="/_layouts/images/edititem.gif" />
        </a>
    </span>
</div>

There’s nothing fancy going on here yet, just a call to an as yet unimplemented openDialog() function.  The result looks like this:

To open an AJAX modal dialog in SharePoint 2010 either specify a remote page to open, or specify an HTML element in the page.  Opening a remote page is a little easier.  The openDialog() function would look like this:

function openDialog() {
	var options = {
		url: "../../Lists/User%20Stories/DispForm.aspx?Id=1",
		width: 800,
		height: 600,
		title: "User Story",
	};
	SP.UI.ModalDialog.showModalDialog(options);
}

Obviously hard coding an id in the url parameter isn’t exactly best practice, but it works for demonstration purposes.  The result looks like this:

This is a useful technique for opening existing SharePoint pages as in the example above or for opening pages as a dialog that a user might also navigate to directly.  However, in our application we want to edit information that is in-memory in the browser (which is where ASP.Net AJAX Templating stores its data).  The showModalDialog() function will support this scenario, but it’s slightly more complicated.

Modaling to Your Own Page

First we’ll need an HTML element that we’re going to pop up.  A first draft might looks like this:

<div id="userStoryDetails">
    Hello World!
</div>

Since the options parameter that we passed to showModalDialog() supports an ‘html’ parameter instead of a ‘url’ parameter it might seem like we could simply retrieve the userStoryDetails element inside of openDialog and pass that to options.  However, there’s a problem with this approach.  By default SharePoint’s showModalDialog() function will destroy the DOM element that are passed to it.  The result is that the dialog can be opened once, but it fails each subsequent time it is opened.

To avoid this behavior we can cache the DOM element in a global variable rather than keeping it as a local variable scoped at the function level.  The code to will look like this:

var userStoryDetails;

Sys.onReady(function () {
    userStoryDetails = document.getElementById("userStoryDetails");
    ...
});

function openDialog() {
    var options = {
        html: userStoryDetails,
        width: 600,
        height: 300,
        title: "User Story",
    };
    SP.UI.ModalDialog.showModalDialog(options);
}

With this code we can close and open the modal dialog multiple times.  The result looks like this:

The only thing we’re missing now is the ability to close the dialog and handle the results.

Goodbye World

Closing the dialog and handling results is also pretty simple.  It takes two steps.  First we’ll need to call commonModalDialogClose() in our popup code and next we’ll implement a callback method that SharePoint will call when the dialog has been closed. 

To call commonModalDialogClose() we can modify the code that we are going to pop up like this:

<div id="userStoryDetails">
  <input
    type="button"
    value="OK"
    onclick="SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, 'Ok clicked'); return false;"
    class="ms-ButtonHeightWidth"
    target="_self"
    />
  <input
    type="button"
    value="Cancel"
    onclick="SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.cancel, 'Cancel clicked'); return false;"
    class="ms-ButtonHeightWidth"
    target="_self"
    />
</div>

Notice the first parmeter to commonModalDialogClose().  It’s a DialogResult.  This parameter is important because our callback method will need to differentiate the ways in which a user could close the dialog.  For instance when a user clicks the X in the upper right of the dialog SharePoint passes DialogResult.cancel for the first parameter. 

The second parameter to commonModalDialogClose() is simply passed through as the second parameter to our handler as we’ll see shortly.

To handle the results of closing the dialog we can pass a function to the dialogReturnValueCallback argument in the options parameter of showModalDialog.  The result would look like this:

function openDialog() {
	var options = {
		html: userStoryDetails,
		width: 800,
		height: 600,
		title: "User Story",
		dialogReturnValueCallback: onDialogClose
	};
	SP.UI.ModalDialog.showModalDialog(options);
}

function onDialogClose(dialogResult, returnValue) {
	if (dialogResult == SP.UI.DialogResult.OK) {
		alert('goodbye world!');
	}
	if (dialogResult == SP.UI.DialogResult.cancel) {
		alert(returnValue);
	}
}

And now we can open and close SharePoint modal dialogs and handle the results.  If needed there are other adjustments we can make to modal dialogs through the options parameter.  For instance X, Y, allowMaximize, showMaximized and showClose.  The documentation is sparse, but hopefully this page on MSDN will eventually be updated with more details.

Summary

This post should provide everything needed for opening dialogs that look like the ones SharePoint uses.  And more importantly it will provide a foundation for the next post in the series in which we will edit user story information using a master-details view inside of a modal popup.

Guest Author: Lee Richardson
http://rapidapplicationdevelopment.blogspot.com/

Lee Richardson is a Senior Software Engineer at Near Infinity Corporation, an enterprise software development and consulting services company based in Reston, Virginia. He is a Microsoft Certified Solution Developer (MCSD), a Project Management Professional (PMP), a Certified SCRUM master and has over ten years of experience consulting for the public and private sector. You can follow Lee on Twitter at @lprichar