jQuery UI Dialog – Tricks for New Players

There are a number of good dialog plugins for jQuery out there.  I’ve looked at Facebox, SimpleModal most recently.  But there’s really no need to include additional overhead into your scripts and possibly start reinventing the wheel if all you need is literally a dialog popup window.

jQuery UI comes with an incredibly simple to use dialog control (among others) straight “out-of-the-box”.  I’m going to look at how to include it in my own solution and what some of the behaviours are that can cause a great deal of head-scratching for the uninitiated.

jQuery UI Dialog

If you haven’t already, have a look at jQuery UI; in particular the ThemeRoller utility.  Play around with some styles and download a theme (or just download one of the many pre-baked ones available). I’m going to gloss over the part about how to actually implement the dialog fairly quickly – there are two tricks that I want to hit on in more detail afterwards: a design consideration for .Net developers and a native behavioural attribute that you should be aware of when working with the UI dialog.

Engaging in Meaningful Dialog

Creating a dialog with jQuery UI is incredibly straight-forward. I need only one element and two attributes: the ID and Title. Let’s look at the “out-of-the-box” example provided with your ThemeRoller download:

<div id="dialog" title="Dialog Title">
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</div>

This block will form the entire dialog. The element is the dialog container and everything else within it is defined by your own individual requirements. The title bar of the dialog retrieves its text from, appropriately, the title attribute of the element.

$('#dialog').dialog();

<p><a href="#" id="dialog_link" class="ui-state-default ui-corner-all"><span class="ui-icon ui-icon-newwin"></span>Open Dialog</a></p>

Technically, we don’t need a lot of that extra fluff. This would work just as happily:

<p id="dialog_link">Open Dialog</p>

All we need is one last item of jQuery:

$('#dialog_link').click(function(){
		$('#dialog').dialog('open');
		return false;
	});

So we now have a click event wired up to the element with ID “dialog_link”. You can try this out for yourself now – it should all work just fine (don’t forget to include references to the style sheets).

The Gotcha!

Note the two separate jQuery methods we used here: one to set the actual definition of the dialog and another to set up the events for showing it. The key here is the call for defining the dialog – the initialisation call. The following might seem like a good idea, but will not work:

$('#dialog_link').click(function(){
		$('#dialog').dialog();
		return false;
	});

It is not sufficient just to say “when I click #dialog_link, show #dialog as a dialog”. Why? Because the .dialog() syntax is an init call. When you close that dialog, it’s still there, just hidden! Regardless of what options you place within that initialisation call, remember that it only needs to be initialised once. Wiring an initialisation to the click event means that you will initialise the dialog on that first click and it won’t need initialised again. When you close the dialog, you can’t get it back because you’re trying to call init() again.

So what do we want to do instead?  The best option is to follow the example set in your original download.  Initialise your dialog first (you’ll probably also want to set the “autoopen” option to false) and then wire up the click:

$("#dialog").dialog({ autoOpen: false });
$("#dialog_link").click(function() {
  $("#dialog").dialog("open");
});

That was possibly a rather long-winded explanation, but hopefully a clear one.

Working with .Net

As I mentioned earlier, there is also something to be aware of if you’re using the jQuery UI dialog in a .Net solution.

HTML transformed by jQuery UI

If you have a look at the HTML of your downloaded example, you’ll see that the dialog content appears roughly half-way down our page. Now have a look at this screen grab once the jQuery script has initialised the actual dialog.

You’ll see that the content we had mid-way through our page has been marked up with additional classes and, most importantly, placed at the bottom of the page immediately before the closing tag. Why is this important? Because it also means that any ASP.Net controls you place within this dialog will also appear at the bottom of the page, outside of the page’s tag. This means you won’t be able to get a handle to them on postback.

What’s the solution?  Well, there are two options:

1. Move the elements back to the form, and manually submit when the button is clicked
2. Clone the elements when you create the dialog, then clone the values back, trigger click on the original button (or, if you only have one or two values to post back, simply assign the values to an ASP.Net hidden field control).

Hope that helps and hat-tip to Richard Worth for providing personal input to the user community!