jQuery Plugin Tips: ColorBox

ColorBox is described as “A lightweight customizable lightbox plugin for jQuery 1.3+”. As of this writing the ColorBox jQuery plugin is being actively supported as Version 1.3.19 was issued on 8 Dec 2011. It’s an open source work released with the MIT license and it’s one of the top ten jQuery plugins used around the world.

To use ColorBox first download the plugin, unpack the .zip file, and inspect the example directories. The index page in each example folder presents a series of links to slideshows with different features, such as elastic transitions, fade transitions, or using other content types. The colorbox directory contains a minified .js file and a non-minified JScript file.

ColorBox requires that its stylesheet be included in the <head> before its javascript source, which must be included after the javascript library. In the head of an HTML page call colorbox.css, jQuery library, and then any jQuery plugins — in that order. If you don’t call jquery.js before the plugin, nothing happens on the page where you’re wanting to view a lightbox or slideshow. You’ll see a “jQuery is not defined” error if you’re using the Firebug development tool.

We want the webpage to be fully constructed before running any scripts, so put <script>s near the end of the HTML, just before the closing body tag, </body>. That way, when elements are called for in the script, they will already be present.

You don’t want the scripts near the top of the document because of the way a web page is constructed. HTML is parsed by the browser until it comes across a script. When a script is encountered the parsing is paused and the script is then executed. If a script precedes the elements that it calls for, the script won’t work as intended.

Alternatively, the script could be wrapped in a ready() method like so:

Using the ready() function assures that the DOM is completely constructed before modifying it with the script.

ColorBox works on any jQuery selectable object. It’s a simple matter to create a slideshow by grouping images with the “rel” attribute or with a common class name, like so:

A simple, one-line script is all that’s needed to create a slideshow from the images grouped by their common class name, in this case .group1.

When the image link is clicked this script will center each image in a lightbox and shadow the rest of the page behind the image. Clicking on the page, or close button, will bring back the page as it was before clicking on the image.

To create a slideshow complete with previous, next and close buttons, add ‘rel=group1’ as a css key:value pair inside curly braces in the parentheses for the colorbox function.

Any number of key:value pairs can be added here to make your slideshow really stand out.

Other content types can be used with ColorBox, like HTML, Flash, video, or external webpages. Of course, that means you can let your imagination run wild and use ColorBox to your advantage in creating beautifully modern websites.