Mean in green
I'm Kevin. I live in Salem, Mass with my wife and little boy and I build software.

Adding help text to your Drupal forms using the Popups API

Tuesday Jul 14, 2009

It seems fairly often that I put links into Drupal help text. It's a great way to show some extended descriptions or direct people to administrative options. The only annoying thing is that it really disrupts the UX. If you are entering a new node, you risk leaving an unsaved form. If you use target="_blank" then you risk confusion by having multiple windows open. So, after reading Gábor's post on D7UX overlays I decided to try out the Popups API module to solve this annoying problem.

So, now I am absolutely in love with the Popups API. It provides a great way to show contextual help and even let users execute administrative forms without losing their place. For example, I've run into a few situations where I'm using a CCK nodereference field and thought it would be awesome to create the referenced node without leaving the /node/add form. Now it becomes simple - the Popups API allows you to create an elegant javascript popup that doesn't have a negative effect on the UX. The popup can contain any page content on your site - a new node/add form, a custom page, etc. If you want to get crazy, you can even set up the popups to refresh or effect the parent page.

For example click here to leave a comment. [Planet Drupal readers will have to click through to my site to see this example]

The installation isn't too bad, but make sure that you check out the README.txt file that comes with the module. Once you enable the module, you will have to make sure that you have a container <div> around your $content variable in page.tpl.php - this will filter out the extraneous parts of your theme and only show the important parts in the popups. Next you have to specify the selector of that container <div> in your global theme settings. Finally, you need to do one of three things to make it work: 1) enable popup scanning on all pages (located in the admin settings), 2) call popups_add_popups() somewhere in a module callback, 3) add one of the popups classes to your anchor tag. The available popup classes will determine how the popup interacts with the parent page. Again, check out the README.txt for all of the details.

Also, be sure to watch the screencast on the Popups API project page to really see how cool this module is. You can use these popups to show any number of things. For example, you could create a wiki page that your administrators can edit, then link to that node from help text so that editors can maintain their own help text with notes. You could even build administrative views with bulk operations, or link to a user creation form. If you have ever had someone ask: "can I do this without leaving the page?" then this is a great module for you.

The coolest part is that this doesn't even scratch the surface of what you can do with these popups. It's a very exciting time for Drupal UX and I'm totally excited to see these things find their way into core.