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.

Picnav: A Slideshow Using JavaScript and CSS

The End of Crazy-Ass Picnav: I'm no longer working on Picnav. It's been replaced by a slightly-less-stupid set of scripts, called SBGen. (Slimbox Generator). The old Picnav documentation is below.

Our Motto? Picnav: It's the Carhenge of Slideshow Tools!

This page (and the toolset it describes) is a work-in-progress. As of 6/23/2010, it has been extensively revised, and much of the documentation below is out-of-date.

Click to see an example of a Picnav slideshow Picnav - short for Pick-A-Picture Navigation - is a slideshow script for web pages. A Picnav slideshow uses Javascript and CSS to display images and captions for a set of photos.

You can view examples of the Picnav slideshows in the main Photo Gallery, the Movie Theatre Gallery or the Cambodia Photo Gallery sections of this site.

Picnav generates pages that can 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. That said, it's still not particularly easy to implement. If you're looking for a very simple slideshow, you might be better off with PicFader, a modified version of Dynamic Drive's Ultimate Fade-In Slideshow.

Picnav is a highly specialized tool. It was created for my own use, and any suitability for use by anyone else is more by coincidence than design.

Although Picnav pages 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.

Click to see an example of a Picnav slideshowPicnav's main strength is that it can create large numbers of pages more-or-less automatically. I'm still working on documentation and some simple examples, but for now, if you want to take a look at the Picnav tools, you can download the Picnav Tool zip file.

The Picnav tool suite consists of a VBS script which reads data from Excel spreadsheets, and a batch file which uses Image Magick to convert, resize, and/or sharpen a set of images.

There are many slideshow scripts freely available, but I inevitably found that these scripts weren't quite suitable for what I needed to do. I needed something that would handle thousands of images. I didn't want to rely on additional plugins (like Flash), and I wanted to be able to easily modify the slideshows. I also wanted to ensure that the slideshows would require little or no configuration on the webserver itself, so that they could be moved to a different server with ease.

I also wanted a relatively simple structure for organizing the images, and I wanted to be able to keep track of basic information about the photos, such as the name of the photographer, and a short caption.

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. This is the mother-of-all photo pages, and it contains several different sections. Our gallery, for example, might contain separate sections for 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. Or we might divide choose to divide the section into sets based on date; photos from the 1980s, photos from the 1990s, and so on.

3. The Set
A single set of photos might contain fifteen to twenty pictures. The set can be viewed either from a set of previews, or as a slideshow that lets us select images one by one.

My solution came largely through trial and error, with a particular emphasis on "error." First, I created a set of templates for each type of page:

  1. The Gallery page, with links to each of the sections.
  2. The Section home page, with links to each of its sets.
  3. A Set Slideshow page (for displaying all of the images in a set, one after another)
  4. The Set Preview page, for displaying small thumbnail versions of each picture in the set.
  5. A Download page, where higher-resolution copies of each image in the gallery could be downloaded.

Creating individual pages "by hand" was simple enough for the gallery home page and the section pages. After all, there would be only one main gallery page, and a fairly small number of section home pages. But what about the preview and slideshow pages? There would be lots of these, and coding them by hand would be agonizing. The download page was also difficult to do by hand, since it might include links to several hundred images.

Screen capture of the photo data spreadsheet Ultimately, I decided to create an Excel spreadsheet to store the data about the photos. I then created a VBScript to automatically extract the data and generate the HTML pages.

The HTML pages would use Javascript and CSS to create the slideshow effects.

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 "picnav" scripts, creating the pages for a gallery involves a total of six 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 preview pages, slideshow sets, and the download page.
6.   Manually create the photo home page.

More detail on each of these steps is outlined below.


1. Resizing the images

The current versions of the Picnav templates are designed to display images with a maximum height or width of about 550 pixels. My own preference is to maintain a consistent scale for all images. That is, if an image has a portrait orientation, I'll size it to 550x367 pixels; and if it has a landscape orientation, I'll size it to 367x550 pixels. The thumbnail preview images, meanwhile, are 120x120 pixels, with a solid-color background filling any unused space.

It isn't absolutely necessary to use these dimensions. If you use different sizes, however, you will probably need to modify the page templates to ensure that everything still fits nicely in the browser window.

