I wanted to create a very basic (and I mean basic) image gallery to use on a webpage. It didn’t have to be flash or with fantastic animation. Its purpose was just a little extra page flair and so simplicity was the main requirement.

I looked at a number of existing libraries, searched for examples, read a few blogs and just didn’t see anything particularly simple or lightweight (Lightbox2 for example was pulling 100Kbs of js data in; granted its lovely to see in action but a little overkill for what I wanted).

So I decided to create something as minimal as possible but that was still flexible using PHP to construct the HTML, Javascript to swap images and some simple CSS styling. The solution, nominally called Preview is nothing special, however it does provide a nice simple solution that you might find educational.

The basic features:

• Somewhat flexible on image sizes.
• Use a simple folder based structure, making it easy to auto-generate gallery images (not covered here but easy to do with PHP) or for someone to do it quickly by hand (under 5mins).
• Displays clickable thumbnails;  with the number displayed being configurable.
• Displays a single main image, that can be swapped out when the thumbnails are clicked.
• Provide support for titles and alt text association with images.
• Uses as little browser-side code as possible.
• Supports CSS styling.

Javascript and OnClick

The dynamic swapping of images is handled using a really simple Javascript function, which is small enough to be embedded in the header of a page and a little CSS

This function is attached to an onClick action placed on an image of our choice. In Preview, when the user clicks on a thumbnail image, this swapImage function is triggered. We change the main image being displayed by updating where its src should point to (the image is simply identified by the CSS id image-main). We then attach the attributes from our thumbnail image to the new main image.

The page then shows a new main image with the correct alt and title attributes. You could obviously pass different alt, title and other attributes into this function as well as trigger animations and other visual wizardry. Thats up to you.

Preview places Javascript onClick events on each thumbnail images being displayed, so when the user clicks on one then the imageSwap function is called:

<img class='thumbnail' src='gallery/ke_75.jpg' alt='[Photo:Lake Victoria]' title='Lake Victoria' height='75' width='75' onclick='imageSwap(event, "gallery/ke.jpg")'>

The final trick is to change the cursor when rolling over a thumbnail, so that the user will ‘see’ the thumbnail as a clickable link. This requires a only tiny piece of CSS via the cursor property ie:

#preview img.thumbnail {
	cursor: pointer;	/* Show 'link' cursor */
}

Really thats the core of the solution in a nutshell.

Putting it together with PHP

Now we have the basic mechanism ready for use, we can use PHP to tie everything together so one simple call will show a nice looking gallery, such as this one:

Preview provides a single PHP call, which takes the location of the gallery folder and how many images to show:

show_preview_gallery('gallery', 6);

First we need to decide on some basic image size rules, which really helps to constrain the design requirements. You will need to set different image sizes in the preview.php and preview.css files if you want to use image sizes different than this example.

Image Sizes

The first thing to decide is on a size for our Preview main image, in this example I’m going to use images which are 240px by 300px (again sticking with idea of small page decoration) so it can be easily be floated into a sidebar or margin.

Next lets decide on thumbnail sizes, in this example thumnail previews are going to be 75px by 75px.

I use PHP to crop, resize and prepare uploaded images for galleries like this, but we can look at that on another day. We need for each image to display:

• The main image version, 240×300 (ie image.jpg)
• A thumbnail preview version, 75×75 (ie image_75.jpg)
• A piece of description text, that will be used for the alt text and tooltip title

The pair of images are placed flat in our gallery folder and the description text is written into a very simple descriptions.txt file at this level, which is simply a tab separated format.

Folder Structure

All the image files and description file reside in a single folder, like so:

Each thumbnail file has the same name as its parent (thumbnails are identified by a suffix showing their image dimensions – so in this case xxxx_75.jpg). The Preview code should support .gif, .png files as well.

Using PHP to scan a folder

We use PHP to scan the given gallery folder to find all the thumbnail images of the size we want (in this case all 75×75), using the glob function, which finds pathnames matching a simple pattern:

You could use nice directory iterators to do the same, but as we have a flat filesystem currently then glob works fine. To add a bit of spice we use shuffle to randomize things and then we slice off how many images we want.

At this stage we now have an array of all the thumbnail images.

The rest of the code is pretty simple. We strip off the thumbnail size designation to get the name of the main image file its related to. We construct our IMGs and hook in the imageSwap onClick event and we attach the long descriptions from our flat description text file.

Use CSS to style Preview

Preview is set-up to use id based selection for its main view. Unfortunately theres no simple way of passing our thumbnail and image sizes in, so if you using something bigger/smaller than adjust the widths accordingly in the CSS (remembering to account for any padding and margins being set).

The css file is there mostly to provide a very simple starting point for experimentation by the key components. The only real constraint is that the imageSwap function relies on the CSS id of the main image.

Example

You can see a very basic example of Preview here. Things are pretty basic to support experiementation.

Download

You can download all the code and a working example here. Feel free to modify, hack, lambast and destroy this code. Its deliberately simple and limited so you can see how things work. There is no support provided for this code, though am happy to answer questions and the code is obviously provided as is, with no warranty or guarantee of its functionality.

Too Simple?

There are literally thousands of Javascript image galleries and cool lightboxes out there. Preview is just here to show how to begin to construct your own, its not meant to be used seriously.

If you want something to make really good-looking images displays then start with one of these fine libraries:

LightBox2

Colorbox

JCarousel