RubyPhoto

Home page:
http://plig.net/~ture/rubyphoto/ 		Authors:
Mark Hulme-Jones <ture@plig.netg>
Adam Spiers <adam@spiers.net>

Contents

Description

RubyPhoto is a program for creating image galleries for the web. It recurses through a directory tree creating album index files for each sub-directory and image index files and thumbnails of specified sizes for each image. The generated HTML is completely customisable via templates. All configuration and image/album information is supplied in XML files.

Examples of the type of output the program can generate can be found on Adam's photo page.

RubyPhoto was inspired by the swigs program, written in Perl, though RubyPhoto is a complete, from-scratch re-write. There are a couple of scripts provided with RubyPhoto that allow you to convert the album and image files used by swigs over to the format used by RubyPhoto. You can find these in the swigs-converters/ directory of the RubyPhoto distribution.

Requirements

Installation Instructions

  1. Unpack the tarball.
  2. Install all the required software (see Requirements above). You may need to set the RUBYLIB environment variable if you install the ruby libraries in a non-standard place.
  3. Make a directory called ~/.rubyphoto-templates and copy templates/* from RubyPhoto's directory into ~/.rubyphoto-templates. Alternatively, if you've unpacked the tarball into a place where you plan on keeping it, you can simply make ~/.rubyphoto-templates a symlink to the templates/ sub-directory.
  4. If you want to change settings from the default configuration, copy sample_input/config.xml to ~/.rubyphoto-conf and edit it. The file only needs to contain settings which deviate from the defaults, so you could optionally delete any settings you don't want to override; then if you upgrade to a newer rubyphoto at a later date, you would automatically get any changes in the default settings.
  5. Ensure the path to the ruby interpreter at the top of ruby_photo.rb is pointing to the place where you have Ruby installed.
  6. Copy the rubyphoto.css stylesheet and granitesm_*.gif icons from the sample_input/ subdirectory to your top level photo directory. In this directory, create a file called .rubyphoto-ignore which contains granitesm_*.gif (see Ignore Files below).

Running RubyPhoto

All you need to do if you want to be up and running really quickly is to change to the directory with your images in it and run: 

  /path/to/rubyphoto/ruby_photo.rb

RubyPhoto should do all the rest of the work for you. However, this does not take advantage of many of the more advanced possibilities open to you with RubyPhoto. For details of each of these, see below.

For more information on running RubyPhoto, invoke ruby_photo.rb with the --help command line option.

Configuration File

The config file (see the example in sample_input/config.xml in the RubyPhoto distribution directory) is a reasonably simple XML file. In addition to the global config file (~/.rubyphoto-conf) you can also override the global configuration on a per-directory basis, by including a file called config.xml in a particular directory. You can also point RubyPhoto at a configuration file with the --config command-line option.

The top-level environment in a RubyPhoto config file is <config>, and within this are three different sections:

Album XML Files

Each directory, or sub-album, may contain an album.xml file, allowing you to configure things like the title to be used in links to that album. For an example album XML file see sample_input/album.xml in the RubyPhoto distribution. Inside the top-level <album> environment there are four valid elements:

<title>
The title of the album. Used in links to the album, and at the top of each album page.
<shortdesc>
Description of the album used next to each link to the album, and at the top of the album page if no <longdesc> is provided.
<longdesc>
Description of the album used at the top of the album page.
<thumbnail>
Image used next to links to this album (defaults to the first image in the album, or if the album contains no images, the first image in the first sub-album of that album). The filename may be a path to an image, eg. foo/bar/baz.jpg

Image XML Files

Each image in your album may have an associated XML file containing details about the image. The exact fields that are valid in these files are specified in the <photofields> section of the configuration file (see Configuration File, above). See sample_input/example.jpg.xml in the RubyPhoto distribution for an example.

Ignore Files

Ignore files enable you to tell RubyPhoto to ignore particular files and/or directories. RubyPhoto allows you to specify both a global ignore list file, and an ignore list for each directory (sub-album). The global ignore file is usually called ~/.rubyphoto-ignore (though this can be changed with the ignore_file configuration option). Per-directory ignore lists are called the same thing, only you put them in a particular album's directory instead of in your home directory.

Template Files

RubyPhoto uses four different template files to generate its final HTML output. These are all kept in the ~/.rubyphoto-templates directory. Template files consist of XML element pairs for each part of the page (eg. <pageheader> for the header of an image page). In order to include HTML inside these XML element pairs, XML CDATA sections are used (see the template files for an example of how this works).

The four template files are:

image.xml
used to generate the individual image pages
album.xml
used to generate album pages
tree.xml
used to generate the 'tree' page
shared.xml
templates which are commonly used by more than one of the above files, via the {foo} template include mechanism described below. They typically contain HTML page headers, the HTML for navigation icons, etc.

In the first three of these files, text to be replaced appears inside brackets, [ and ], and should be upper-case. For example, in image.xml, the text [TITLE] will be replaced with the title of the image for which the page is being generated.

Templates may recursively include other templates using curly braces. For example, a template foo may include within itself the contents of a template bar by referencing it as {bar}.

The best thing to do to get a feel for the template files is to take a look at them yourself. A full template reference may follow some time in the future...

Extras

In the swigs-converters/ sub-directory are some scripts for converting from swigs format album and image files over to RubyPhoto ones, and in the xml-generators/ sub-directory are some Zsh scripts you can use to create album and image XML files. Note that the Zsh scripts probably require a recent-ish version of Zsh.

Config Option Reference

album_file
Default: album.xml
The name of the file in which to look for album information.
index_file
Default: index.html
The name of the file to output for an album index page.
drop_index
Default: yes
Whether to omit the index file when creating links to album indices, in other words, a link to an album foo will look like: 
      <a href="blah/blah/foo/">Foo</a>
rather than 
      <a href="blah/blah/foo/index.html">Foo</a>

The former makes for cleaner links, but will only work if your images are only being viewed from a webserver which is configured to interpret such links as references to the index page (this should be true by default on virtually all webservers).

tree_file
Default: tree.html
The name of the file to output for the tree page.
ignore_file
Default: .rubyphoto-ignore
The file to search for the list of files to ignore.
table_columns
Default: 6
The number of columns of thumbnails you want to appear on each album page.
table_rows
Default: 4
The number of rows of thumbnails you want to appear on each album page.
thumb_width
Default: 100
The width (in pixels) of each thumbnail on an album page.
thumb_height
Default: 100
The height (in pixels) of each thumbnail on an album page.
sort_photos_by and sort_subalbums_by
Default: filename and title respectively
Possible values: filename, title, mtime, date, order_field

The order in which to display the photo and subalbum thumbnails respectively on an album page. date sorts lexically by the contents of the date field, and order_field numerically (you can use non-integers) by the contents of the order field. If a photo is missing the order field, it will come after all photos which have the order field. You can reverse the sense of the sorting order by including an order="reverse" attribute.

min_best_width
Default: 301
When working out which of the image pages to link a thumbnail to, this is used as a threshold value. If the only available image page to link to has a width smaller than this threshold, then the link will be made to the Original image page instead.
min_best_height
Default: 201
When working out which of the image pages to link a thumbnail to, this is used as a threshold value. If the only available image page to link to has a height smaller than this threshold, then the link will be made to the Original image page instead.

For each of these <option> tags, you may also specify an inherit="no" attribute, which inhibits subdirectories from inheriting this particular setting.