I have set up a jQuery.popeye site where you can find documentation and demos.

You will also find links to a new feature request forum and bug tracker there. Hope you like the new stuff!

Writing the history of single-page image galleries on the web, one could start like this:

In the beginning, there was nothing. And the Developer said: “Let there be pop-ups!” And the Users saw that pop-ups were bad…

Then came Lightbox. Finally, an unobtrusive script allowed to display enlarged versions of thumbnail images embedded in web pages without leaving that web page or breaking the layout. The “simple” solution was to add a semi-transparent overlay to the page, on which the enlarged image is centered.

Since then, we’ve seen a ton of similar scripts used on an ever-increasing number of websites.

While at first, I, like everyone else, was really enthusiastic about this technique, I have come to see some of the downsides of a lightbox-ish image presentation:

• Lightboxes are usually not consistent with the look & feel of the rest of the website, and
• they still feel like a kind of pop-up, since the image leaves the layer of the web page and opens up a new layer.

Besides – I’m getting tired of seeing the same effect, the same UI controls over and over…

So, while working on a client project in which I at first used a jQuery Lightbox plugin, I ended up dissatisfied with the outcome. I had gone through great length to stir up a consistent look & feel, just to see it vanish under the lightbox overlay.

I wanted something more integrated in the flow of the web page – a box with a small preview image with caption, the possibility to flip through an array of more thumbnails and, of course, to show an enlarged version, all in one place. Lightbox offers that. Moreover, I wanted the box to stay anchored to the page layout and not hovering above it disconnectedly. The way to achieve this was writing a script which would fix one corner of the enlarged image to the exact spot where the thumbnail had been.

After toying around for a while, I decided to put the final outcome into a proper jQuery plugin and see, what other people (you!) think. May jQuery.popeye be of use!

Behavior

The plugin transforms an unoredered list of images into a box displaying only one preview image at a time. The box has controls to skim through the preview images and to enlarge a given image. The box expands to accomodate the enlarged version, while the controls are hidden in full image size mode. A simple click on the image returns the box to its compact state.

The compact box has fixed, automatically calculated dimensions. The widht and height are calculated so that all thumbnail images are cropped to the smallest width and height in the set and centered resulting image area (stage).

This behaviour can be overriden in the plugin options.

I have set up a demo page which best shows the behavior of jQuery.popeye.

Usage

jQuery.popeye degrades gracefully into a scrollable list of thumbnails which link to an enlarged version. The HTML-setup should look like this:

			

			

			
...

Once the plugin has been included in your web page, the popeye(es) can be easily created with the following command:

$(document).ready(function () {
	$('.popeye').popeye();
});

Of course, multiple popeyees can be used together on a single page.

Customization

jQuery.popeye supports a wide range of options. They are, in detail:

Update: These are the options for jQuery.popeye 0.2. The options for the latest version have changed!

To overwrite the default parameters, you can use the following code:

var options = {
	direction:  'right',
	duration:   230,
	stageW:     '200px',
	stageH:     '240px'
}
$('.popeye').popeye(options);

The plugin comes with the mandatory css-file jquery.popeye.css which shouldn’t be altered. Additionally, I have included a second, customizable CSS-file with an example style for you to build upon.

I repeat…

• Get the latest version of jQuery,
• (optional) get the jQuery Easing Plugin,
• see it in action on the demo page,
• get the plugin:

Download jQuery.popeye
from the jQuery Plugin Repository

Considerations

There are still some issues with the first release of jQuery.popeye which I hope to resolve in future versions. They mainly concern the size of the enlarged box (the whole image should stay visible) and the gallery controls (will introduce proper controls to enlarged box).

But for now, your feedback, bug reports, improvements and feature requests are very welcome in the comment section.

“I yam what I yam!” — Popeye