Tech Support Section Home Mekong Network Home
About This Site...
Mekong.Net Sites...
Recently Updated...
Recommended Links...
Contact Us...
Questions? Comments? Requests? Click here to contact us.

SGen: A Script for Generating Slimbox and Lightbox Slideshows

Ever want to add a slideshow to your website? There are many excellent slideshows available, but most of them require you to spend quite a bit of time editing pages in order to add captions and custom navigation.

One of the best slideshow tools is Slimbox 2. Slimbox 2, by Christophe Beyls, is a lightweight clone of Lightbox, a very popular Javascript image display script, written by Lokesh Dhakar.

SGen is a set of Windows scripts for automatically creating image slideshows which use Slimbox (or Lightbox) to display photos. The name "SGen" is short for "Slimbox Generator," or, if you prefer, "Slideshow Generator."

SGen screen capture - Click to see sample slideshowHere's the short version of what it is, and how it works: You download the file, and extract it. You put the photos you want to feature in the "Originals" folder. If you need to resize them, you run the "sgen-process-photos.bat" script. Next, you run the "sgen-make-datasource.vbs" script. Then you run "sgen-make-pages.vbs." Once that's done, you'll find a fully functional slideshow in the "html" folder.

Now, it's disclaimer time: the marginally-competent doofus who created SGen is in no way associated with the extremely smart people who created Lightbox and Slimbox.

Here is most current version of the toolset:

SGen Slideshow Page Generator

(If you're wondering why the .zip file is so large, it's because I'm currently including a large number of sample photos.)


History and Background

Once upon a time I built this convoluted, goofy-ass tool that automatically generated Javascript slideshows. It had a couple of nice features, but all-in-all, it was vastly inferior to the stuff that was already out there.

Even though I knew that other slideshows looked better than mine, I stuck with my home-brewed version for two reasons. The first reason was that I had invested an enormous amount of work in the tool, and there's a certain amount of pride that comes with that. The more important reason, however, was that the tool did one thing pretty damn well: it allowed me to build many different slideshows, and it allowed me to manage and modify thousands of photos.

The problem wasn't the photos themselves: the problem was the data associated with those photos. My old scripts stored all of the photo data in a spreadsheet, including detailed captions, and the names of the photographers. Would I have to re-enter that data?

I started looking at options, and lo and behold: Slimbox to the Rescue.

A slimmed-down version of Lightbox (one of the most popular slideshows), Slimbox stores the caption for each image inside its own <img> tag. Looking at the HTML, I realized that not only could I use my existing spreadsheets for storing the data, I could even modify my ridiculous "Picnav" scripts to build Slimbox (and Lightbox) slideshows.


Using SGen

Since SGen was made for my own use, it's not very polished. However, it does one thing very well: It is can create large numbers of pages automatically. (Click here to see an example of a large photo gallery, built using SGen.) Pages built using SGen can then be deployed on any standard webserver. There's no need for a database, PHP, Perl, or any other scripting language to be installed on the server.

Although pages created with SGen can be deployed on virtually any webserver, there are a few prerequisites that have to be present on the machine where you will be developing your pages. You'll need Microsoft Excel, and you'll need to be able to run VB Script. I'm using Excel 2003 on a Windows XP Professional workstation. I have not tested the scripts with other versions of Excel or other versions of the operating system, but I believe they will be compatible with Windows 2000 and later, and Excel 2000 and later.

Screen capture of an SGen SlideshowThe SGen tool suite consists of a set of batch files which use Image Magick to convert, resize, and/or sharpen a set of images, and a set of VBS scripts which can create a default data source, and generate slideshow pages.

Let's say that you have a couple thousand photos that you want to display on your website. The first question is: how do you organize that many images, and present them to your site's visitors in a user-friendly way? It's not likely that your visitors are going to want to see that many photos. Typically, they'll be interested in a particular subject, or a specific type of photo.

Ultimately, I decided to group the photos into a three-level heirarchy:

1. The Gallery
The top level is the Gallery. The Gallery contains links to several different sections. For example, one section might contain photos from Chicago, photos from Guatemala, photos from the Grand Canyon, and abstract photos.

2. The Section
Within each section of the gallery, photos are further subdivided into sets. Our Chicago section, for example, might have be divided into a set of black-and-white photos, a set of nighttime color photos, a set of summer photos, and a set of winter photos.

3. The Set
Each set of photos would contain a page showing thumbnail previews of all its images. Images are also linked sequentially within the set; so if, for example, a user clicks on the fifth image in a set, that image will display "Next" and "Previous" links to Images 4 and 6. There's no hard and fast rule as to how many photos a set can contain, but you should avoid sets larger than 50-60 photos, since too many images would make the preview page slow to load.

Creating the top-level Gallery page by hand seemed simple enough; after all, it would be only one page. However, the section pages would be little more work, since the gallery might have several sections. And the slide preview pages? There would be many of those, and each one would contain dozens of image links. Coding those pages by hand would be agonizing.

Screen capture of the photo data spreadsheet To store data about the photos, I created a very simple spreadsheet. The spreadsheet contains the list of photos for the section, the photographer's name, a caption, and an ID number to indicate which set it belongs to.

With the photo data thus organized, I then created a VBScript to automatically extract the data and generate the HTML pages.

To enable the pages to be easily modified for different galleries, I also created a separate spreadsheet to store configuration information for the scripts.

Using the "SGen" scripts, creating the pages for a gallery involves the following steps. (Click an item in the list to jump to details on that step.)

1.   Resize the images and create thumbnail previews.
2.   Enter the desired information in the photo data spreadsheet.
3.   Customize the HTML templates as desired. (Optional)
4.   Customize the parameters of the script by editing the configuration spreadsheet. (Optional)
5.   Run the script to generate the section home pages, the preview pages, and the download page.
6.   Manually create the photo gallery home page.

More detail on each of these steps is outlined below.


1. Resizing the images

The current versions of the SGen templates are designed to display images with a maximum height of 550 pixels, and a maximum width of 732 pixels. (Those sizes were the largest that I could fit into a browser running on a 1024x768 screen, without forcing the user to scroll to see the entire image.) The thumbnail preview images, meanwhile, are 120x120 pixels, with a solid-color background filling any unused space.

Although it isn't necessary to use these dimensions, if you use different sizes, you may need to modify the page templates to ensure that everything fits nicely in the browser window.

SGen includes a script for automatically resizing photos. To use the script, you'll need to have the free ImageMagick graphics program installed on your system. ImageMagick is not included in the SGen toolkit, but it can be downloaded from (Alternatively, you can click here to download the version I'm currently using from this server.)

