Dialogs are a conventional way of notifying a user or prompting for input. Like them or not, SharePoint uses them a lot, so users are accustomed to them, thus there’s a high chance that you have to develop custom ones.
Fortunately there’s a simple entry point when you construct dialogs: the SP.UI.ModalDialog class. You can construct a dialog many ways, and show it using the showModalDialog function. There are a bunch of options you can pass in, such as the title of the dialog, the url of the content, callback function, etc. Here’s a brief list:
- Title: the title of the dialog. If not specified, the target page’s title will be used. If used with custom html content, then the term ‘Dialog’ will be used.
- x, y, width, height: the position and size of the dialog.
- allowMaximize, showClose: show or hide these buttons, respectively.
- showMaximized, autoSize: note the fantastic naming convention. Showmaximized indicates whether or not to show the dialog “full screen”, autoSize needs no comment.
The remaining properties are more important, so let’s review them here. If you want to use your custom HTML content, then you can pass a DOM element as the html parameter. Now since I mostly use jQuery to generate my HTML markup when it comes to dialogs, here’s a little trick to convert a jQuery object to make it usable for showModalDialog:
var html = “<div>My markup</div>”;
var htmlAsDomElement = $(html).get(0);
More interesting is the dialogReturnValueCallback parameter. You can pass in a function to be called when the user finishes with the dialog. Two parameters will be needed, one for the result (eg. closed, canceled, ok’d) and one for the return value (if any) of the dialog.
For a real hardcore in-depth introduction of SharePoint dialogs, check out this blog post.