Dr Popup: Or How I learned to stop worrying and love the modal dialog
One of the many pieces of functionality added in SharePoint 2010 was the dialog window, this is a nice little control implemented in JavaScript that allows us to display a “lightbox” style dialog, containing either another page within our site or direct HTML.
This post will explain how to pass information back and forth between the page creating the dialog and the page displayed within that dialog.
Firstly lets take a look at the JavaScript on our calling page. This could be added through any of the normal methods of inserting JavaScript into a SharePoint page.
(function() {
// Use jQuery to wait for the DOM to be ready
$(document).ready(function(){
// Use SharePoint's SOD (script on demand) to wait for SharePoint to be ready
ExecuteOrDelayUntilScriptLoaded(function() {
//Create an options object (valid options properties reference - http://msdn.microsoft.com/en-us/library/ff410058(v=office.14).aspx):
var options = SP.UI.$create_DialogOptions();
options.title = "My dialog";
options.autoSize = true;
options.url = "/pages/myPage.aspx";
//arguments to pass in to dialog (standard anonymous object)
options.args = {
someKey: "Some Value",
someOtherKey: "Some Other Value"
}
//callback to handle the result from the dialog, you process the result of your
//dialog from the origin page.
options.dialogReturnValueCallback = function(result, arguments) {
if (result == SP.UI.DialogResult.OK) {
// Our arguments parameter contains the arguments originally passed to the dialog, so we could
// reference arguments.someOtherKey here for instance and it would contain the value "Some Other Value"
SP.UI.Notify.addNotification("OK Button clicked");
} else if (result == SP.UI.DialogResult.Cancel) {
SP.UI.Notify.addNotification("Cancel button clicked");
}
}
// Create the dialog with options.
SP.UI.ModalDialog.showModalDialog(options);
}, "SP.UI.Dialog.js");
});
})();
As you can see, there are 3 major parts to this, the options object, the args object and the callback.
The options object is created using the SP.UI.$create_DialogOptions() factory, although I have seen people using an empty object without apparent issue.
Into this you set various options affecting the way the dialog is presented, such as title, size and the url to the page to be displayed. A list of available options is posted on MSDN.
The args object is actually a property of the options object, and can be any sort of JavaScript object, be it an anonymous object like in our example above, or a closure, or a data model or anything else you may wish to send. This object will be available within the page shown in your dialog.
The last part is the callback, this is also a property set against the options object, and is a callback method executed when the DialogClose() method is called from within the parent page.
It takes two parameters, the result which should be one of the members of the SP.UI.DialogResult enumeration and the arguments, which can be any kind of variable or object returned from the dialog page.
Additionally in here you can call SP.UI.ModalDialog.RefreshPage() – this method takes a single parameter and is designed to be called using the result value from your callback. This method ensures that the page refreshes if the result is equal to SP.UI.DialogResult.OK
With these three sections we can define how our dialog looks, what data it takes in, and what happens once it is closed and how to process the data that comes back from it.
Lastly the dialog itself is opened using the call to SP.UI.ModalDialog.showModalDialog()
Now lets take a look at the other side of the coin, here’s the JavaScript code to run within the dialog page.
(function() {
// As on the parent page, wait for the DOM and SharePoint to be ready before doing anything.
$(document).ready(function() {
ExecuteOrDelayUntilScriptLoaded(function() {
// retrieve a reference to the page that called us.
var _parent = SP.UI.ModalDialog.get_childDialog();
// If this is false, then chances are you have browsed to the page directly rather than
// loaded it in a modal window.
if (_parent) {
// Pull through the arguments sent to the dialog.
var args = _parent.get_args();
// set a red alert status line with our argument.
var status = SP.UI.Status.addStatus("someKey:", args.someKey);
SP.UI.Status.setStatusPriColor(status, "red");
// Add handlers for our ok and cancel buttons
$("#okButton").click(function() {
// This closes the modal dialog and runs the callback method defined on the parent page.
SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.OK, args);
});
$("#cancelButton").click(function() {
SP.UI.ModalDialog.commonModalDialogClose(SP.UI.DialogResult.Cancel, "cancel clicked");
});
}
}, "SP.UI.Dialog.js");
});
})();
This again is fairly simple, we first of all get a reference to the calling page in the variable _parent. Then if that has been successful we pull in the args object from our options variable above.
Once at this point the world is your oyster, you can use the arguments from the parent page however you wish to display the dialog or interact with your users.
To close the dialog you can use SP.UI.ModalDialog.commonModalDialogClose(). This again takes two parameters, the first should be a member of the SP.UI.DialogResult enumeration, the second can be any object to send back, these map to the variables sent to our callback function above.
Additionally in here I have made use of some of the other neat parts of the SP.UI namespace such as the status bar and notification system. These are beyond the scope of this post but they’re pretty awesome and you should go read about them.
So there we go, by now you should be able to add true SharePoint style dialogs to your pages with minimal effort.
via Chris on SharePoint http://spchris.com/2013/04/dr-popup-or-how-i-learned-to-stop-worrying-and-love-the-modal-dialog/
   SharePoint and Project Server Consultant
This article has been cross posted from spchris.com (original article) |
SharePoint (and Project Server) Shenanigans 