Image Magick is a phenomenally powerful program, but it's not exactly user-friendly. It's a command-line program, and that might seems a little intimidating at first: what kind of graphics program doesn't have a graphical interface? However, if you want to use the SGen scripts, you don't really need to learn how to use Image Magick; you just need to install it, and run the script, and you should wind up with images suitable for use in your gallery. The batch file will resize the images, sharpen them, and create and pad the preview images. You might, however, need to take a look at the code in the batch file to make sure you are putting your images in the right places.

Strictly speaking, the "batch file" is actually three separate batch files: find-orientation.bat, sgen-imagemagick.bat, and sgen-process-photos.bat. The file to execute is:


That script will invoke find-orientation to determine which images are vertical (i.e., portrait orientation) and which are horizontal (landscape orientation). Once the images have been sorted, sgen-imagemagick is invoked to handle the actual processing of each image. The final images will be copied to the appropriate directories in SGen's "html" directory. (Note: the script doesn't try to determine orientation based on the photos EXIF information, or anything fancy like that: it only examines the dimensions of the photo. If your camera doesn't rotate photos appropriately automatically, you will need to rotate them yourself before you run SGen.)

If you're resizing images manually, you'll also want to create thumbnail previews of each image, 120 pixels square. With the default SGen script parameters, you'd place your main slideshow images in /html/photos, the previews in /html/photos/previews, and a high-resolution copy in /html/photos/highres. All versions of each photo would need to have the same name as the original file.


2. Entering data in the spreadsheet[s].

The VBS scripts that create the SGen pages rely on two spreadsheets: One containing script configuration data, and one containing data on the photos themselves. The script configuration spreadsheet (sgenconfig.xls) tells the script what file to use as the photo data source, what to use for the template file, what to use for the page title, what to use for output filenames, and so on.

Why get these things from a spreadsheet, instead of just putting them into the VBS code? And if they have to be in a spreadsheet, why not just put them in the same spreadsheet as the photo data? If the values were defined in the VBS scripts, you'd need to modify the code every time you wanted to make a change. It would be very easy to accidentally modify the wrong thing and break the script. And while the script parameters could have been included in the same spreadsheet as the photo data, I liked the idea of keeping the data about the program isolated from the data about the photos.

You can also created different config files, and point them to different data sources. By default, the script will look for its configuration parameters in sgenconfig.xls. However, you can optionally specify a different config file on the command line. That way, if you want to use SGen to create or manage multiple slideshows, you can create unique config files and data sources for each slideshow. For example, you could use the command:

sgen-make-pages sgenconfig_cambodia.xls

In that case, the program would use the configuration settings in the file sgenconfig_cambodia.xls, which could point to a data file containing only the data for that particular set.

What exactly is in the photo data source? Open the file in Excel, and you'll see that it's very simple. There are four colums for data:

Column 1: Filename
Column 2: Caption
Column 3: Photographer
Column 4: Set ID number

Because these scripts were actually written by monkeys, they're pretty crude, and you should be aware of one limitation: You cannot use quotation marks (or other special HTML characters) in the "Description" field of the spreadsheet. Anything that screws up the HTML is going to break the slideshow. Maybe in the future, the monkeys will take the time to parse the description field and perform proper character substitution for special entities.

The toolkit currently contains a default configuration file (sgenconfig.xls) and a sample data source file (sgenpics.xls). The default configuration should be adequate for most users, and you can enter your own data into the data source. However, there's also an easy way to make a new data source from scratch. First, copy your photos to the "originals" directory inside the SGen folder. Then, run the supplied script to build your datasource:


