Yesterday I blogged about using jQuery to create automatic hot links around certain words in your page text. While working on that demo, I tried to use the jQuery Dialog widget. I ran into some trouble and gave up, but returned to it this morning to see if I could get it working.

Unfortunately things didn't work out too well for me. I ran into more than one issue, but I had some great help from the folks on the jQuery team. I'd like to specifically call out Rey Bengo, Richard Worth, and Scott Jehl for helping me out. Things actually got ridiculously easy after their support, but I figured a blog post may help others as well. So let's get started!

The first thing you have to know about the jQuery UI stuff is that it is not included in your core jQuery download. You have to download a few additional files before you start using the UI items. You can start at the jQuery UI Download page and select either the latest stable release, the preview release, or use the custom downloader. If you are a newbie like me, I strongly urge you to select the preview release. 99% of the trouble I had today went away when I simply switched from the latest stable 1.5.x release to the 1.6 RC. Let me repeat this. Do not download 1.5. Life will come to an end - chaos will reign - and you will pull out what remains of your hair. From what I've been told, 1.6 will be released very shortly (very very shortly apparently), so it's not like your working with a beta copy.

Once you download the zip, the next thing you will notice is that you don't simply have one simple JS file. Instead you have a complete package of JavaScript, CSS, and HTML files. There are two important folders here. The UI folder is your javascript collection. The themes folder is your skins folder. For my example code I took both folders and copied them to my demo:

Alright, so next we will create a very simple html page. I based my code on the dialog documentation page with one big change. Their demo code runs the dialog immediately when the page loads. I think in almost all cases folks will want to show a dialog based on some event. Here is what I came up with:

<html>

<head> <script src="js/jquery.js"></script> <script src="js/ui/ui.core.js"></script> <script src="js/ui/ui.dialog.js"></script> <script> function showDialog(){ $("#example").dialog(); return false; } </script>

</head>

<body>

<p> <a href="" onclick="return showDialog()">Show the Dialog</a> </p>

<div id="example" class="flora" title="This is my title">I'm in a dialog!</div>

</body> </html>

Going through the file, here are some important things to note. The dialog documentation says that the only required file is ui.core.js. That is not true. You also have to include ui.dialog.js. Maybe that's obvious, but I had assumed that ui.core.js simply contained the code for all the widgets. The one and only function, showDialog, demonstrates how easy it is to create the dialog. You point to an existing div and run dialog(). Yeah, that's really hard. Can I still bill by the hour and use jQuery?

Scrolling down, you can see my simply link to run the function, and lastly the actual div for my dialog. This works, and you can see it in action here:

http://www.coldfusionjedi.com/demos/jqueryuitest2/test1.html

But it has a few problems. First off, the dialog is visible on page load. Secondly, the UI leaves a bit to be desired:

So how do we fix this? First off, to make the dialog hidden on load, we can simply add a bit of CSS to it:

<div style="display: none;" id="example" title="This is my title">I'm in a dialog!</div>

To load the default skin, we use a CSS from the themes folder we copied over earlier:

<link rel="stylesheet" href="themes/base/ui.all.css" type="text/css" media="screen">

And that's it! Check out the sexy dialog! It is the most sexiest dialog I've seen in my life. (Ok, I may just be a bit happy that I finally got it working.)

You can see it in action here: http://www.coldfusionjedi.com/demos/jqueryuitest2/test2.html Don't forget you can view source to see the entire page.

None of this worked for when I was using 1.5, so be sure to use the release candidate of 1.6!

Ok, so with things working well now, I decided to go crazy and try to apply a custom theme. I went to ThemeRoller and grabbed one of the presets - Mint Choc. As before, the zip you get is a bit big and may confuse you. (Well, it confused me at first.) After extracting the zip, the folder you want is jquery-ui-themeroller/theme. I renamed theme to mint and put it within my themes folder. I then changed the CSS to

<link rel="stylesheet" href="themes/mint/ui.all.css" type="text/css" media="screen">

and it just plain worked!

You can see this in action here: http://www.coldfusionjedi.com/demos/jqueryuitest2/test3.html

All in all, I'm pretty pleased with the UI stuff, once I got past my brain cramps with it. I seem to remember having similar issues with the core jQuery library as well and I'm over that as well, so maybe it's simply something that I have to get used to.

I'll leave off with one more quick tip from Richard Worth. Remember my trouble with hiding the div on page load? He pointed out that you can also dynamically create dialogs with strings:

$("<div>I'm in a dialog</div>").dialog()

That's pretty slick. I'm not sure if that is documented though. To be honest, I feel a bit weird putting stuff on the page that isn't visible. I'll probably use this form instead.