What should you use to resize the images? You can use any graphics program, but if you are working with a large number of photos, you'll want to use something that has scripting abilities. Paint Shop Pro, Photoshop, and even Picasa all have some batch abilities. I generally use Image Magick, a free program designed for just this type of task. Image Magick, and it's a phenomenally powerful, 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 need to perform the same manipulations over and over on many images, Image Magick is an excellent solution. (You can click here to download the version I'm currently using.)

Image Magick has a fairly steep learning curve, but if your sole reason for installing it is to use it in conjuction with Picnav, you won't really need to learn how it works. The batch file (picnav_process_images.bat) 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.

At the moment, I'm too lazy to do detailed documentation on the image manipulation, but for the record, I'm including two additional batch files to sort images by size and orientation. The two files are sort-pics.bat, and sort-orientation.bat. To use these scripts, just run the command:


Sort-pics grabs the list of images from the originals directory, and then invokes sort-orientation to place copies of those images into one of four folders: horizontal, vertical, square, or undersize. "Horizontal" images are those that are in a landscape orientation; "vertical" are portrait orientation, "square" are square (duh), and "undersize" are images whose dimensions are smaller than the pixel size we're defined for our slideshow.

The version of picnav_process_images.bat currently packaged with Picnav is written with the assumption that you've used Sort-pics to put the base images into the appropriate directories, based on their size and orientation.


2. Entering data in the spreadsheet[s].

The VBS scripts that create the Picnav pages rely on two spreadsheets: One containing script configuration data, and one containing data on the photos themselves. The script configuration spreadsheet (picnav_config.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? Either of those methods would have worked. However, 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. Defining the script configuration in the photo data spreadsheet, meanwhile, has a different drawback. When you have a large number of photos of different subjects, a single colossal spreadsheet becomes unwieldy in a hurry. Having the configuration data in a different spreadsheet allows me to pick which photo spreadsheet I want to use as the data source. Making new pages for the movie theatre gallery? Fine, edit the configuration spreadsheet to point to photodata_theatres.xls. Need to update the images in the Cambodia gallery? No problem... point it to photodata_cambodia.xls.

To make switching between sets even easier, you can also create different versions of the config file, and specify the name of the config file on the command line when you execute the script. By default, if you launch one of the scripts without specifying a config file, it will look for pnconfig.xls. If you made different config files for each of your photo sets, however, you could use a command like:

picnav pnconfig_cambodia.xls

In that case, the program would use the configuration settings in the file pnconfig_cambodia.xls.

What about the photo data spreadsheet? What exactly does it contain? If you open them in Excel, you'll see that they're very simple. In their current incarnation, the spreadsheets contain four colums for data:

PROCESS_IMAGE_FILENAME (this contains the image filename)
DESCRIPTION (this is a description of the photo, which will be used as a caption)
PHOTOGRAPHER (the name of the photographer)
WEB_SET (the set identification number)

The column headings are actually at the bottom of the spreadsheet, separated from the actual data by at least one blank row. That way, Excel's line numbers will correspond with the number of images. In other words, the first image is in row one, the second in row two, and so on. With the column headings at the top, the first image would be in row two. That seems kinda silly. (The blank row indicates to the scripts that they have reached the end of the photo data.)

These scripts are fairly crude, and they have one notable limitation: You cannot use quotation marks in the "Description" field of the spreadsheet. If you do, the slideshow Javascript will break.

Data entry is never fun, but there is one little trick that will make it less painful: you can use a simple command-line command to get your list of filenames. I usually keep the relevant command in a batch file and move it into the directory with my photos. The command is:

dir /b *.jpg >filelist.txt

That will create a file called "filelist.txt," containing all the .jpg files in the directory. Once you have that file, you can select its contents and paste them into Excel.


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:

slide_template.txt (for the Javascript slideshow pages)
preview_template.txt (for the thumbnail preview 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 VBS scripts parse the templates and insert the data pulled from the spreadsheet in place of the token strings. The files created by this find-and-replace operation are then assigned new names, based on the values specified in the configuration spreadsheet.

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.


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. Most of the parameters in the configuration spreadsheet are fairly easy to understand. They contain things like the filename prefixes and suffixes for the pages you'll be creating, the path to your photos, and so on.

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


5. Run the script to generate the pages.

Info below needs updating!!

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:

picnav-make.vbs pnconfig_cambodia.xls

A couple notes on image sizes:

The images displayed in the slideshows are scaled down to fit in a browser window. Since I generally don't mind my photos being used elsewhere (with permission, of course) I like to create another 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 high-res image. Users can simply click on the images to save them to their computer.

There's one other advantage to creating a page like this: it's Google-friendly. Google does not (as far as I know) index text rendered via Javascript. 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.

There's one important page that you have to create manually: the slideshow "launch" page. These scripts are designed to create different sets of photos automatically from values set in the photo data spreadsheet... but at this point, there is still no automated method for creating a page with links to all of those separate sets. I hope to get around to scripting that one of these days. For now, however, you'll need to make that page by hand.


File Summary:

The Picnav toolset currently includes nine essential files: Two spreadsheets, a VBS script, three plain-text template files, two cascading style sheets, and three batch file for sorting and resizing images. Specifically, they are:

Configuration spreadsheet: pnconfig.xls
Photo datasource: photodata.xls
Page generation script: picnav-make.vbs
Slideshow template: picnav_set_js_template.txt
Thumbnail preview template: picnav_preview_js_template.txt
Download page template: picnav_downloadpage_template.txt
Image sorting launch file: sort-pics.bat
Image sorting functional file: sort-orientation.bat
Image resizing batch file: picnav_process_images.bat
Picnav CSS Stylesheet: picnav.css
Sample page CSS Stylesheet: generic.css

At this point there are several other random files in the zip, such as sample pages, and sample images, and various buttons and graphics used on the sample pages.

The two CSS style sheets warrant some additional explanation. Picnav uses Javascript to swap between different styles in order to highlight the caption of the photo you are currently viewing. All of the styles that are required for Picnav to function correctly are in the stylesheet named picnav.css. The supplied templates also include a number of other styles. While these are necessary for the sample pages to display correctly, they are not, strictly speaking, essential, and if you make your own templates you may not need them. These styles are defined in a separate stylesheet (generic.css).


The To-Do List

I originally wrote these scripts for my own site. They're still fairly 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.

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 incorporate those into a very nice tool.

Enhancements that I hope to get around to one of these days include:

Hmmm... allow me to think out loud for a moment. (In other words, I'm keeping my personal notes about this project on this page. Otherwise, I forget where I put them!) So, with that in mind, here are some things the scripts need to "know" for future enhancements:

Also on the to-do list: implement a "fast custom" option. If you create many sections, it's silly to have to always create a new config file, when most of the parameters are the same. Suppose we wanted to make a new gallery of photos from Thailand. The fast custom option would let use add parameters on the command line like so:

picnav /f thailand

Ideally, you'd get a message along the lines of: "Overriding config file settings."

Variables would then be set alnog the lines of the following:

sectionHomePage = thailand & pageSuffix
sectionPageTitle = [capitalize]thailand & "Photos"
sectionHomeText = [capitalize]thailand & "Photo Home"
setPrefix = thailand & "-set"
previewPagePrefix = thailand "-preview"
downloadPageFilename = thailand & "-download.htm"
metaDescription = "A gallery of " & [capitalize]thailand & "photos"
imageBasePath = thailand & "/"


Now About That Motto...

So why is this "The Carhenge of Slideshow Tools"? Because, like Carhenge, it's the product of an absurd amount of work for no good reason. There are so many better tools for making slideshows... why did I write my own? Tools like Picasa didn't exist ten years ago, when I first started toying with ways to easily add and update the slideshows on my site. I started using batch files to create easily-customized pages, and those batch files eventually grew into scripts of increasing complexity. Meanwhile, I decided that I kinda liked the way my slideshows worked, and I didn't want to have to change the way my pages looked, or learn to use a new tool, or install a bunch more crap on my server. The end result is that I've built an elaborate, ungainly, peculiar set of tools which probably won't appeal to anyone but me.

As a final note, if you are genuinely interested in using Picnav, but feel that it's too complicated or confusing, feel free to contact me. Since the current crude versions suffice for my own purposes, I'm not terribly motivated to improve them. If I hear from enough people, I might be willing to start making the scripts more flexible and more robust.