The script will automatically insert all the filenames into a spreadsheet, slap in a couple default values for the caption and photographer, and will automatically group them into sets of 20 photos.


3. Customizing the HTML templates

Screen capture of the a template, with replacement tokens circled The scripts create web pages by performing a "find and replace" operation based on a set of template files. The templates are identified in the configuration spreadsheet. There are three files: one for the preview page, one for the Javascript slideshow pages, and one for the download page.

The current templates are:

preview_template.txt (for the thumbnail preview pages)
section_template.txt (for the higher-level "section" pages)
download_template.txt (for the download page)

If you open the template files, you'll see that each one is basically an HTML page, with a few "token" strings embedded within the HTML. The SGen scripts first pull the data from the spreadsheets, then massage it into appropriate HTML. Next, they parse the templates and insert the data in place of the token strings.

If you know HTML, you can modify the existing templates or create new ones from scratch. As long as the token strings are there, the scripts really don't care what else is in the template file.

The current template for the "section" page is very crude; for my own site, I had already created the section pages manually before I added the ability to create it to the script. At the moment, I'm too lazy to spend the time to make a nicer one.


4. Customize the script parameters.

The behavior of the script, and the pages it creates, can be modified by editing some of the settings stored in the configuration spreadsheet (sgenconfig.xls). Most of the parameters in the configuration spreadsheet are fairly easy to understand: the filename of your photo datasource, the path to your photos, filename prefixes and suffixes, and so on. At this point, there are a few parameters in the config spreadsheet which are not actually used in the script.

Also, in the current version of the SGen toolkit, the image processing script and the datasource generation script do not look at the config spreadsheet; it is used only by the main page generation script (sgen-make-pages.vbs).

I'll add more documentation on the configuration settings later. Maybe.


5. Run the script to generate the pages.

The script that creates the pages is:


If you're using the default settings for the templates and data sources, you can execute this script by double-clicking it. However, you can also execute the script from the command line. That will allow you to specify a different configuration file, which is a big advantage if you use the scripts for several different slideshows.

For example, I use the script to generate pages for my site's Cambodia section, and also for a section of the site devoted to movie theatres. Since the sections have a different look and feel, I use different configuration files to customize the script settings. Then, from the command line, I can specify which configuration file to use, like so:

sgen-make-pages.vbs sgenconfig_cambodia.xls

A couple notes on image sizes:

Since I generally don't mind my photos being used elsewhere (with permission, of course) I typically create a page where higher-resolution copies of the photos can be downloaded. I keep this page nice and simple; it's nothing but a list of all the photos and their descriptions, linked to the images.

One advantage to creating a download page: it's Google-friendly. A static page with descriptions of all the photos makes it more likely that users will be able to find your images via search engines.


6. Manually create the photo area home page.

If your site will feature many different sets and sections, you'll probably want a single page that links to all the various sections. I haven't gotten around to writing a script to generate that page, so if you want it, you'll have to create it by hand. Of course, you don't have to use such a page at all; you could simply remove the references to the page ($***GALLERYHOMEPAGE***$) from your HTML templates, and forget about it.


File Summary:

The SGen toolset currently includes the following files:

Configuration spreadsheet: sgenconfig.xls
Photo datasource: sgenpics.xls
Slideshow template: preview_template.txt
Download page template: download_template.txt
Section page template: section_template.txt
Page generation script: sgen-make-pages.vbs
Datasource generation script: sgen-make-datasource.vbs
Image sorting launch file: sgen-imagemagick.bat
Image sorting functional file: find-orientation.bat
Image resizing batch file: sgen-process-photos.bat
Slimbox Javascript file: jslimbox2.js
Jquery Javascript file: jquery.min.js
Slimbox CSS Stylesheet: sgen_slimbox.css
Sample page CSS Stylesheet: generic.css

The .zip file also contains some sample pages and images, and various buttons and graphics used on the sample pages. A copy of touch.exe is also included; it's not essential, but the ImageMagick script can use touch to ensure a consistent time-stamp on all the images in a particular set. There are also a few files files (add-watermark.bat, watermark.txt, and the "watermark" directory) which are not needed by SGen, but which I often use for photos that need a watermark or copyright notice embedded in the image.


The To-Do List

I originally wrote these scripts for my own site. They're still crude. There's practically no error handling, and a couple things that could be automated still need to be done manually. As it stands, these scripts fall into a twilight zone: they're probably too complicated for non-technical users, while deeply technical users could probably build better tools on their own. However, they work extremely well for my purposes.

Future enhancements? It would be nice to have:

Will I ever bother to do any of that stuff? Meh... I dunno.


And, In Conclusion...

SGen is bascially an ungainly, peculiar set of tools which probably won't appeal to anyone but me. I'm not sharing these tools because I think they'll be widely used; instead, I'm sharing them because I think they'd serve as a good foundation for something written by a real programmer. The best way to think of these scripts is to regard them as "proof of concept." There are some nice features buried in here, and a decent programmer could use these scripts as a model for a genuinely good program. So if you're in a mood to build such a thing, feel free to contact me.