Page Links
Other Links


For our galleries we wanted to make it easier to view a group of photos rather than just going forward and backward using the browser buttons. Here are some examples of what you can do.

To achieve this effect we used a piece of JavaScript called "greybox". This is open source licenced under the Lesser GNU Public Licence (or LPGL) which means you're free to use the software (it's different if you plan to modify or distribute it, but we'll leave that topic for another page!)

So how do you do the same?

Note that this guide relates to version 5.53 of Greybox (which we use on this site). You may find that there's a newer version when you go and look. The description here should still be valid...

Getting Started

Go and get the greybox files from here. Once downloaded open the zip. There are a lot of folders within the zip, the one we're interested in is the 'greybox' folder (you'll need to navigate down through the GreyBox_v5_53 folder first).

Now, think about where you'd like to keep the greybox files. You could put them in your website root folder but we like to keep things tidy so we created a new folder (at the root level) called (orginally enough) greybox. Whatever you decide to call it, remember the name as we'll need it later.

Extract the contents of this folder into whichever folder on your website that you created earlier.

Here's a summary of the files you should get and what they're for:

AJS.js This JavaScript file provides general library routines for use by the greybox script - e.g array processing and event handling.
AJS_fx.js This adds some effects, e.g fades. If you don't want these effects then this file can be deleted, you don't need to modify the other scripts as they check to see if this file exists.
g_close.gif This is the close greybox button image.
gb_scripts.js This is the main script containing the functions for creating, navigating and destroying the greybox - it uses AJS.js and AJS_fx.js to provide other functionality.
gb_scripts_tmp.js This is a more "readable" version of gb_scripts.js - that is it contains white space, meaningful parameter names etc. However you don't need this so you can delete it!
gb_styles.css This is the cascading style sheet for greybox.
header_bg.gif This provides the background to the navigation header.
indicator.gif This is an animated gif file providing the loading indication.
loader_frame.html This is the HTML for the inline frame (IFRAME) which greybox uses to display the slide show.
next.gif This is the next image button.
prev.gif This is the previous image button.
w_close.gif This is a close window button for those items rendered in a page view rather than a image show (see here).

Making it work

OK, we now have the source files and images within our website, how do we use it?

Firstly we need to get our web page to include the necessary scripts. So we need to add three bits of HTML to the header section (between the <head>...</head> tags) of our webpage.

The first bit sets a variable used by the scripts. This is the name of the folder we created as part of the setup (so replace greybox by whatever it is you named the folder earlier). The installation instructions that come with greybox state that you should specify the full URL of the location - we guess that makes it easier to cut 'n' paste the HTML around, but you don't need to providing you get the path to the source files correct:

  <script type="text/javascript">
      var GB_ROOT_DIR = "greybox/";

Then we need to include references to the scripts. Again replace greybox if appropriate:

  <script type="text/javascript" src="greybox/AJS.js"></script>
<script type="text/javascript" src="greybox/AJS_fx.js"></script>
<script type="text/javascript" src="greybox/gb_scripts.js"></script>

Finally we need to link to the style sheet (replacing greybox by whatever you called it):

  <link href="greybox/gb_styles.css" rel="stylesheet" type="text/css"/>

So editing the page header is complete. Note that you need to do this for all the pages you want to use greybox on, but it's easy enough using cut 'n' paste between the files. Be careful to ensure the files are correctly linked though! If the HTML files are not at the same level in the web file structure then you'll need to modify the greybox above to point to the correct location.

Creating The Slide Show

Activation of the greybox is very simple and involves adding a tag:

  rel gb_imageset[name]

to the link to the pictures you want as your slideshow. gb_imageset tells greybox that you want to view a number of images - you can also use gb_image[] for a single image. (You can find out more about rel tags here).

Here name should be some meaningful grouping of your pictures. There is no limit to the number of groups you have so you can go mad!

