Lightbox Slideshow

by Justin Barkhuff, justin@justinbarkhuff.com

Help Keep This Code Alive (and Free)

This code is provided to you free of charge, but it does require my time and effort to maintain and to support those who use it.

You can help keep this code free and alive by making a donation:

Download

Version 1.1, released August 15, 2007

If you are using Prototype 1.6, replace lightbox.js with the Prototype 1.6 compatible lightbox.js

All users of Version 1.0 should upgrade to this new release. See the Change Log for details.

About Lightbox Slideshow

Lightbox Slideshow is a simple, unobtrusive script used to overlay images on the current page.

It’s basically a better version of Lightbox2.

In fact, the technical requirements and installation steps are identical to Lightbox2, but with Lightbox Slideshow, the underlying code is much better and there are lots of useful configuration options.

Here are just a few things you can do with Lightbox Slideshow that you can’t do with Lightbox2:

auto-playing slideshow
navigate images via ‘prev’ and ‘next’ links in the image caption area
when browsing a group of images, go from the last image to the first image (and vice versa)
track individual image views using Google Analytics
move the caption above the image
customize the interface language

See the configuration options section for more.

Examples

Single image

Group of Images

Installation

If you are already using Lightbox2, just replace your existing lightbox.js and lightbox.css files with the ones included in the download. Be sure the image references in the CSS file are correct.

Part 1 - Download and Test

lightbox_slideshow.zip

The downloadable zip file contains all files required to run Lightbox Slideshow and the sample page and photos.

After downloading the zip file, extract all the files to any directory on your computer and upload that directory anywhere on your site.

You should then be able to view this functioning sample page at: http://yoursite.com/your_upload_directory/sample.htm

If you are using Prototype 1.6, replace lightbox.js with the Prototype 1.6 compatible lightbox.js

Part 2 - Setup Your Own Page

Lightbox Slideshow uses the Prototype Framework and Scriptaculous Effects Library. You will need to include these three Javascript files in your header (in this order).

<script type="text/javascript" src="prototype.js"></script>
<script type="text/javascript" src="scriptaculous.js?load=effects"></script>
<script type="text/javascript" src="lightbox.js"></script>

Include the CSS file (or append your existing stylesheet with the Lightbox Slideshow styles).

<link rel="stylesheet" href="lightbox.css" type="text/css" media="screen" />

Check the CSS and make sure the referenced image files are in the right location.

Part 3 - Activate Links

Add a rel="lightbox" attribute to any link tag to activate the lightbox. For example:

<a href="images/image-1.jpg" rel="lightbox" title="my caption">image #1</a>

Optional: Use the title attribute if you want to show a caption.

If you have a set of related images that you would like to group, include a group name between square brackets in the rel attribute. For example:

<a href="images/image-1.jpg" rel="lightbox[roadtrip]">image #1</a>
<a href="images/image-2.jpg" rel="lightbox[roadtrip]">image #2</a>
<a href="images/image-3.jpg" rel="lightbox[roadtrip]">image #3</a>

There are no limits to the number of image sets per page or how many images are allowed in each set. Go nuts!

Keyboard Shortcuts

f for first image
l for last image
x and c to close
left arrow and p for previous image
right arrow and n for next image
s to toggle the slideshow

Configuration Options

Lightbox Slideshow allows you to easily configure a number of options. Configuration options are specified by passing an object of your configurations to the Lightbox.initialize() method. This involves editing the last line of the lightbox.js file.

Here are the configuration options:

animate : resize animations; defaults to true
autoPlay : should slideshow start automatically; defaults to true
borderSize : if you adjust the padding in the CSS, you will need to update this variable; defaults to 10
containerID : lightbox container object; defaults to document
enableSlideshow : enable auto-playing slideshow feature; defaults to true
googleAnalytics : track individual image views using Google Analytics (requires Google Analytics code to be installed); defaults to false
imageDataLocation : specifies the location of the caption information (north or south of the image); defaults to south
initImage : ID of image link to automatically launch when upon script initialization; defaults to an empty string
loop : whether to continuously loop slideshow images; defaults to true
overlayDuration : time to fade in shadow overlay; defaults to .2
overlayOpacity : transparency of shadow overlay, can be any value between (and including) 0 and 1; defaults to .8
prefix : ID prefix for all dynamically created html elements; if you change this, you must also update the CSS selectors in lightbox.css; defaults to an empty string
relAttribute : string that specifies the rel attribute value that triggers lightbox; defaults to 'lightbox'
resizeSpeed : controls the speed of the image resizing (1=slowest and 10=fastest); defaults to 7
showGroupName : show group name of images in image details; defaults to false
slideTime : time (in seconds) to display images during slideshow; defaults to 4
strings : object that allows for localization; when customizing this, all string object properties must be defined; defaults to:
{ closeLink : 'close', loadingMsg : 'loading', nextLink : 'next »', prevLink : '« prev', startSlideshow : 'start slideshow',stopSlideshow : 'stop slideshow',numDisplayPrefix : 'Image',numDisplaySeparator : 'of' }

Sample Configuration Options

Do you use Google Analytics? Here is a sample configuration that enables tracking of individual image views. This line of code would replace the last line of your lightbox.js file:

Event.observe(window,'load',function(){ Lightbox.initialize({googleAnalytics:true}); });

Here is a sample configuration that shows the group name for groups of images and disables the autoPlay slideshow setting. Remember, this line of code would replace the last line of your lightbox.js file.

Event.observe(window,'load',function(){ Lightbox.initialize({showGroupName:true,autoPlay:false}); });

Is your site in German? Here is a sample configuration that uses German-specific strings. These lines of code would replace the last line of your lightbox.js file:

var lbStringsDE = {
    closeLink : 'ende',
    loadingMsg : 'laden',
    nextLink : 'weiter &raquo;',
    prevLink : '&laquo; zur&uuml;ck',
    startSlideshow : 'start diashow',
    stopSlideshow : 'stopp diashow',
    numDisplayPrefix : 'Bild',
    numDisplaySeparator : 'von'
};
Event.observe(window,'load',function(){ Lightbox.initialize({strings:lbStringsDE}); });

Change Log

Version 1.1 (released August 15, 2007)

Fixed a bug in Firefox that would cause an error if no ’title’ attribute was found for a Lightbox Slideshow enabled link (thanks Patrick Weyers)
Added support for the ’initImage’ configuration option
Added support for the ’loop’ configuration option

Version 1.0 (released July 27, 2007)

First official release!