Voidspace

rest2web: Building Websites Across the Known Universe

Picture Galleries and Beyond

Author: Fuzzyman
Date: 2005/08/12
Version: 0.2.0
Homepage:Gallery Page

Introduction

The gallery acts as a plugin to rest2web. (It can also fuction as a standalone program). It generates an html gallery page from a directory of images, an html template, and a few settings.

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.

You can see the sort of output it generates with the online example, which acts as the gallery test site in the rest2web distribution.

If you are viewing this from the test docs, you can build the test gallery by running [1] :

rest2web.py gallery_test.ini

You can then view the gallery at gallery index.

Downloading

At some point I will package the gallery on it's own. Currently it's only available bundled with rest2web.

Using Gallery 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 :

plugins: gallery

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.

uservalues Settings

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.

Standalone Program

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 [2] ; or just version 0.2.0 (or higher) of pythonutils [3].

By default the gallery looks for a config file called gallery.ini. You can also specify an alternative config file at the command line [4].

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.

The Settings

Most of the settings have the same meaning however you use gallery.

  • thumb_size -> width, height

    e.g. 150, 150

    This is the maximum size of the generated thumbnails. It keeps the proportions of the original image.

  • gallery_dir -> path to directory

    e.g. ../../FTP Mirror/gallery

    This is the path from the file to the directory of images.

  • gallery_url -> url path

    e.g. gallery

    The final url path from the gallery to the image directory. This path is used to make paths for all the images/thumbnails/pages.

    Note

    When run as a standalone program, the image directory should be in a single subdirectory from the main gallery. Hopefully this limitation will be removed soon.

  • data_file -> filepath

    e.g. gallery_data.ini

    This is the data file that stores details of all the image files and thumbnails. See the Gallery Data File section for details.

  • page_template -> filepath

    e.g. page.html

    The path to the template file for the individual pages. See The Templates for details.

  • entry_template -> filepath

    e.g. entry.html

    The path to the template file for every thumbnail on the main page. See The Templates for details.

  • gallery_mode -> 1 or 2

    e.g. 1

    Whether gallery should scan all the images (1), or just use the stored data file to generate the pages (2). See the Gallery Data File section for details.

Standalone Specific Settings

These next two settings are only used when gallery.py is run as a standalone program.

  • gallery_template -> filepath

    e.g. gallery.html

    This is the template file used to create the main gallery page.

  • gallery_page -> filepath

    e.g. gallery_page.html

    This is the filename to save the main gallery page as. See The Templates for details.

Gallery Data File

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 [5] - one section per image !

If you have pythonutils 0.3.0 [6] (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.

Warning

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 :

  1. Title - by default gallery generates a title for the image based on the filename. It replaces '_' with spaces and capitalizes words.

  2. Description - You can put an optional description for the image here. This will appear below the image, on it's page.

    Note

    Entering a description with several lines is only possible with pythonutils 0.3.0 or higher (or configobj 4).

    If you have pythonutils 0.3.0, you should surround entries with multiple lines between triple quotes - '''like this'''.

Gallery Mode

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.

The Templates

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 :

  • entry_template

    This is a small template. It is used for every thumbnail and link in the main gallery page.

  • page_template

    This is the template used to make each page (the ones containing the individual images).

  • gallery_template

    This is only used when running as a standalone program. It is used to make the main page with all the thumbnails on.

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.

Note

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.

entry_template

This template is used for every thumbnail and link in the main gallery page.

The special values are :

  • **link**

    Link to the image page.

  • **thumb**

    Path to the thumbnail (for the img tag).

  • **width**

    Thumbnail width.

  • **height**

    Thumbnail height.

  • **title**

    Image title.

page_template

This is the template used to make each page (the ones containing the individual images).

The special values are :

  • **title**

    The image title. Used as the page title, and as a heading above the image.

  • <!-- **leftcomment**

  • **leftcomment** -->

  • <!-- **rightcomment**

  • **rightcomment** -->

    In the template the 'previous image' and 'next image' are commented out. If they are needed in the page, the comment markers are removed.

    Obviously, the first image doesn't have a previous (left) image, and the last doesn't have a next (right).

  • **linkleft**

  • **linkright**

    These are the links to the previous and next image pages.

  • **thumbleft**

  • **thumbright**

    These are the paths to the thumbnails for the previous and next images.

  • **widthleft**

  • **heightleft**

  • **widthright**

  • **heightright**

    The widths and heights for the next/previous thumbnails.

  • **titleleft**

  • **titleright**

    The image titles for the next/previous thumbnails.

  • **linkgallery**

    The link back to the main gallery page.

  • **image**

    The path to the actual image.

  • **widthmain**

  • **heightmain**

    The width and height of the actual image.

  • **description**

    Guess what !

gallery_template

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 :

  • **gallery**

    This is replaced with the html containing all the thumnail images and links.

Using the Output

..note:

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 [7].

The output for the main page contains thumbnails with links to the individual pages. It is made up from the entry template - with the value

filled in for each image. You would normally use it with something like :

<% gallery %>

TODO

The gallery is still experimental ('alpha' quality). I need to check the following things.

  • XXXX Does it delete thumbnails and html pages for deleted images ?
  • XXXX Sort html for multi-line descriptions.
  • XXXX check "file_error" works
  • XXXX If the page format is reST, the ouput is indented and put inside a .. raw:: html directive.
  • XXXX except - shouldn't use plugins with reST

Footnotes

[1]On Windoze you can just double click on gallery_test.bat.
[2]Installed means somewhere on your normal PYTHONPATH.
[3]Version 0.2.0 was the first to include urlpath, which gallery.py needs in order to run.
[4]Or by creating a bat file if you use windoze and are unfamiliar with the command line. To run gallery.py with gallery.ini, create a text file called gallery.bat - with python gallery.py gallery.ini. Double clicking on gallery.bat should then run gallery.py with the correct config file.
[5]It uses ConfigObj to read/write the 'INI' style config files.
[6]Which has ConfigObj 4 - this retains the order of entries in config files.
[7]Except currently plugins are not compatible with pages in reST format. That will be fixed soon.

Return to Top
Part of the rest2web Docs
Page last modified Thu Mar 30 17:04:24 2006.


Site Built with rest2web SourceForge.net Logo Certified Open Source

Python on Voidspace