So as an example say we have the pictures a.jpg, b.jpg and c.jpg as a grouping that we want to display as a slideshow. Let's call this grouping 'holiday'. We also have thumbnail images of the pictures - a_t.jpg, b_t.jpg and c_t.jpg. Then the HTML we need is:

 <a href="a.jpg" title="Beach" rel="gb_imageset[holiday]"><img src="a_t.jpg"</a>
 <a href="b.jpg" title="Hotel" rel="gb_imageset[holiday]"><img src="b_t.jpg"</a>
 <a href="c.jpg" title="View"  rel="gb_imageset[holiday]"><img src="c_t.jpg"</a>

Note alsothat we've also added the title="" tag for each image. In this example we'd get the titles "Beach", "Hotel" and "View" with the appropriate picture.

So let's see this in action...


  Greybox Single Image Example Here's a single image using greybox. Click on the picture to see the effect. Note that the picture has a title of "Windmill".

The HTML for the above looks like:

  <a href="images/Windmill.jpg" title="Windmill" rel="gb_image[]"><img src="images/Windmillt.jpg"</a>



Here are a number of pictures of flowers that are grouped as a slideshow using the group name of 'flower'.

The HTML for this looks like:



 <a href="images/Flower1.jpg" rel="gb_imageset[flower]"><img src="images/Flower1t.jpg"</a>
<a href="images/Flower2.JPG" rel="gb_imageset[flower]"><img src="images/Flower2t.jpg"</a>
<a href="images/Flower3.jpg" rel="gb_imageset[flower]"><img src="images/Flower3t.jpg"</a>

Other things you can do with greybox

Greybox can work with images as we described above, but it can also work with more general objects. For example click here to launch Google.

Here we have added the tag below to the hyperlink:


This causes the link to be generated in a 600 pixel wide by 600 pixel high window. Here's another example where we launch a (not very interesting) PDF document.

There are a few other things we can do:

Launch the object in a window 'W' pixels wide and 'H' pixels tall which is centered within the browser window. Try it - Google  
Launch the object full screen - i.e. fill the browser window (best fit). Try it - Google  
Like you could do with images you can also do with objects - replace NAME by a meaningful tag to group the objects together. Try it - Search Site 1, Search Site 2, Search Site 3  

We won't bother to show the HTML for these examples as by now you should have got the hang of it!



Things can, and do, go wrong. If you don't get the effects you're looking for when you click on the link here are some things to check:

  • The GB_ROOT_DIR variable is incorrectly set - when this is the case you may get the greybox starting to load but then it stops. If you have a hierarchical structure for your website this may not point to the root of where greybox is - specify the relative path or use the full URL.
  • If the object just appears with no effects then check that the scripts are correctly linked (including the correct path) in your page header; check also that style sheet is also correctly linked. Check that you have correctly added the rel tag.
  • Also, as mentioned here, you need to let the page completely load before trying the effects out - if you have a lot of pictures on a single page this could be a reason for it not working.
  • Check also the case of the path. Windows based servers are case insensitive (so greybox and GreyBox are treated the same) whereas Linux (or other Unix) based servers are case sensitive (so greybox and GreyBox are NOT the same). To ease this problem we use lower case for all our files and folders where we can.
  • We also had a problem with greybox not working when we had a rollover images on the page. Thanks to Nick Powers for pointing out a solution - you can remove the preload images function and it works! I used to use Dreamweaver for designing the web site and this was autocoded as part of a new page template. I have since moved to Linux so I'm now using BlueFish and hand editting. Anyway if you have this problem look for function MM_preloadImages in the header section and delete all the code.


We first came across Lightbox which provides similar functionality to greybox (apart from only working on images) but we gave up on it due to not being able to get it to work on our webhost. This appeared to be a case sensitivity issue within one of the linked scripts - it worked perfectly well on our development PC, but when uploaded onto the web server (which is a Linux box) it just refused to work.

Another alternative we discovered is Thickbox. This appears to be really a demonstration for the JQuery library but it looks interesting in that it allows a wider set of functionality and object types. We haven't yet had time to play around with this, so check back for an update in the future - you may find we've migrated!



Page last updated: 29 August, 2009
© 2003-2009 Mark and Betty