Picture Galleries and Beyond
The Gallery Plugin
It creates a single main gallery page, with thumbnails that act as links to each image. The images themselves appear on their own page, with a title and optional description. Each page has links to the next and previous images, and back to the main gallery.
If you are viewing this from the test docs, you can build the test gallery by running  :
You can then view the gallery at gallery index.
At some point I will package the gallery on it's own. Currently it's only available bundled with rest2web.
In order to use it with rest2web, gallery.py needs to be available in the plugins subdirectory of rest2web - and also PIL must be installed.
In order to use the gallery in a page, you must have 'gallery' in your list of plugins for the page. This is done in the restindex, with a line like :
Next you must specify a set of values that tell the gallery what to do. When run as a plugin you specify these as uservalues.
The settings control the gallery program, they specify which directory to read the images from, which templates to use to generate the output pages, and so on.
All the settings must be present, or the gallery will raise an error. Assuming you have no other uservalues, the settings look like :
uservalues thumb_size = 150, 150 gallery_dir = ../../FTP Mirror/gallery gallery_url = gallery data_file = gallery_data.ini page_template = page.html entry_template = entry.html gallery_mode = 1 /uservalues
See the settings section for an explanation of what they all mean.
gallery.py will work as a standalone program as well as a plugin to rest2web. It uses the same settings, but gets them from a config file instead of uservalues.
One of the main reasons to make gallery.py run in this way, was so that Aidan could use it for his online Pages of Computer Imagery.
In order to use gallery.py as a standalone program, you will need Python 2.3 or later and a recent version of PIL. You will also need either pythonutils 0.20 and rest2web installed  ; or just version 0.2.0 (or higher) of pythonutils .
By default the gallery looks for a config file called gallery.ini. You can also specify an alternative config file at the command line .
All the settings need to be present or the gallery will raise an error. The complete settings are :
thumb_size = 150, 150 gallery_dir = ../../FTP Mirror/gallery gallery_url = gallery data_file = gallery_data.ini page_template = page.html entry_template = entry.html gallery_template = gallery.html gallery_mode = 1 gallery_page = gallery_page.html
See the settings for what they mean.
Most of the settings have the same meaning however you use gallery.
These next two settings are only used when gallery.py is run as a standalone program.
The gallery data file won't exist until the first time you run gallery.
When gallery.py runs it scans the image directory and stores the details of each image. It puts all the thumbnails in a 'thumbnail' subdirectory of the image directory. It puts all the html pages it creates in an 'html' subdirectory of the image directory. If these directories don't exist, it will create them.
The datafile it creates is effectively a config file with sections  - one section per image !
If you have pythonutils 0.3.0  (or more recent) then the order of these sections will be the order that images appear in the gallery. This means you can cut and paste to edit the order.
If you run gallery (in mode 1) after removing any images from the image directory - it will remove their entry from the data file.
There are two other entries that you can edit per image :
The details it stores in the data file are sufficient to generate the main gallery page and all the individual pages, without having to scan the image directory again.
If gallery_mode is set to 2 (see The Settings), then gallery won't scan the image directory. Not only is this quicker - but it can be useful when you have finalised the contents of a gallery and want to move the images.
If you do want gallery to scan the image directory, set gallery_mode to 1. This won't overwrite any titles or descriptions, but it will add new images and remove entries for ones you've deleted. You can also use it to regenerate thumbnails if you change their size.
gallery.py generates it's output from html templates that you supply. It fills in values in the template with things like the path to the image or thumbnail, it's height, width, or title, and so on.
If you are using gallery from rest2web there are two templates. If you are running it on it's own there are three. You need to supply the path to each of these files in the settings.
Obviously a good place to start is by looking at the example ones provided.
The three templates are :
The templates have various entries in them, that gallery replaces with the right values for the pages it is building. They all look like **some name**. When you edit the templates, you must keep these for the page to work.
In fact it won't cause an error to remove any of the special entries from the templates - that value will just be missing from the final pages. You can use this to further customize the appearance of your galleries.
This template is used for every thumbnail and link in the main gallery page.
The special values are :
This is the template used to make each page (the ones containing the individual images).
The special values are :
This template is only needed (or used) when running gallery.py as a standalone program. It is used to make the main page with all the thumbnails on.
The only special value is :
This section is only relevant when the gallery is used from rest2web.
Using the output from the gallery in your page is very easy. It creates an extra value gallery to use in your page.
If the page format is reST, the ouput is indented and put inside a .. raw:: html directive .
The gallery is still experimental ('alpha' quality). I need to check the following things.