sirkitree.net //say it out loud, [sur-ki-tree]

First off, when I talk about popups, I'm NOT talking about popup ads, or popup browser windows, but rather modal windows within the canvas. Techniques like lightbox, greybox, and jQuery UI's Dialog. These give us 'application-like' modal windows within the browser, completely provided by javascript, in order to give our users elegant views of content, sometimes through Ajax.

There have also been Drupal modules whose goals have been to integrate these display techniques and make them easier for us to utilize within our sites (@see Lightbox2, Greybox, jQuery UI). But I think it's safe to say that none of these really scratch the surface of a full-fledged API that allows you to fully integrate these into your site in a... shall I say... 'sexier' way than Popups API.

I'm not going to reiterate what you can simply find for yourself within the README, (yes, that's a popups link!) but I would like to show you a some of the more impressive things you can do with this sexy little beast and why you should use it.

Spice up your login screen

First off, here is the simplest way to accomplish putting something within a popup. We first go to our Popups Setting page and check the 'Scan all pages for popups links.' checkbox.

This will make sure that the popups.js is loaded on every page load on your site, so may not be suitable for high traffic sites, but not to worry! There are other ways to implement popups, we'll get to those.

The second thing is to simply create a link to our user login page and give it the class 'popups' like so: Login
Since popups is loaded, as soon as it sees that this link has the 'popups' class, it's going to attach our behavior to it. The default style sheet also appends a little 'tick' to the link so you can quickly tell that this is a popups link with just a glance. (Note that this is done with css and can be easily subverted).

Now when we sign out of our site, and click our user link, we're now presented with our login form within a popup!

reloadWhenDone option

Now, the previous example isn't quite functional just yet. If you follow these steps and then enter your username and password, the popup simply closes and it seems that nothing at all has happened! You were expecting the login box to go away, or at the least, some sort of confirmation message telling you that you were logged in successfully. But nadda? Hrmph.

It turns out that popups has implemented a very clever (although not fullproof) way of replacing your content area using Ajax with the results of whatever normal action was supposed to happen within what you've placed within that popup. Sound confusing? Well, it's complex, but if you refresh your page, you will indeed see that you are logged in. It's just that the link you clicked effects more that just the content area (setup within your theme settings)

and this poses a problem for instances like this where you need to effect more than the content area. For this, you want to use the 'reloadWhenDone' option. Modify your link to look like this: Login
The page will now reload as soon as you're submit the form.

"But what about symantics?!", you cry. Well there are more than one way to skin this cat. Popups provides two more ways that you can specify where, on what and how your popups should work. Those being popups_add_popups() and hook_popups(). See the README for more information on how to use these. By the way, hook_popups is my favorite. ;)

Skins

Skins are not fully supported yet, but I've created a patch and example on how this can be accomplished, along with using an example skin that will make your popups look just like Facebook's popup style. Check out this issue for more, test it out, and give your feedback there. (@see Popups Skins - Facebook looking popups)