Add a Responsive Lightbox to Your WordPress Theme

After my recent tutorial where I showed you how to Add a Responsive jQuery Slider to Your WordPress Theme, I thought I’d show you how to add a responsive lightbox to your WordPress site.

We’re going to be using the incredible fancyBox jQuery plugin (script) to demonstrate the implementation of the lightbox, but the same principles can apply to most lightbox scripts. This tutorial is going to be primarily taught through a 15-minute screencast, but I’ve also included some brief written instructions too.

The Screencast

Step 1 Include the Files

First thing we need to do is download fancyBox from the fancyBox website. We then want to open up the source folder, where we’re going to copy the following files to our theme (note that we’re using WordPress’ default Twenty Twelve theme):

• blank.gif
• fancybox_loading.gif
• fancybox_overlay.png
• fancybox_sprite.png
• jquery.fancybox.css
• jquery.fancybox.pack.js

It’s best to stay organised though, so let’s create a folder in our theme’s inc directory called lightbox, and in there we’ll create three new folders: css, js and images. At this point you also need to create a file called lightbox.js (don’t worry about it just yet). We then need to split up the files above into their appropriate locations, so it’ll look like the image below.

You’ll need to edit the paths to images in jquery.fancybox.css so it matches our new file structure. You can do so by doing a search and replace for:

url(' with url('../images/

Step 2 Enqueue Lightbox Files

Now that we’ve got the folder above filled with all the required files, we need to actually load them! Open up your functions.php file and add in the following:

// Enqueue Scripts/Styles for our Lightbox
function twentytwelve_add_lightbox() {
	wp_enqueue_script( 'fancybox', get_template_directory_uri() . '/inc/lightbox/js/jquery.fancybox.pack.js', array( 'jquery' ), false, true );
	wp_enqueue_script( 'lightbox', get_template_directory_uri() . '/inc/lightbox/js/lightbox.js', array( 'fancybox' ), false, true );
	wp_enqueue_style( 'lightbox-style', get_template_directory_uri() . '/inc/lightbox/css/jquery.fancybox.css' );
}
add_action( 'wp_enqueue_scripts', 'twentytwelve_add_lightbox' );

What we’ve done above is enqueued the FancyBox minified script (and by dependency, WordPress’ included jQuery library), our new lightbox.js file, as well as FancyBox’s stylesheet. Too easy!

Step 3 Initializing The Lightbox

Remember that lightbox.js file we created earlier? Time to open it up and fill it with some beautiful jQuery! In the screencast above I showed you each example separately so you could better understand how the jQuery actually worked, but below is all of the code combined. Copy this to the lightbox.js file:

(function($) {

	// Initialize the Lightbox for any links with the 'fancybox' class
	$(".fancybox").fancybox();

	// Initialize the Lightbox automatically for any links to images with extensions .jpg, .jpeg, .png or .gif
	$("a[href$='.jpg'], a[href$='.png'], a[href$='.jpeg'], a[href$='.gif']").fancybox();

	// Initialize the Lightbox and add rel="gallery" to all gallery images when the gallery is set up using  so that a Lightbox Gallery exists
	$(".gallery a[href$='.jpg'], .gallery a[href$='.png'], .gallery a[href$='.jpeg'], .gallery a[href$='.gif']").attr('rel','gallery').fancybox();

	// Initalize the Lightbox for any links with the 'video' class and provide improved video embed support
	$(".video").fancybox({
		maxWidth		: 800,
		maxHeight		: 600,
		fitToView		: false,
		width			: '70%',
		height			: '70%',
		autoSize		: false,
		closeClick		: false,
		openEffect		: 'none',
		closeEffect		: 'none'
	});

})(jQuery);

Step 4 Usage

You can now use the Lightbox! With the above code it’s set up to automatically add a lightbox for all links to image files with .jpg, .jpeg, .png or .gif extensions. So the following bit of code would produce a lightbox:

<a href="image.jpg"><img src="image_thumbnail.jpg" /></a>

Lightbox Galleries:

You can also create a ‘lightbox gallery’ by adding the same rel attribute to several links, like so:

<a href="image1.gif" rel="some-photos">
   <img src="image1_thumbnail.gif" />
</a>

<a href="image2.png" rel="some-photos">
   <img src="image2_thumbnail.png" />
</a>

<a href="image3.jpg" rel="some-photos">
   <img src="image3_thumbnail.jpg" />
</a>

<a href="image4.jpeg" rel="some-photos">
   <img src="image4_thumbnail.jpeg" />
</a>

However, that same lightbox gallery can also be achieved by just inserting a plain old WordPress Gallery into your post or page. Just be sure to link the thumbnails to the image files like so:

Video Lightbox:

Also included is video lightbox support, which can be achieved by linking to a video’s IFRAME embed URL (find it by looking at a video’s embed code from a service like YouTube or Vimeo) and giving it a class of video and fancybox.iframe, like so:

<a href="http://player.vimeo.com/video/50006726?badge=0" class="video fancybox.iframe">
	Click this to open up a Video from Vimeo!
</a>

IFRAME Lightbox:

In addition to IFRAMEs in video lightboxes you can embed other IFRAMES, such as Google Maps, by including the same video and fancybox.iframe classes, like the following:

<a class="video fancybox.iframe" href="http://maps.google.com/?output=embed&f=q&source=s_q&hl=en&geocode=&q=London+Eye,+County+Hall,+Westminster+Bridge+Road,+London,+United+Kingdom&hl=lv&ll=51.504155,-0.117749&spn=0.00571,0.016512&sll=56.879635,24.603189&sspn=10.280244,33.815918&vpsrc=6&hq=London+Eye&radius=15000&t=h&z=17">Google Maps (IFRAME)</a>

Captions:

As you can see in the video, some of the images I automatically inserted and applied a lightbox to have captions. These are determined by the title attribute of the link. So for example, see the captions being set in the following piece of code:

<a href="an-image.jpg" title="Here is a caption! How exciting!"><img src="an-image_thumbnail.jpg" /></a>
<a href="another-image.jpg" title="Did you see the caption on that image? Damn!">Click for an image!</a>

License

Note that FancyBox is licensed under a Creative Commons Attribution-NonCommercial 3.0 license, which means that you can use it freely in non-commercial works with attribution, but you must pay a license fee to use it in commercial projects. You can read more about the license here.

Resources

• fancyBox jQuery Plugin
• fancyBox Tips & Tricks
• Using $ Instead of jQuery in WordPress (Addresses jQuery No Conflict Mode)

Download

If you download the source files above, please take note that after placing it in your theme’s inc directory, you’ll need to add the code found in Step 2 to your functions.php file, which enqueues jQuery and all of the fancyBox files.

Alternatively, I also turned this into a free plugin that you can download over on my personal site.