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

Picnav: A Slideshow Using JavaScript and CSS

This page... and the tools to which they refer... are a work-in-progress.

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 Movie Theatre Gallery or the Cambodia Photo Gallery sections of this site.

Picnav's main strength is that these pages can be created 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 set of VBS scripts which read 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 wanted a script that didn't require additional plugins (like Flash), and I wanted to be able to easily modify the slideshows. Over the years, I've found that I often want to add or remove slides from a particular set. I also needed something that would handle a large number of images; at this point, there are over a thousand photos on my site, divided into a couple different galleries, each with 20-30 separate sets of photos.

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

My solution came largely through trial and error, with a particular emphasis on "error." First, I created a set of simple webpages:

  1. A "thumbnail" page (for displaying small preview versions of each picture in the set)
  2. A "single image" page (for displaying a single image and its caption)
  3. A "slideshow set" page (for displaying all of the images in a set, one after another)

Once the HTML was done, I wrote the Javascript for the slideshow, and created CSS styles to customize the display. When the design was complete, I created empty templates based on each of the three pages.

Next, I created two Excel spreadsheets: One to store the basic details about each photo, and another to store site and script configuration information. Finally, I created a set of VBS scripts which read the data from the spreadsheets, and automatically inserted the photo data into the template.

Creating a slideshow involves a total of eight 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 scripts by editing the configuration spreadsheet. (Optional)
5.   Run the script to generate the preview pages.
6.   Run the script to generate the individual image pages.
7.   Run the script to generate the slideshow pages.
8.   Manually create the photo home page (and, optionally, the download page).

More detail on each of these steps is outlined below.

(Late-breaking news... the version numbers listed below are out-of-date. I've updated Picnav, but haven't updated the documentation yet.)

1. Resizing the images

The Picnav scripts are designed to display images with a maximum height or width of about 515 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 515x343 pixels; and if it has a landscape orientation, I'll size it to 343x515 pixels. The thumbnail preview images, meanwhile, are 120x120 pixels, with a black 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.

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. Fortunately, there is a free program designed for just this type of task. It's called Image Magick, and it's a phenomenally powerful program. 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? Never fear: I've created batch files that will automatically perform the necessary functions to create images specifically for use with the Picnav slideshows.

[Fill in details on batch file here]

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, defining those values in the VBS is bad practice, since it means you need to modify the code every time you want to change those values. It's very easy to accidentally modify the wrong thing and break the script, and it's also confusing to try to keep track of the most current version of the script when the file modification date is being changed every time you use it. Defining the script configuration in the photo data spreadsheet, meanwhile, has a different drawback. I use the Picnav script on several photo galleries. I find it much easier to keep data for each collection of photos in its own spreadsheet, rather than storing them all in one gigantic file. 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.

What exactly is in the photo data spreadsheets? If you open them in Excel, you'll see that they are fairly simple. In their current incarnation, the spreadsheets contain eight colums for data:

PROCESS_IMAGE_FILENAME (this contains the image filename)
RAW_IMAGE_FILENAME (this contains the original, unmodified 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)
DATE_TAKEN (the date the photo was taken)
KEYWORDS (terms which could be used to find specific images)
COMMENTS (comments on quality, etc.)

Of those columns, only four are actually used by the scripts: The process image filename, the description, the photographer, and the web set number. The other columns are purely optional: you can fill them in, or ignore them. I use them to keep track of basic data about the pictures. The one thing that might be a little confusing is the distinction between the "Process Image Filename" and the "Raw Image Filename." The "process" image is the one that will be used by the scripts. The "raw" image is the original file. If, for example, a photo was originally scanned from a print, I'll save the original scan (the "raw" image) as a TIFF file. The .tif will then be converted to a .jpg file, and the .jpg will be the "process" image.

The current version of the script is a little crude, and it has one notable limitation: You cannot use quotation marks in the "Description" field of the spreadsheet. If you do, the slideshow Javascript will break.

3. Customizing the HTML templates

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 individual photo pages, and one for the Javascript slideshow pages.

The current templates are:

picnav_singlepage_template.txt (for the individual pages)
picnav_css_highlight_slideshow_template23.txt (for the Javascript slideshow pages)
picnav_preview_template.txt (for the thumbnail preview pages)

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 create new templates, or modify the existing templates. 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 scripts, and the pages they create, 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.

One poorly-named variable bears explanation: the DATA_ROW value would make more sense here if it were called "STARTING_ROW." Picnav was written on the assumption that I would frequently be adding new pages, but rarely be regenerating entire galleries. If you've added more data to the spreadsheet, you can enter the row number where you would like to start. If you want to create new pages for all of the photos listed in your datasource spreadsheet, you can set DATA_ROW to 1.

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

5. Run the script to generate the preview page.

To build the preview pages, double-click on the preview page script. The current version as of this writing is:

picnav_preview27.vbs

Assuming that you've got the data source files and templates in the correct locations, after running this script, you'll have a preview page for images.

6. Run the script to generate the individual image page.

Double-clicking the individual page generation script will create a separate HTML page for each photo. The current version of this script is:

picnav_create_singlepages17.vbs

7. Run the script to generate the slideshow page.

Same story as above: double-click the VBS file, and if you've got everything where it should be, you'll get a webpage for displaying a set of images in a single slideshow. The current version of this script is:

picnav_css_highlight_slideshow23.vbs

 

8. Manually create the photo area home page and download page.

There's also 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.

I also generally make a download page for the high-resolution photos. At the moment I cut-and-past columns from the spreadsheet to make that page, but it would be nice (and fairly simple) to generate that automatically, too. Hopefully I'll get around to that one of these days. Other possible enhancements are listed in the "to-do list" at the bottom of this page.

 

File Summary:

The Picnav toolset currently includes nine files: Two spreadsheets, three VBS scripts, three plain-text template files, and one batch file for resizing images. Specifically, they are:

Configuration spreadsheet: picnav_config.xls
Photo datasource: photodata_theatres.xls
Slideshow generation script: picnav_css_highlight_slideshow23.vbs
Individual page generation script: picnav_create_singlepages17.vbs
Preview page generation script: picnav_preview27.vbs
Single page template: picnav_singlepage_template.txt
Javascript slideshow template: picnav_css_highlight_slideshow_template23.txt
Thumbnail preview template: picnav_preview_template.txt Image resizing batch file: picnav_process_images.bat

 

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 it would be nice if it were easier to set default paths for the scripts, the data and template files, the image folders, the output folders, and so on.

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.

A few enhancements that would be nice: