Using the Drupal overlay for non-admin paths

Drupal 7 ships with a module called 'Overlay', it is installed by the standard install profile and actually is pretty great for most people. If you don't know what I'm talking about then, it's this:

It's basically a nice wrapper around the jQueryUI Dialog component and has some nice features, like keeping the URL fragment up to date with the page being viewed in the overlay. This means you can create a link that goes to a page, and then opens the overlay automatically, it also means that it doesn't break the 'back button'. Using the drupal overlay it's very simple to get a page to open up in a modal popup, wouldn't it be great if you could just get one of your pages to open up in the overlay?

###Admin paths

To get a page to appear in the overlay you simply tell the Overlay module the path of that page. Then whenever there is a link to that page, it'll be automatically turned into a link that will open in an overlay. Neat? No.

It turns out that the way that you define a path as 'overlay-able' is to define it as an admin path:

function hook_admin_paths() {
  $paths = array(
    'mymodule/*/add' => TRUE, 
    'mymodule/*/edit' => TRUE,
  );
  return $paths;
}

Then all the Overlay module magic will apply to any link to mymodule/123/add or my module/456/edit. However, we've just defined those paths as admin paths, which means that they will also appear using the admin theme. Lame!

What we need is a way to define paths that should just use the overlay, but not be an admin path, well there is!

Overlay paths

The Overlay paths module provides a new hook for you to use to define overlay paths. This hook looks familiar:

function hook_overlay_paths() {
  $paths = array(
    'mymodule/*/add' => TRUE,
    'mymodule/*/edit' => array(
      'width' => 500,
    ),
  );
  return $paths;
}

This will do the same as the hook_admin_paths earlier in that paths defined here will appear in the overlay, but the Overlay paths module will do some Drupal trickery to make the paths not use the admin theme.

Notice that we can also specify a width here, the overlay paths module allow us to set additional settings about our pages when they appear in the overlay, such as the width of the page.

So using this we can very easily¹ make the user registration form appear in the overlay, with a width of 400px:

Cool!

Getting started

The Overlay paths module is really designed for module developers to use, rather than site builders, you need to define a hook to really use it. However, as a demonstration and possibly useful way to get started for site builders, it is bundled with an 'Example' module that provides a UI for defining new paths to appear in the overlay, you can even define the widths for those paths.

Alternatives

There are of course, alternatives to using the overlay for non-admin paths, notably the [ctools module][ctools] provides its 'modal', which can be seen in action in the views 3 UI and in page manager among other places. It can give you much more control over when and how it appears, but lacks some of the features of the overlay, like breaking the 'back button' and also structurally the content in the modal is part of the page, whereas the overlay brings new content in using an iframe. This means that the modal can 'leak' CSS and JavaScript into the host page, changing the styling there unintentionally.

There are also a number of other modal popup frameworks in contrib for Drupal which you may want to use.