that acts as a window) or single elements like an image that serves as a 'loading' dialog for example.

options
Options is an overloaded parameter that either lets you specify options (see below) or the following action verb:

hide
hides the modal dialog.

msg
Optional message text that is displayed if you provided a contentId in the options.

header
Optional header text that is displayed if you provided a headerId in the options.

asHtml
By default text is assigned as text. Set this parameter to true if you want both header and text to be assigned as HTML.

handler
same as specifying the dialogHandler in the options - provides a hook when anything is clicked inside of the modal element (see below).

Options

The options parameter can be a map of any of these properties (default values are shown):

var opt = { 
    overlayId: "_ModalOverlay",
    contentId: jEl.get(0).id,
    headerId: "",
    backgroundOpacity: .75,
    zIndex: 10000,
    keepCentered: true,
    fadeInBackground: false,
    dialogHandler:null
}

overlayId
Optional ID of the element that is used for an overlay. Set this if you want to style the background like use a custom color or background image. If not specified the default opaque black background is used and an overlay is automatically added to the document.

contentId and headerId
Optional ids of the content and header areas that can be updated as a message and header respectively when passing the msg and header parameters.

zIndex
Determines the zIndex of the element when popped up on top of the content. The overlay will be one below this value. By default the value is large at 10000, which should work just fine for most content. However, if you also use drag and drop it may be necessary to explicitly specify a larger zIndex to force the overlay to the top.

keepCentered
Determines that if the window is resized or scrolled whether the dialog remains centered. True by default.

fadeInBackground
If true causes the background to be slowly faded to the specified opacity.

dialogHandler
A handler that is called when a click occurs on any child elements of the dialog. Use to perform custom operations when the dialog is clicked. (see below).

Simple Modal Popup Display (show content):

$("#imgLoading").modalDialog();   // pops up loading image on transparent background

$("#divCompletedMessage").modalDialog();  // display a fully formatted dialog

Hide Dialog

$("#imgLoading").modalDialog("hide");

Assigning Message Content with options:

You can assign content via the msg and header parameters of modalDialog when the headerId and contentId option parameters are set:

// pass text for messages by providing contentId and headerId
$("#divDialog").modalDialog( 
		{ contentId: "divDialogContent", headerId: "divDialogHeader" },
		"The operation completed successfully",
           "Acme Application");

Note that these parameters can be set only once after which they are cached and retrieved. So only the first call needs to specify contentId and headerId.

Static Generic Message Display

You can also create a generic 'MessageBox' that doesn't require any pre-existing elements. This version creates the elements - a header, content and buttons for you on the fly and displays the dialog. The static $.modalDialog function has this signature:

The code to implement this looks like this:

function GenericButtonClick() {            
    $.modalDialog("This dialog is generic, was created on the fly and requires no page elements.",
                   "Generic Modal Dialog ",
                   ["OK", "Cancel", "Otherwise"],
                   function() {
                       var div = $("#divGenericButtonResult"); // display result here
                       var txt = $(this).val(); // grab the button's caption                               
                       if (txt == null)
                           return false; // don't close

                       div.text("You clicked on: " + txt).show();
                       
                       return true; // close the dialog 
                   }, false);
}

Handling Result Messages based on Clicks

By default all click events on buttons or links cause the dialog to close. You can hook the dialogHandler property with an optional event handler that responds to these clicks. Assuming you have a 'dialog' element that contains a couple of buttons (btnOk and btnCancel) you might do:

$("#divDialog").modalDialog( 
                { dialogHandler: function(e, inst) { 
                    // this = button or link clicked
                    if (this.id == "btnOk") {
                       showStatus("thank you for your feedback");    
                    }
                    if (this.id == "btnCancel")
                       return false;  // dialog is not closed
                    
                    // *** dialog closes (default)
                    return true;
                });

The handled is called with the jQuery event object and the hoverpanel instance as a parameter and this set to the element that caused the click (ie. the button or link). The HoverPanel instance has show() and hide() methods that can be used to manually show/hide the dialog.

The handler should return false if it wants the dialog to not be closed. Any other value causes the dialog to be closed.