Contents |
Foreward
PGTK - The Photo Gallery Tool Kit
A lot of people have commented on my photo gallery, and have asked how they could do the same. I wrote a couple articles on the topic for Apache Today - One about "Dynamic Directory Indexing" and another on "Dynamic Site 'Table of Contents'" - Neither of them talked directly about how to build a photo gallery, but the concepts are largely the same.
To this end, I have recently packaged up my photo gallery software, commented the code, made it all pretty-like, moved a lot of the config and functional stuff to modules - All so I could release it to the world, and hopefully help a couple people at least have cooler websites.
PGTK At-A-Glance
Security NOTE: Do not leave the utils/ folder within active webspace!
The Photo Gallery Tool Kit consists of the following files:
- PGTK::config.pm - Configuration file
- PGTK::basic.pm - Common functions, etc.
- PGTK::image.pm - Module for making thumbnail images of your JPEGs, and other image-manipulation things.
- PGTK::html.pm - Module for HTML-related stuff.
- PGTK::random.pm - Module for randomization stuff.
- PGTK::automagic - Module to handle the automatic indexing, thumbnailing, and resolutioning options
- mkthumbs.pl - Script to make thumbs for the galleries that haven't had them made yet. Specifying "sane" as a parameter causes mkthumbs to make a Make_Sane_Thumb call instead of a Make_Thumb call (slower, but more accurate width/height ratios for some pics). You can also use the "rebuild" argument to rebuild all of your thumbs (ignoring previous copies), and the "snaporder" argument to call snaporder.pl before, and restoreorder.pl after the tumbnail update.
- mkhires.pl - Script to create 640x480 (or as close to as possible while maintaining width/height ratios) versions of large graphics for the "normal" view, and stuff the higher res ones in a separate directory. You can also use the "snaporder" argument to call snaporder.pl before, and restoreorder.pl after the mkhires procedures. WARNING: This utility can ruin your photos if it isn't used properly. The ORIGINAL pictures are copied into the hires/ folder and renamed with a prefix "h_". So if you delete the hires/ folder, you have lost the original versions of the pictures. This is the only utility that actually changes the original pictures. Use with care.
- updategallery.pl - Script combining mkthumbs.pl, mkhires.pl and mkemptyindex.pl into one for later-added pictures. Expects the gallery folder as the first argument, followed by a list of pictures to automagically Do The Right Thing to.
- snaporder.pl and restoreorder.pl - Complimentary scripts that take a snapshot of the current "order" of your galleries folders (based on last modification date), and restore the folder order (using iterative "touches") repectively. May be called from mkthumbs.pl or mkhires.pl with the "snaporder" arguments. NOTE: restoreorder.pl will take 1 second per gallery, as it is necessary to sleep for that second between "touches" in order to properly order the modification times of the folder galleries. You may override the file used (by default they use PGTK::config::$base) by specifying a file as an argument.
- index.pl or gallery.pl - The main CGI that is your gallery.
If you want to use mkthumbs.pl or mkhires.pl to make thumbnails or scaled down hi-res images (more on this slightly confusing topic below), you'll need ImageMagick as well as the PerlMagick module set (and satisfy all of THOSE requirements).
The only file other than the PGTK::config.pm module that needs customizing are the header.tmp and footer.tmp files. The header file can contain a variable $TITLE that will be replaced with the title of the page. The footer can contain $YEAR and $VER which will be replaced with the current year and PGTK version respectively. Security NOTE: Do not leave the utils/ folder within active webspace!
PGTK is built on GNU/Linux systems using Perl, but may run with no/minimal changes on other Perl-supported operating systems as well. PGTK is built to run under the Apache Webserver, and fully supports Mod_Perl and may or may not work at all/properly under other servers.
Evolution
As with most of my software, PGTK started out very simple (16 lines, as I recall) and has evolved.
Pre-History
Initially the script generated a list of galleries (similar to how it currently does) which you could click on, and then it would give you a flat list of all of the files in the directory with a .JPG extension.
The first major enhancement was the ability to parse the "index file" known as subdirectory/index.txt. The index file followed a pretty vanilla format. The first line was the "title" of the gallery (a hold-over from the first version), the second line was a more robust description, the third line was a reserved field (currently unused, therefore left blank) and all subsequent lines followed the format "Picture Description - FILENAME.JPG". The .JPG part wasn't required, as you could have any file type. The dash character (-) was special, and couldn't be used anywhere in the line EXCEPT to separate the description from the filename (this eventually changed below).
The second enhancement was the ability to add comments to the index.txt file. By starting a line (save leading whitespace) with a pound sign (#), that line was treated as a comment, and placed in the generated index as such. This allowed for me to embed links, describe groups of pictures, change time frames, etc. At the same time, I supported two successive equal signs (==) to represent a dash, thus allowing me to put dashes within picture descriptions (still not in filenames).
The first overhaul was when I decided I needed to support thumbnails- Rather, the ability for viewers to optionally see a list of smaller (160x120) graphics, and the descriptions: As well as the ability to click and see the "full sized" version of the picture. This required re-writing a lot of code, and rethinking a lot of the logic I had in this project thusfar. At this time, I also formally elevated PGTK to "formal project" status, instead of it just being "Yet Another Script" that I used to make my site better/easier. I started commenting my code, created abstract packages, as well as the "mkthumbs.pl" tool, to allow for mostly-automated thumbnail creation. This really got me excited about the possibilities of PGTK. It was really evolving quickly, with new features being added as quick as I could come up with them, and a myriad of code optimizations.
The first post-overhaul enhancement came after I decided that I needed to be able to support higher resolution images, as well as the 640x480 "standard" images and the thumbnails. I wanted to allow those who had the bandwidth and resolution to see the photos as I intended them (1024x768, 1280x960 or 1600x1200) instead of the resized versions previously displayed. At the same time, I understood that a lot of people didn't want to see my pictures as "wallpaper" (like I and some of my "photo fans" do). Thus, every picture described has a "hires" link next to the description if there is a higher-resolution version available.
The second post-overhaul enhancment was brought about when I decided to use the magical powers of Math to create "sane thumbnail" creation. This "new" part of PGTK, allows (optionally) for the mkthumbs.pl script to call a new function, PGTK::image::&Make_Sane_Thumb, that calculated the width/height ration of the image before making it a thumbnail, and keeps the same ratio as well as staying as close as possible to the specified thumbnail width and height. This really wasn't all that "new", as the code I used already existed in the mkhires.pl script, it just had to be ported to PGTK::image and made a bit cleaner.
1.0
The subsequent enhancements were basically polish and completion enhancements leading up to the PGTK 1.0 release. These included more comments, getting this webpage up-to-date, writing the snaporder.pl and restoreorder.pl scripts (and adding snaporder support to mkthumbs.pl and mkhires.pl), adding in cutesy functionality such as the $SHOW_IMAGE_COUNT and $MAKE_OVER_RED directives, and other miscellaneous enhancements and optimizations.
2.0
Between the 1.0 and 2.0 releases there were a myriad of new features added. Some PGTK users noticed that my photo site had a lot of cool new features (thumbnailed index pages, archive gallery support, faster load times, etc.), so I had an interim "private 1.5" release with some of the new features for them. With public release 2.0, PGTK can hold its own with any other photo-gallery package out there. Running under Apache's mod_perl, PGTK 2.0 can really scream, even if there are dozens and dozens of galleries to load. It's more "complicated" than a lot of packages out there, but that will change with the eventual web-based admin tool to replace the command-line utilities.
3.0
The changes betweek version 2.0 and version 3.0 are pretty profound. For the first time, PGTK can be dropped in a web folder and start working INSTANTLY (asuming the required modules are installed). In 3.0, PGTK can be run as a Perl CGI, mod_perl application, or Mason application.
New features include:
- simplified, abstracted templating
- ability to edit gallery contents via a convenient web interface
- automagic indexing
- automagic image resizing
- automagic thumbnailing
Reference
The items listed below are exposed functions/variables for use by programmer who are using these modules. This is brief, and not intended to replace in-code documentation! Only .JPG and .PNG graphics are supported at this time.
PGTK::basic
&Get_Title - TAKES: a scalar containing the path to an index.txt file. RETURNS: the "title", else "Untitled Gallery".
&Get_Index_Pic - TAKES: a scalar containing the path to a gallery. RETURNS: the specified thumbnail graphic, or a random thumbnail if unspecified.
&trim - TAKES: A scalar. RETURNS: The same scalar less leading and trailing whitespaces.
PGTK::config
$IMAGE_PATH - STRING path to the "logo image".
$GOT_THUMBS - BOOLEAN whether or not thumbnails are to be used if available
$THUMB_WIDTH - INTEGER representing the preferred width of thumbnails
$THUMB_HEIGHT - INTEGER representing the preferred height of thumbnails
$URL - STRING base URL
$base - STRING base filesystem path
$USE_THUMBS - BOOLEAN on whether or not thumbs are used in this session (read in-code comments)
$MAXCOL - INTEGER representing the number of thumbnail columns to use
$script - STRING of the URL path to the gallery script (self-reference).
$NEWWINDOW - BOOLEAN to decide whether or not to open images in their own window when viewing a gallery by thumbnails.
$SHOW_IMAGE_COUNT - BOOLEAN to decide whether or not to show the number of indexed images (n) after the name of the gallery on the gallery index page.
$MAKE_OVER_RED - INTEGER to determine what number is used as a rule to make the $SHOW_IMAGE_COUNT entries red. 0 means "never". Whatever number you set here will be compared >= (greaterthanorequalto).
$ORDERFILE - STRING to the file you want to snaporder.pl and restoreorder.pl to use for their order database.
$PIC_INDEX - INTEGER where 0 turns off thumbnailed index pages, 1 sets thumbnailed indexes by default, 2 sets non-thumbnailed indexes by default.
@IMGEXTENSIONS - STRING ARRAY of valid image extensions. Don't change this unless you know what you're doing.
$UNBUFFEROUTPUT - BOOLEAN to determine whether output is unbuffered, or buffered. Don't change this unless you know what you're doing.
$WITH_MODPERL - BOOLEAN to determine whether certain mod_perl optimizations should be performed.
$ALBUM_TITLE - STRING to set what you want the title of the gallery to be called.
$USEHTMLINDEX - BOOLEAN to determine whether or not pre-generated HTML pages are used for the index pages. (see in-code comments)
$HTMLINDEX_FILENAME - STRING to set the pre-generated HTML index page name, if used.
$HTMLINDEX_THUMB_FILENAME - STRING to set the pre-generated HTML index with thumbnails page name, if used.
$USE_ARCHIVE - BOOLEAN to determine whether an archive gallery is available.
$ARCHIVEPREFIX - STRING to name the folder that the archive gallery is contained in. This must match a folder in the root of the album, and contained in it are gallery folders.
PGTK::image
$base - see PGTK::config::$base
&Get_Dirs - TAKES: A scalar folder path. RETURNS: An array of directories within that path.
&Get_JPGs - Migration function, passes all arguments to &Get_IMGs and returns everything it returns.
&Get_IMGs - TAKES: A scalar folder path. RETURNS: An array of files ending with a valid @IMGEXTENSIONS (case insensitive) within the path.
&Been_Done - TAKES: A scalar folder path. RETURNS: BOOLEAN if the path folder has had thumbnails made.
&Make_Thumb - TAKES: A scalar folder path, name of the graphic to be thumbnailed. RETURNS: Void. DOES: Creates a thumbnail of the image, names it t_imagename and saves it in the thumbs/ subdirectory of the provided folder path. The thumb will be $THUMB_WIDTH x $THUMB_HEIGHT.
&Make_Sane_Thumb - TAKES: A scalar folder path, name of the graphic to be thumbnailed. RETURNS: Void. DOES: Creates a thumbnail of the image, names it t_imagename and saves it in the thumbs/ subdirectory of the provided folder path. Unlike &Make_Thumb, however, this function uses math *gasp* to keep the width/height ratios the same for the thumbs as the original picture and as close to $THUMB_WIDTH and $THUMB_HEIGHT as possible.
&Resize_Graphic - TAKES: A scalar of the path to the file to be resized, a scalar of the path to where the resized file should go, the resized width, the resized height. RETURNS: Void.
&Get_Dimensions - TAKES: A scalar file path. RETURNS: width of graphic, height of graphic
The index.txt file
The index.txt files in every gallery, help PGTK to properly display your galleries. The format for these files is:
- Line 1: Title of the gallery (will be displayed in the gallery index)
- Line 2: Description of the gallery
- Line 3: Either the name of a thumbnail to display on the index page, or an asterisk (*) to have PGTK randomly choose one from the gallery.
- Subsequent lines: Description of photo - PHOTONAME.JPG
The photo description may contain HTML markup, but don't embed links (href) or images (img) in the descriptions. You can use comments for that. There can be only one dash in these lines, and it is used to separate the description, from the filename of the photo. If you want to display a dash in the description, use two successive equal signs (==), and they will be displayed as a single dash.
Comments are lines preceded by a pound sign (#). They are sent literally to the browser, and may contain any form of HTML code. Make sure you close any HTML tags you open.
See the enclosed index.txt.sample for an example.
In Development
- Web-based gallery administration tool
Quick Start
- Make sure your webserver is configured to execute CGI's properly
- (optional) configure your webserver to use "index.pl" as a "default page" (for Apache, use the DirectoryIndex directive)
- Place the index.pl script inside of your webspace where you want people to access your gallery (I use /projects/photos/ - But you can use anything)
- Place the PGTK folder and its contents either in the same folder as index.pl from above, or elsewhere in your Perl path (I use /usr/lib/perl5/site_perl/)
- Configure the PGTK/config.pm file to represent the correct paths for your system (mine are given as examples)
- Place your photos in separate folders we'll call galleries, and the galleries in the folder defined by PGTK::config::$base. In each of those galleries, you need an index.txt file. The format is described here.
- Point your web browser at your gallery script, and enjoy.
Availability
PGTK 2.0 is currently available.
Security NOTE: Do not leave the utils/ folder within active webspace!