Icon The Kermit Project   |   Now hosted by Panix.com
New York City USA   •   kermit@kermitproject.org
…since 1981

The Photogallery script

[download

    A Kermit script for automated creation and updating of photo galleries on the Web

Author:  Frank da Cruz
Script version: 1.15
Dated: 2014/08/13
      Platform:  Any version of Unix where C-Kermit is available.
Requires:  C-Kermit 9.0.304, Image Magick.
This page last updated: Mon Nov 3 10:35:12 2014

Photogallery is a program written for the Unix operating system family* in the Kermit script language that builds an HTML gallery for the World Wide Web from a collection of original JPG images: photos, scans, screen shots, or any other type of image in JPG format. The gallery pages are coded in HTML 4.01. Like all Kermit scripts, Photogallery is a text-mode program; it is to be run in an interactive Unix shell session, in a terminal screen. The Photograllery script can probably be made to work in Windows and/or in VMS with some work, if there is any interest. This document assumes a basic knowledge of Unix and the language (HTML) and structure of Web pages.
______________________________
* UNIX is an operating system family that includes Linux, Mac OS X, Android, FreeBSD, NetBSD, HP-UX, Solaris, AIX, and hundreds of others. Click here and here for more information about Unix.

Screen shot of a Photogallery gallery - click on it to visit the gallery itself:
Gallery example

CONTENTS:

News

13 Aug 2014: Version 1.15. Allow labels to be associated with subsections; don't generate Javascript if scaling is not elected.

23 Jul 2014: Version 1.14. Allow specification of gallery subsections and subtitles. Add index2 parameter (text to put below thumbnails). Don't assume return code of \fpictureinfo() is index into array element holding length of longer side because new third element is "date taken". Fetch and install this version with Getkermitscript.

14 Jan 2014: Version 1.12 (and 1.11) more options for handling uplink; new dontenlarge option; exit if images file specified but no images found. Plus a new automated installation script is available, HERE.

20 Oct 2013: Version 1.10 (and 1.08-1.09) fix a couple minor bugs (see comments in source).
27 Sep 2013: Version 1.07 fixes a typo that prevented Photogallery from finding its index.txt file.
18 Sep 2013: Version 1.06 allows images from other directories, multiple galleries in one directory.
15 Sep 2013: Version 1.05 allows Javascript to be disabled.
14 Sep 2013: Version 1.04 allows the scale parameter to work with Microsoft Internet Explorer (using Javascript).
08 Sep 2013: Version 1.03 fixes some bugs when adding images to a gallery.
07 Sep 2013: Version 1.02 allows normalization of image file names and sorting of images based on date taken.
07 Aug 2013: Version 1.01 allows image file names to be taken from a file.
04 Aug 2013: Initial version, based on a script from 2006 called Photoalbum.

OVERVIEW

In its simplest application, the Photogallery script creates a gallery in a fresh directory that contains only the images that are to be shown. It is driven by the JPG images it finds in the directory. The normal sequence is:
  1. Create a new directory and give it the desired access permissions.
  2. CD to the new directory and upload or otherwise move the JPG files into it.
  3. Run the Photogallery script, supplying at least a title for the gallery.
The Photogallery script always operates on its current directory. Be sure to CD to the desired directory before running the script. All the JPGs found in the directory are included in the gallery unless you specify otherwise. Text, captions, and special special effects can be added as explained below.

When you run the Photogallery script...

The script takes some pains to avoid excessive image processing. On its first run for a particular gallery, it produces resized versions of each original (unless told not to), plus a thumbnail for the main gallery page. If you run the script again, it skips these steps unless you have changed the original image or have added new images, in which cases it will only resize and make new thumbnails from the changed or new images.

The script is designed to allow the gallery to be expanded as new photos arrive, and can be run repeatedly on the same gallery without undoing previous work.
______________________________
* Most images that come from modern digital cameras, cell phones, scanners, or similar devices are too big for web browsers. Photogallery uses an external program, Image Magick convert, to resize them (in both dimensions and byte count), and also to produce thumbnails (very small versions of each image) for the main page. You can control the sizes but reasonable defaults are supplied. The original images are retained but can be deleted once the gallery is created.

IMPORTANT WARNING

This script creates an index.html file in your current directory unless you tell it not to via the 'indexfile' parameter (see below). Unless you want your website home page to be a gallery, YOU SHOULD NOT RUN THIS SCRIPT in the top-level directory of the website without specifying a different name for the index file, because this will replace the website's home page, the index.html file. There is no foolproof way for Photogallery (or any other program) to know whether it is running in the home directory of a website. However:

DOWNLOAD AND INSTALLATION

The Photogallery script requires C-Kermit 9.0.304 or later* on a Unix-based operating system, and also that the Image Magick convert program is installed in your PATH (that is, if you type “convert -version” at the shell prompt, you'll see some text like “Version: ImageMagick 6.2.9” rather than “convert: command not found”).  Download links:

Link to download... Status
[CLICK] C-Kermit 9.0.304 Free open-source software, next release (in development)
[CLICK] Image Magick** Free open-source software
[CLICK] The Photogallery script Free open-source software

After downloading the Photogallery script, follow these steps:

______________________________
* The script should also work with earlier versions of C-Kermit 9.0, but certain features will not be available: sorting by Date Taken, anything to with locales, etc.
** Strictly speaking, Image Magick convert is not required, but if Photogallery doesn't find it, it won't be able to resize pictures or make thumbnails. If you have some other way of doing that, or if you are willing to have text links in place of thumbnails, you can still use Photogallery to create galleries. Name the thumbnails as shown in the table in the following section.

GALLERY FILE NAMES

These are the names of the files that actually compose the gallery, and that are served by the web server when the gallery is visited. Note that file names in Unix operating systems (with the possible exception of Mac OS X) are case-sensitive.

Name Example Created by Description
imagename.jpg dscn1234.jpg Your camera or scanner (etc) An original image
imagename-r.jpg dscn1234-r.jpg Photogallery + Image Magick A resized version of the image
imagename-t.jpg dscn1234-t.jpg Photogallery + Image Magick A thumbnail of the image
imagename.html dscn1234.html Photogallery Gallery subpage for this image
index.html index.html Photogallery The home page of your gallery

Image file names must be lowercase; for example dscn4321.jpg rather than DSCN4321.JPG. This is because (a) Unix filenames are case-sensitive and (b) the script assumes all image files have names ending with “.jpg”. If your images have uppercase letters in their name, you can convert them to lowercase by including:

fixfilenames=1
on the command line (or in the PARAMS file, explained below). The script does not do this by default because you might want to have images in the directory that do not appear in the gallery, or different images whose names have the same spelling but different casing.

You can also use Kermit's RENAME command; for example:

rename /lower *.JPG
If the JPG images have a different extension such as .jpeg instead of .jpg, this too can be fixed with Kermit's RENAME command:
rename /replace:{{.jpeg}{.jpg}{$}} *.jpg

Once the gallery is built, the originals can (but need not) be deleted. If an original image is changed (e.g. by editing it in Photoshop) and the script is run again, a new thumbnail and a new resized version are produced automatically.

To add or modify text or captions, create or change the relevant *.txt files and run the script again to rebuild the HTML files (see examples below).

Caution:
If any of your original images have filenames that end with -r.jpg or -t.jpg, all bets are off!

ORDER OF IMAGES

Normally, all .jpg files in the directory are included in the gallery. Unless instructed otherwise, Photogallery orders the images “alphabetically” by filename; that is, in the same order Kermit's “directory *.jpg” command would list them. Image files originating from cameras, scanners, cell phones, and similar devices generally have a naming sequence that corresponds with chronological order. For example, a photo with image name dscn1234.jpg will have been taken before dscn1235.jpg from the same device.

To change the order in which images appear, you can:

When you use an IMAGES file to specify the source images, the images need not be in current directory. To include images from other directories, just put the relative or absolute pathname of each image in the image file.

Use an IMAGES file when you want to:

About SUBTITLES... Suppose you want your gallery to be divided into sections, with a title for each section, like this one. In this case, I've made what appears to be a gallery of galleries of different places in the Bronx. To do this you can include [SUBTITLE] lines in your IMAGES file, like so:
[SUBTITLE]Van Cortlandt Stadium
davc00.jpg
davc05.jpg
[SUBTITLE]Van Cortlandt Park Southwest Playground
davc10.jpg
davc20.jpg
davc30.jpg
[SUBTITLE]Bronx County Courthouse
chbc100.jpg
chbc110.jpg
Subtitles only work when you're using an IMAGES files, and they don't work if you tell photogallery to SORT the images.

When you specify a subtitle, it appears on the main gallery page on a line by itself above the images whose names follow it in the IMAGES file. It also is appended to the title of each subpage until another [SUBTITLE] directive is encountered. Visit the Bronx New Deal gallery to see how this looks.

If you wish to be able to link to subsections of your main gallery page, you can include a label in your [SUBTITLE] directive:

[SUBTITLE:vcstadium]Van Cortlandt Stadium
davc00.jpg
davc05.jpg
[SUBTITLE:vcswplayground]Van Cortlandt Park Southwest Playground
davc10.jpg
davc20.jpg
davc30.jpg
[SUBTITLE:bxcourthouse]Bronx County Courthouse
chbc100.jpg
chbc110.jpg
If you wish to override the subtitle for a particular image, create a file with the same name as the .jpg file, but with a file type of .ttl instead of .jpg; for example, davc00.ttl for the image davc00.jpg.

THE PARAMS FILE

The entire process of creating and maintaining a gallery can (but need not) be controlled by a file named PARAMS (upperase) in the same directory where the images are. The file contains the parameters used for the gallery. While the following sections discuss the kinds of things you can specify in the PARAMS file, it is important to understand that it is nothing more than a Kermit command file, and can contain any Kermit commands at all, as well as blank lines and comments in Kermit syntax. Normally it contains definitions for the same variables that you can define on command line (listed below). Here is an example (# indicates a comment):
# Photogallery parameters file for the Mermaid Parade
#
.title = Coney Island Mermaid Parade June 22, 2013, Brooklyn NY
.shorttitle = Coney Island Mermaid Parade 2013
.head = ../head.html                # Use standard head file   
.tail = ../tail.html                # Use standard tail file   
.copyright = ../copyright.html
.root = festivals

You can set the same set of parameters with the PARAMS file or from the command line. Any variables that you set on the command line override the settings of the same variables in the PARAMS file.

OPTIONAL EXTERNAL FILES

You can create some “helper” files that make the creation and maintainance of a gallery much easier, and the end result more pleasing. This section applies to the normal case, where a gallery has its own directory. Later you'll see how to put multiple galleries in one directory or to put a gallery in the home directory of a website without interfering with its home page. File names in most Unix operating systems are case-sensitive, so "PARAMS", "Params", and "params" would be three different files.

External gallery components (all optional)
File Default name Used in Used for
Parameters file PARAMS whole gallery Gallery configuration
Images file IMAGES whole gallery List of images to be included in gallery
The head file (none) index.html HTML prolog, style, menus, etc, for index.html
The Index text file index.txt index.html Text to be included above the thumbnails
The Index text file index2.txt index.html Text to be included below the thumbnails
The tail file (none) index.html End matter, HTML epilog
imagename.txt Invariant Each gallery sub-page Caption or text for each image
The copyright file (none) Each gallery sub-page Copyright notice for each image

Gallery with head file The beginning and end of the main page of the gallery (its index.html file) can be copied from an external file if you wish. This is desirable if you want your gallery to have some kind of banner and/or menu on top and/or on the bottom, and/or a particular style or look, as in the example on the right (click it to see it in full size). The importable top part is called the head file; you can specify it in any of these ways:

The Head File (optional)
Method Example
In the PARAMS file .head = head.html
In the PARAMS file define head ../head3.html
On the command line head="../head3.html"
As an environment variable export HEAD_HTML=~/heads/special.html

(Note: the “../” notation is a Unix shortcut for “in the superior directory”.) The head file should contain the HTML prolog, the <head> section, the <body> tag, and whatever else you want to appear above the thumbnails except text particular this gallery (which comes from the index.txt file). When you import an external head file, the string _PAGETITLE_ is replaced by the gallery title. Within the <head> section you can have a <style> section where you can choose the font and so on. If you don't specify a head file, the script generates a minimal HTML prolog, <head> section, and <body> tag.

Gallery with tail file Similarly, for the end of the index page there can be an external tail file specified in the same way:

The Tail File (optional)
Method Example
In the PARAMS file .tail = tail.html
In the PARAMS file define tail ../headsandtails/tail4.html
On the command line tail="../tail3.html"
As an environment variable export TAIL_HTML=~/$USER/html/standardtail.html

The tail file should include the </body> and </html> tags, but you can also include whatever you want before that: links, menus, logos, text.

When you import a tail file, if it contains the string _PAGEDATE_, this is replaced by the current date. If there is no tail file, a minimal tail is provided by the script.

Language, color, and background specified in the head file take precedence over whatever you might have specified on the command line or in the PARAMS file, but only for the index page; the sub-pages still use the settings you specified.

Finally, you can have a copyright file if you wish to place a copyright notice on the bottom of each sub-page. (CLICK HERE to see an example of a sub-page with both a caption and a copyright notice).

The Copyright File (optional)
Method Example
In the PARAMS file .copyright = copyright.html
In the PARAMS file define copyright ../includes/copyright.html
On the command line copyright="../copyright3.html"
As an environment variable export COPYRIGHT_HTML=~/$USER/html/standardcopyright.html

If the copyright file contains the string _YEAR_, it is replaced by the current year.

File permissions: The files that are used to build to the gallery, including the PARAMS and IMAGES files, the original JPG images, and any head, tail, or .txt files, do not need to be world-readable. In fact you might prefer to keep them private; for example to avoid having the transmission lines clogged by large, high-resolution images. The files that actually compose the gallery – the resized and thumbnail images and the HTML files – are, of course, automatically protected to allow public reading. The default permission for these files is 664. You can override this on the command line or in the PARAMS file as explained below. For an explanation of Unix file system permissions, click here.

SCRIPT PARAMETERS

Parameters for a gallery can be specified: When the script is to be invoked repeatedly for the same gallery, it is best to put the parameters in the PARAMS file so you don't have to type them each time.

On the command line, parameters are given as:

name=value
OR (doublequotes required around values with spaces by Unix shell):
name="value with spaces"

In the PARAMS file, the syntax is slightly different:

.name = value
In this case, each definition must begin with a period, and the equal sign must have spaces around it. If the value contains spaces it may, but need not, be enclosed in doublequotes:
.title = Vacuum Tube Computers
.title = "Vacuum Tube Computers"
When giving parameters on the command line, all parameters except title are optional. Photogallery's command-line parameters are listed in this table and explained in more detail below it:

Photogallery parameters
Parameter Value Default Command-line example Description
arrows 0 or 1 1 arrows=1 Use arrows for navigation
background Color name or code #fff0f0 background=white Background color
color Color name or code darkmagenta color=blue Foreground text color
copyright filename (none) copyright=copyright.txt For bottom of each sub-page
dontenlarge 0 or 1 0 dontenlarge=1 When resizing don't enlarge
fixfilenames 0 or 1 0 fixfilenames=1 Normalize image file names
head filename (none) copyright=../head.html For top of index page
height number of pixels 160 height=200 Height for thumbnails
help (none) (none) help List command-line options
imagesfile filename IMAGES imagesfile=newimages Name for alternative IMAGES file
indexfile filename index.html imagegallery.html Name of gallery main page
language English or Spanish English language=spanish Language for navigation
linktonext 0 or 1 1 linktonext=1 Click-on-image action
noarrows 0 or 1 0 noarrows=0 Use words for navigation
noscale 0 or 1 1 noscale=0 1=don't scale, 0=scale
paramsfile filename PARAMS paramsfile=newparams Name for alternative PARAMS file
permissions octal number 664 permisssions=644 Permissions for gallery files
resize number of pixels 740 resize=0 0 means don't resize
root directory path none root=. See Advanced Use
scale 0 or 1 0 scale=1 1=scale, 0=don't scale
sort 0, 1, or 2 0 sort=1 0=no, 1=yes, 2=reverse
shorttitle string same as title shorttitle="Parade" Short title for sub-pages
tail filename (none) copyright=../tail.html For bottom of index page
title string (none) title="Mexican Parade" Title of the gallery
uplink     uplink=../index.html Where uplink should link to
version (none) (none) version Show script version

Example using command line:

photogallery title="New Models for Fall 2013" color=gold background=black
Example using PARAMS file:
.title = "New Models for Fall 2013"
.color = gold
.background = black
Resizing and thumbnails are not done by the script itself, but by an external package called Image Magick, which is freely available for Unix, VMS, and Windows. If Image Magick is not available, the script still works, but images won't be resized and thumbnails will not be produced (text links are shown in their place on the index page).

The ARROWS parameter...
says whether to use "arrows" for navigation icons. These are actually Unicode triangles: ▲ ▶ ◀. If you specify arrows=0, then words are used, English or Spanish according your language selection. Since the default value is 1, if you give an arrows parameter without a value, it is the same as specifying arrows=1.
The BACKGROUND parameter...
is the background color to be used for the index page (unless a different background is specified in a head file) and all sub-pages. Normal HTML color names or numeric tags (such as #fff0f0) are used.
The COLOR parameter...
is the foreground color; the color to be used for text, lines, arrows, and borders on the index.html page and on the sub-pages (also in HTML notation. It also determines to some extent the "hover" color for links; for example, if the color parameter is gold the hover color will be yellow.
The DONTENLARGE parameter...
When resizing would result in enlarging an image, which would necessarily make it more blurry, this parameter says to skip resizing and display the image in its own size. Thus, large originals will be reduced but small ones will be left as-is.
The FIXFILENAMES parameter...
normalizes image file names, converting them to all lowercase and changing any .jpeg files to .jpg, as required by the script. If you request that Kermit normalize filenames, this applies also when the names are taken from an IMAGES file, in which case a new IMAGES file is created containing the normalized names.
The HEIGHT parameter...
applies to the thumbnails generated for the index page; it tells how many pixels high each thumbnail should be.
The HELP parameter...
is not exactly a parameter, it tells the script to print a list of its command-line options. It also does this if you run the script with no arguments and there is no PARAMS file.
The IMAGESFILE parameter...
You can provide an explicit list of image files from which to build the gallery in a file named IMAGES, which Photogallery looks for automatically when you run it. But in case you want to have more than one gallery in the same directory, with one or more of them using an images files, you'll need to prevent confusion over which gallery uses which IMAGE file. To specify an alternative filename use the "imagesfile=xxx" option on the command line or ".imagesfile = xxx" in the PARAMS file.
The INDEXFILE parameter...
Normally the main page of the gallery is named index.html. But in case you are building a gallery in a directory that already has index.html file that you don't want to destroy, you can give the gallery main page another name of your choice.
The LANGUAGE parameter...
tells whether text generated by the script (such as instructions, tool tips, navigation labels, dates, etc) should be in English (which is the default) or Spanish. As of this writing, those are the only choices. Spanish text is written in the ISO-8859-1 character-set, properly announced. If you specify language=spanish and you have an external head file, it should include the following:
<html lang="es">
...
<META http-equiv="Content-Type" content="text/html; charset="ISO-8859-1">
At present it is not possible to use a different character set (such as UTF-8), at least not if you have selected Spanish as the output language, because Spanish words in the script are encoded in ISO-8859-1. This could be addressed if there were any interest.
The LINKTONEXT parameter...
tells whether clicking on a picture in a subpage takes you to the next sub-page (which is the default action), or brings up a full-size version of the same image. The latter works, of course, only when you don't delete the originals after making the gallery.
The NOARROWS parameter
is the same as the ARROWS but with opposite sense: noarrows=1 is the same as arrows=0. If you include a noarrows parameter without a value, it is the same as specifying noarrows=1; that is, don't use arrows.
The NOSCALE parameter...
is the opposite of the SCALE parameter (see below).
The PARAMSFILE parameter...
Photogallery looks for parameters in a file called PARAMS in the current directory. But in case you want to have more than one gallery in the same directory, you can have a different parameters file for each one, but then each parameters file must have a different name. You can tell Photogallery which parameters file to use by including the 'paramsfile=xxx" option on the command line.
The PERMISSIONS parameter...
lets you specify the permissions for the JPG and HTML files that comprise the gallery. The default permission is 664, meaning owner and group can read and write the files, others can only read them. You might want to change this to 644 if you don't want others in your group to be able to change or delete your gallery files.
The RESIZE parameter...
tells whether to resize the original images for display in the sub-pages, and if so, to what size. RESIZE=0 means don't resize them; that is, put them in the subpages exactly as they are. Use this when your original images are small enough to fit into a normal browser window. When you give a number (e.g. RESIZE=600), this says to resize the image so its longer dimension (height or width) is that many pixels. Resizing is not destructive; it makes a copy of each original image with “-r” added before the .jpg in the name. This way you can always come back and re-resize them to a different size if you wish, as long as you haven't deleted the originals.
The SCALE parameter...
applies to the image shown in each sub-page. Normally the image (original or resized) is shown in its true size, regardless of the window size. With scale=1 (or noscale=0), the image is scaled by the browser to fit the window size. If you are using Firefox, Chrome, Safari, Opera, or probably any browser other than Internet Explorer, then if you change the window size by dragging or maximizing or restoring, the image size changes with it. If you're using Internet Explorer, you'll need to reload the page to see the image in the new size after the resizing the browser. Use scaling only for fairly large images, because smaller images don't look good when magnified.
The SHORTTITLE parameter...
specifies the title to be used for sub-pages. If no SHORTTITLE is specified, the title is used.
The SORT parameter...
lets you tell the script to arrange the images in chronological order according to the "Date Taken" that is recorded by the camera or scanner inside the JPG file itself. The default is not to sort. When sort=1, the filenames are sorted in normal chronological order (oldest first, latest last). When sort=2 (or any number greater than 1), they are sorted in reverse chronological order (newest first). Note:
  • If any of the images do not contain a "Date Taken", the images can't be sorted. Kermit detects this, cancels the sorting operation, and proceeds with the gallery. This can happen, for example, if you saved the Image from Photoshop's “Save for Web & Devices” option, which strips most non-graphic information out of the JPG file before saving it.
  • If you have an IMAGES file, the names specified there will be sorted too if you specify sort with a nonzero value.
  • Sorting by Date Taken works as expected only if all the cameras or scanners that created the JPG images had their date and time set correctly.
Sorting is useful when the names of the image files would not produce a chronological arrangement; for example, when you have images from different devices, or image from a device whose naming sequence wrapped around.

You can use a separate Kermit script, Jpginfo, to get a listing of JPG files with their internal information: date taken and dimensions. CLICK HERE to download it.

The TITLE parameter...
specifies the title for the gallery and for its index page. It goes in the HTML <title> clause and also appears as the main heading on the index page.
The UPLINK parameter...
lets you specify where the uplink (normally shown as ▲) goes to when clicked. If this paramater is not specified, it goes to the index.html file of the superior directory, if there is one, or else if a root parameter has been defined, to the index.html file of that directory, or else to the index.html file of the website's root directory.

MAKING CHANGES TO A GALLERY

If you will be making changes to a gallery, or think you might, or even if you don't think you might, it is best to create a PARAMS file. Then any time you need to make changes, you simply run the script again by typing its name; you don't need to enter the parameters again. If you don't have a PARAMS files, then you'll need include all the relevant parameters on the command line each time.
Adding images
To add a new image (or images) to the gallery, simply put the new image(s) in the gallery directory, make it your current directory, and run the Photogallery script again. Example:
cd teachersday
kermit -g img_7654.jpg
photogallery
Deleting images
To delete an image from the gallery, delete all the files that start with the image's name and run the script again. Example (Unix shell):
cd machupicchu
rm dscn3742*.*
photogallery
Or, alternatively, create an IMAGES file that lists only the images you want to include.
Renaming images
If you want to rename an image, you should rename not only the original image file, but all associated files accordingly: the rezised image, the thumbnail, and any caption file. And if the gallery is driven by an IMAGES file, the name of the image should be changed in that file too.
Editing images
If you want to improve or change the appearance of an image, edit the original image in Photoshop (or whatever) and replace it, then run the script again and it will generate an updated resized version and a new thumbnail.
Adding or changing captions
Create or edit a file that has the same name as the image file, but ending with “.txt” instead of “.jpg” (for example “dscn4321.txt”. Then run the script again. You don't have to run it again after each change; you can change a lot of files and then run it when you're finished. If you see a mistake on a sub-page, edit the caption file and run the script again. Caption files contain regular plain text but you can also put HTML tags like <b>THISISBOLD</b>, links, or anything else you want.
Adding or changing text on the main gallery page.
Create or edit a plain-text file named “index.txt”, then run the script again. Like the caption files, this one can also include HTML tags. Typical contents include author and/or contact and/or copyright information and a brief description of the gallery.
Changing Photogallery parameters
If you want to change any of the parameters (for example, the size of the thumbnails) edit the PARAMS file and run the script again.

DELETING ORIGINAL IMAGES

IF you resized the originals (which is done automatically unless you specified resize=0) AND: THEN the gallery doesn't use the originals and you can delete them once the gallery is complete if you want to save space. You can use the following Kermit script to delete all the JPGs in the gallery directory that are not referred by any of the HTML files in the directory:
deletegalleryoriginals
The script tells you which files it's going to delete and then asks your permission to delete them.

In case you want to dispose of the originals in some other way, you can use C-Kermit to RENAME (move) them to another directory, SEND (transfer) them to another computer, etc. For example, to transfer them:

send /delete /except:*-[tr].jpg *.jpg
which means “send all JPG files except the ones that have “-t” (thumbnail) or “-r” (resized) before “.jpg” in their names, and delete each one after (and only if) it has been successfully transferred.

If you run the Photogallery script again after deleting the originals, it will treat the “*-r.jpg” files as originals. If you run the Deletegalleryoriginals script again, it won't do anything unless you added more originals.

EXAMPLES OF USE

EXAMPLE 1 - Simple no-frills gallery
Screen shots of a simple no-frills gallery...
Gallery index page
Index page
First gallery sub-page
First sub-page
Second gallery sub-page
Second sub-page
Last Gallery sub-page
Last sub-page
To make a very simple photo gallery like this one , you don't need anything but the photos. Create a directory in your top-level website directory, give it the appropriate permissions, cd to it, and upload your photos. Example:
cd public_html Change to top-level directory of website
mkdir bronxday Create a subdirectory called "bronxday"
chmod 755 bronxday     Set the permissions
cd bronxday
Change to the bronxday subdirectory
kermit -g *.jpg Upload the images
Then if you don't care about text or captions and you're only going to do this once, just type:

photogallery title="Bronx Day"

(substituting the desired title). The script resizes the photos, makes thumbnails, creates all the forward, back, and up links, creates an index page, sets the correct permissions on all the files, and when the script is finished running, the page is ready for viewing, for example as:

http://www.mywebsitename.com/bronxday/

If you look at the files in the directory you'll see something like this for each image:

img_0100.jpg     An original image
img_0100-r.jpg A resized version for the sub-page
img_0100-t.jpg A thumbnail for the index page
img_0100.html The sub-page itself

and then an index.html file, which shows all the thumbnails. If you wish, and if you did NOT specify linktonext=0 or resize=0 on the command line, you can delete the original images (for example, if they are huge and you want to save space); the gallery only uses the -r and -t images unless you specified linktonext=0 or resize=0 on the command line.

EXAMPLE 2 - Gallery with text
Suppose you want your page to have text, and perhaps a different look. In this case you'll need to create some external files for the text, so since you're doing that you might as well create a PARAMS file so you can easily rebuild the gallery any time you want to make a change. Create these files with a regular plain-text editor such as EMACS or vi in Unix or Notepad in Windows.

To add text to the index.html file, just create an index.txt file (you can include HTML tags in it if you wish). After you run Photogallery again, the text will appear after the title and before the images. This would normally be a description of the gallery as a whole; for example:

Rhinebeck Air Show, August 18, 2013, Rhinebeck Aerodrome, Rhinebeck, New York.

Then for each subpage where you want to add a caption, create a file that has the same name as the original image, but with an extension of ".txt" rather than ".jpg", for example "dscn3271.txt" as a caption for "dscn3271.jpg"; these, too, can contain HTML tags (e.g. for boldface, underline, italics, links, etc); example:

<a href="http://en.wikipedia.org/wiki/Sopwith_Snipe">Sopwith 7F.1 Snipe</a>
biplane at Old Rhinebeck Aerodrome with British markings.

Then create a PARAMS file (uppercase name), for example:

.title = Rhinebeck Aerodrome WWI Aircraft Air Show, August 18, 2013
.shortitle = Rhinebeck Air Show 2013/08/18
.background = blue
.color = lightgrey

(Note: the spaces around the equal sign are required, as is the period before the parameter name.)

Run the photogallery script again after creating or editing the index.txt or caption files. You can come back and change the text files any time, or even edit the images in photoshop. Just run the script again to update the gallery.

EXAMPLE 3 - Gallery with customizations
Suppose you want to make the index page look nicer... font selections, logos, colors, links to other pages or sites... For this you can create an external "head file", that contains the HTML for the first part of the index page. The head file contains the <head>...</head> section, including style selections, and then the beginning of the <body> section, such as a banner or title or whatever you like, that should appear above the thumbnails. You just have to let the script know about it:

.title = Rhinebeck Aerodrome WWI Aircraft Air Show, August 18, 2013
.shortitle = Rhinebeck Air Show 2013/08/18
.background = black
.color = gold
.head = airshowhead.html

Similarly for the tail, which might contain dates, copyright notice, contact information, disclaimer, whatever:

.tail = ../standardtail.html

ADVANCED EXAMPLES

Unless you tell it otherwise, the Photogallery script builds a gallery in a directory of its own, composed of all the JPG images in the directory. The  front page” of the gallery is a page with thumbnails of all the images, plus whatever other content you want to add by providing external HEAD and TAIL files and/or an index.txt file.

But what if you want the front page of the gallery to have the same look and feel and the same menus and links as the other pages on your site? This could be a problem because the gallery is in its own directory, and just copying links from files in the website home directory won't work (unless they are fully-specified absolute links). The normal technique to allow a web page in one directory to use links and menus from another is to put a BASE directive in the index.html file specifying to the URL of the directory to “pretend” that it's in; that is, the base for any relative URLs. You have to put the whole URL or else Internet Explorer won't be able to display the page correctly (BASE="/" is sufficient for other browsers):

<BASE href="http://www.kermitproject.org/">
This way you can copy the code from your other pages to your head and tail files without having to change the links to point to a superior directory. This would not be a big deal if you are only going to have one gallery, but if you have a lot of galleries that share the same head, it can save you a lot of time (read about the HTML BASE tag).
If you are using a head file and you want to take advantage of the BASE feature, you have to put the BASE tag shown above in the head file's <head> section. If you are not using a head file, the Photogallery script will include it automatically.
The BASE tag, however, also introduces a slight complication: now you need special links for the thumbnails and the sub-pages! If you just put their filenames, the web server would look for them in the top-level directory (i.e. the directory indicated by the BASE tag) and, of course, would not find them there.

A special PARAMS-file entry handles this situation:

.root = directoryname

This is the pathname of the directory or directories between the website's home directory and the one where the gallery goes. If a root is specified, the script generates correct paths for the images. If no root is specified, the script just puts their names. Thus, if you are importing a head file that contains a BASE tag, you must include a root parameter in your PARAMS file. If the gallery directory is an immediate subdirectory of the website directory, you can use this notation:

.root = .

If you create a rooted gallery and then rename the directory that it's in (or any superior directory), you'll need to run Photogallery again to generate new links, adjusting the .root = directive as needed.

EXAMPLE 4 - Gallery among other galleries
Suppose you have a website that has lots of parades galleries, so it has a "parades" subdirectory for these, and then each parade gallery is in a subdirectory of the parades directory. But you want to use a standard header with standard menus for each gallery, without having to edit all the links. This is where the root parameter comes in. Specify it in your PARAMS file like this:

.title = Dominican Rican Day Parade
.head = ../head3.html
.tail = ../tail3.html
.root = parades

Then just type "photogallery" to run the script. If the gallery directory is more than two levels below the website home directory, include all the intervening directories in the root definition; for example:

.root = events/bronx/parades
EXAMPLE 5 - Gallery of pictures that keep arriving
Suppose a photographer sends in one or more batches of photos after you have created the gallery. Simply put the new images in the gallery directory, create any desired caption files, and then run the script again. You can do this again and again each time new photos arrive.
EXAMPLE 6 - Gallery of pictures from multiple devices
Suppose you have pictures from different photographers or cameras or devices. Images from each source will have their own naming conventions and sequences and so would come out in a seemingly random order. If you want the photos to appear in chronological order you can create an IMAGES file that lists the image file names in the desired order, or you can tell Photogallery to sort them by Date Taken, as explained above in this section.
EXAMPLE 7 - Example of a nontrivial real-life gallery
Gallery example This gallery uses most of the features described above. The main gallery page has a banner and a menu that is just like all the other pages in the Kermit website, accomplished using exactly the same HTML and links, even though the gallery is in a totally different directory (accomplished with the "root" feature). There's text on on the main page, which comes from the index.txt file, and many of the sub-pages have photo captions, which come from the imagename.txt files. And there's a bit at the bottom of the index page that comes from the tail file.
  • CLICK to see the gallery.
  • CLICK to see the source files.
Clicking the "see the source files" link will give you a listing of the files in the gallery directory, but the results of clicking on them depends on your browser:
  • The PARAMS file should show up as expected. Ditto for any IMAGES file.
  • *.html files such as index.html, will be shown as web pages. To see the HTML code, tell your browser to "Show page source" (Ctrl-U in Firefox; in IE, Right-click on the page, then click "View source").
  • *.txt files such as index.txt or dscf0511.txt will show up as expected.
  • *.jpg image files will show up as images, for example dscf0511.jpg as a full-size image, dscf0511-r.jpg as a resized image, and dscf0511-t.jpg as a thumbnail.
You won't see the head.html and tail2.html files in the listing, though, because they are in the main website directory. That's the whole point; we're sharing the front matter with all the other pages in the website. Here are links to the head and tail files in the main website directory ("view source" to see the HTML code):
EXAMPLE 8 - Example of a Gallery embedded in a website home directory
Gallery example This gallery shows some random images from the main Kermit website directory. It does not interefere with the website's home page. It was produced by the command (all on one line):
photogallery title="Kermit images" indexfile=example.html
and with an IMAGES file listing the images to include. No PARAMS file or anything else.
EXAMPLE 9 - Gallery of pictures from different directories
Gallery example The Kermit project home page shows a random photo of the Bronx (if you click on the photo, another random photo appears). There's a link underneath, “see all images”, to a gallery of all the Bronx images, which is in a different directory. To avoid making copies of all the images for that directory, an IMAGES file was created using this script, which makes a list of all the bronx*.jpg files in the superior directory in "numerical" order (rather than "alphabetical" order, which is different in this case). Then photogallery is run with this PARAMS file to produce the gallery. Whenever a new image is added, the script is run again to incorporate it.

In this gallery, the images in the subpages are scaled, so they are shown in the same width as your browser window. This is a natural and straightforward function of most browsers including Firefox, Chrome, and Safari, but not for Microsoft Internet Explorer. For the latter case, Photogallery generates Javascript code to approximate scaling, adjusting each image to fit the window, but it won't grow and shrink if you stretch or squeeze or maximize or restore the window, as it would in the other browsers. In any case, Photogallery produces a reasonable result in all browsers, even IE.

In this example, all the original images are in a single directory, but when using the IMAGES file, each image listed in it can be in any directory at all.

EXAMPLE 10 - Multiple galleries in the same directory
To have multiple galleries in the same directory:
  • Each gallery must have an index file with a unique name;
  • Each gallery must have a params file with a unique name;
  • If an image list is being used for any of the galleries, the name IMAGES should not be used; each gallery that uses an image list should have a unique name for it other than IMAGES. That's in case any of the galleries does not use an images file; in that case if a file called IMAGES existed, Photogallery would use it automatically.
  • If the galleries share any images, they should not be resized to different sizes, and the thumbnails should not be different sizes. If they are, the thumbnails and/or subpage images in a particular gallery might be shown with different different heights or widths.
For each gallery, Photogallery should be run with the name of the params file on the command line:
photogallery paramsfile=PARAMS3
Each params file should specify unique image and index file names; for example:
.title = Gallery Number 3
.imagesfile = IMAGES3
.indexfile = index3.html
.height = 80             # use the same thumbnail height in all galleries
.resize = 720            # and resize all images to the same size
The names can be whatever you want, as long as they are unique.
EXAMPLE 11 - Changing the order of images in an existing gallery
If the gallery was constructed using an IMAGES file, just edit the file.

If the gallery was constructed without an IMAGES file, you can create one with the following C-Kermit command:

directory /brief /except:*-[tr].jpg /output:IMAGES *.jpg
(NOTE: this command was broken in C-Kermit until November 2014, it is fixed in C-Kermit 9.0.304 Dev.11 and later.) Then edit the resulting IMAGES file to list the images in the desired order, add any desired subtitles, and run Photogallery again to produce the new gallery. Here is an example:
  It uses a PARAMS file, an IMAGES file with subtitles, an index.txt file to put text on top of the thumbnails, an index2.txt file to put more text below the thumbnails, and various options discussed above.
HINTS AND TIPS
  • If you rename one or more original images and run the script again, the thumbnails might not be updated unless you also touch each renamed image to update its modification date. Use the touch command of Unix or of C-Kermit to do this.
  • There might be other similar circumstances where the thumbnails come out duplicated, missing, or showing the wrong image. If that happens, just delete all the thumbnails:
    cd directory-where-images-are
    rm *-t.jpg
    and run the script again.

C-Kermit Photogallery script / The Kermit Project / kermit@kermitproject.org / August 2013 - August 2014