Modal Dialogs with the ModalDialog Server Control

To use the server ModalDialog dialog control, drop a ModalDialog control onto an ASP.NET page. The dialog displayed in the first figure above is created with the following server side control code:

<ww:ModalDialog ID="MessageBox" runat="server" 
    BackgroundOpacity=".70"
    ContentId="MessageBoxContent" 
    HeaderId="MessageBoxHeader"
    ShadowOpacity=".20" ShadowOffset="8"
    Draggable="true" DragHandleId="MessageBoxHeader"  
    Closable="True" FadeinBackground="True" 
    Style="background: white; display:none;width: 400px;" 
    CssClass="blackborder" >
    
    <div id='MessageBoxHeader' class='gridheader' style="padding:4px">Web Connection</div>
    <div style='padding: 10px;'>
        <div id='MessageBoxContent' style="padding:10px;">
        </div>
        <hr />
        <input id='MessageBoxOk' type='button' value='Close' />
    </div>
    
</ww:ModalDialog>

This creates a Modal Dialog control called MessageBox, which contains a header (MessageBoxHeader) and content (MessageBoxContent) area which are assigned to the control as HeaderId and ContentId respectively. The default template dropped adds styles from westwind.css, but these are not required and can be changed as needed. Basically the control uses templating to create header and content areas and these areas can be assigned text dynamically if you like - or you can simply display the static dialog.

When the control is first dropped it doesn't contain HeaderId and ContentId tags, and it drops the header and content areas without IDs assinged. You'll need to assign the names and Id mappings manually. You'll also want to assign an appropriate style to the dialog header so it stands out and assign an explicit width to the control. The style shown above gets dropped by default: You'll want insure that the control has a solid color background and that it is not initially displayed (display:none) as it's made visible only through the showDialog() activation method.

The content of the control is used as a layout template that displays the HTML of the template. The content can be made up of pure HTML or it can contain ASP.NET server controls.

The content typically should contain:

A dialog header area
A content area
One or two HTML Control buttons to exit the dialog

A ModalDialog server control actually renders by creating ModalDialog client instance and in order to display the modal dialog you need to invoke a method on that client side class. The class is created with the same name as the server side ID - in this case MessageBox. To open the dialog box in a button click you'd do something like this:

<input type="button" value="Show" onclick="MessageBox.show()" />

This displays the dialog as is - IOW, the same way you designed without assigning anything into the content or header areas. If you'd rather display a custom message you can call showDialog like this:

MessageBox.show("Title","This is a custom message");

The client side ModalDialog object has a number of properties which you can also customize via client code. When using the server control it generates an instance of the client control and assigns the server set properties to the client control. You can then further manipulate the client side object settings in your client code.

Controlling the Overlay Background

You can control the overlay used by providing a custom Html element - typically a

- and styling it to your liking. For example the example in the previous topic used a background image of a windsurfer and a blue background. To do this you set up an invisible

in the background:

You then set the OverlayId of the ModalDialog control and now the control uses this element as the background instead of creating the plain black one on the fly.

Button Clicks and the Modal Dialog

If you capture user input or if you have more than one button on the dialog, you'll want to be able to figure out which button has been pressed. For this you can use the ClientDialogHandler property and set it to a function that responds to any click in the dialog. This handler is called on ANY click - not just clicks on buttons. The handler is passed the element that was clicked as the this instance and an event object and an instance of the HoverPanel client class that has .show() and .hide() methods as parameters.

Typically when you create a modal dialog you'll need to have at least one button to close or confirm the dialog and you'll want to implement a handler that checks for specific elements, ids, captions on the button. Here's an example:

function onMessageBox2ClientClick(evt, inst) {
    var btn = this;  // this == element clicked
    var text = $("#txtInputName").val();
    
    if (btn.id == "MessageBox2Ok") {
        if (text == "")
        {
            $("#MessageBox2Message").text("C'mon don't be shy - enter something");
            return false; // don't close
        }
        $("#divNameResult").text("You entered: " + text).show();
        return true;  // close dialog
    }
    if (btn.id == "MessageBox2Cancel") {
        $("#divNameResult").text("You cancelled the dialog").show();
        return true;  // close dialog
    }
    
    // dialog is not closed
    return false;
}

You should have at least one button configured so there's a way to close the dialog, but OnClientDialogClick is optional. If you don't provide it and click either the OkButtonId or CancelButtonId button the dialog is closed.

If you've specified that the dialog is Closable you'll also see a red box in the upper right corner and you can click on the red box to close the dialog. Keep in mind though that this option only closes the dialog and fires no events.

The client handler receives two parameters: A result code (1 (Ok) or 2 (Cancel) for the button number) and an instance of the clicked button so you can read the caption of the button. A handler might look like this:

function mbox_Clicked(Result,button)
{
	if (Result == 1)   // or button.value="Ok"
        // Success
      else
        //  aborted
}

Using the Server Side Show method

In addition to pure client side operation you can also use the server side .Show() method to display modal dialog. Calling .Show() on the server will cause the page to load and immediately display the modal dialog after the client page has completely loaded. This can be useful if you want a server driven dialog box.

If you are using server driven modal dialogs you probably will also want to use Server side button controls to handle submissions and you can easily do that simply by including server side buttons in your content. These buttons will then cause the page to post back immediately. If you do this you typically will not define any client side buttons. A server only driven dialog might look like this:

<ww:ModalDialog ID="MessageBox2" runat="server" 
    ContentId="MessageBox2Content" HeaderId="MessageBox2Content" 
    OverlayId="overlay" BackgroundOpacity=".70"
    DragHandleId="MessageBox2Header" Draggable="true" Closable="true"            
    Style="background: white; display:none;" cssclass="blackborder"
    Width="400px"
>
    <div id='MessageBox2Header' class='gridheader' style="padding:2px;">The Name Game</div>
    <div style='padding: 10px;'>
        <div id='MessageBox2Content'>
        Enter your name:<br />
        <input type="text" style="width:300px;" id="txtInputName" />
        <hr />
        <asp:Button id='MessageBox2Ok' runat="server" Text='Save' />
        <asp:Button id='MessageBox2Cancel' runat="server" Text='Cancel' />
        </div>
    </div>
</ww:ModalDialog>

Notice there are no client buttons and OkButtonId is not defined, so the only way to exit this dialog will be through the ASP buttons which in turn cause a server postback.