NAME

Apache::App::Gallery::Simple - Elegant and fast filesystem-based image galleries

SYNOPSIS

  <Location /photos>
    SetHandler  perl-script
    PerlHandler Apache::App::Gallery::Simple;
    PerlSetVar  GalleryRoot    /vacation/images
    PerlSetVar  GalleryName    "My Vacation Photos"
  </Location>

  <Location /~hawkeye/photos>
    SetHandler perl-script
    PerlHandler Apache::App::Gallery::Simple
    PerlSetVar  GalleryRoot /images
    PerlSetVar  GalleryName "Hawkeye's Pictures"
    PerlSetVar  ThumbWidth  250
  </Location>

DESCRIPTION

Gallery::Simple creates navigable thumbnail galleries from directories with images on your web server. Gallery::Simple is completely configurable via a simple template system, allows for image captions as well as multimedia support, and also allows you to specify multiple languages for your templates and captions. The rest of this document is just the details.

Gallery::Simple creates an image gallery (complete with thumbnails and navigation links) from a directory or directory hierarchy on a web server. Simply upload images to a directory and the work is done. You can add captions to your images or other media (e.g., movies; see "ALTERNATIVE MEDIA") and the entire Gallery::Simple application is customizable using a simple template system (see "TEMPLATES").

I wanted an image gallery that was as easy to setup and use as Apache::Album but that offered a little more flexibility with captions, style/layout (including CSS or other customizations).

Some effort has been made to retain some of the Apache::Album configuration directives, if not in name, at least in spirit. You should also be able to use existing thumbnail directories if you're migrating from Apache::Album.

Using Gallery::Simple is, well, simple. There are no configuration files or anything of that sort (other than the Apache directives described in "OPTIONS"). All you have to do is install it, add something like the Location block shown above in "SYNOPSIS" section, and the path specified in GalleryRoot has suddenly become an image gallery.

There are a few features that are not implemented that Apache::Album does implement, namely:

  - slideshow
  - browser-based uploads and gallery configuration
  - image sorting
  - variable image size viewing

Gallery::Simple does do a couple of things well, however. It allows you to put captions to your images. It allows you to link to an alternative media source in the image page, which means you can also upload movies and other such stuff into your gallery. It allows template sets and caption files for multiple languages, meaning web visitors who prefer to see your site in Spanish may do so, while the German readers can see German galleries.

Gallery::Simple handles virtual hosted domains and even handles "tilde-dirs" or directories using Apache's UserDir directive in the form of http://www.foo.dom/~bar/baz.

Further, Gallery::Simple also allows you to completely customize the HTML returned for a particular gallery and an image page (you could even customize it to return XML if you wanted). You can add style sheets, alter (even replace) the layout so that it integrates cleanly with your existing web site.

A quick example

Say you have a directory under your DocumentRoot (e.g., /usr/home/joe/www) called /family/images that contains digital photos (full path: /usr/home/joe/www/family/images) and you want people to access this location with the following url:

    http://www.joesfamily.org/gallery/

Add the following block to your Apache configuration file:

  <VirtualHost joesfamily.org>
    ServerName    joesfamily.org
    DocumentRoot  /usr/home/joe/www
    ...
  
    ## this is the gallery section you've just added
    <IfModule mod_perl.c>
      PerlWarn       On
      PerlTaintCheck On

      <Location /gallery>
        SetHandler perl-script
        PerlHandler Apache::App::Gallery::Simple
        PerlSetVar  GalleryRoot  /family/images
        PerlSetVar  GalleryName  "Joe's Photo Gallery"
      </Location>
    </IfModule>
  </VirtualHost>

Browsers accessing the url http://www.joesfamily.org/gallery/ will be looking at the images in /home/joe/www/family/images.

OPTIONS

The following options are available in the Apache configuration file with the PerlSetVar directive.

GalleryRoot

Default: (empty)

Values: The physical path to the image gallery, relative to the document root (for Apache UserDir directories, this is often /home/username/htdocs or something like that).

Description: this setting determines where Gallery::Simple looks for your image gallery. All image files and directories rooted at this location will be part of the gallery.

Paths should be specified without a leading slash; paths will be relative to the document root (Apache's DocumentRoot) for this virtual host. Special care has been take to make this work for hosts using Apache's UserDir directive (i.e., "tilde-user" URIs such as "~joe") as well.

GalleryName

Default: (empty)

Values: Any string value

Description: this is the name of your "top" gallery; sub-gallery names may be specified in the caption.txt file.

GalleryLang

Default: en

Values: Any ISO-639 language code

Description: this setting determines what language the default caption.txt file services. Browser clients send an ordered list of preferred languages; Gallery::Simple uses this data to select which caption.txt file to read.

For example, if a browser prefers Spanish content to English, it might send "es, en" in its request. Gallery::Simple detects this and will look for caption.txt.es and then caption.txt for caption information. If GalleryLang is set to 'es', then Gallery::Simple will assume that caption.txt is in Spanish and look for caption.txt and then caption.txt.en for caption information.

Gallery::Simple automatically tries major language preference if a minor language preference fails. For example, if 'en-US' does not exist, 'en' will be tried next (and not tried again, even if, for example, 'en-UK' were preferred second).

LanguageStrict

Default: no

Values: [yes|no]

Description: when disabled, Gallery::Simple will try (for example) 'en-us' first (assuming 'en-us' were passed in by the browser) and then fall back to 'en' (the major language type).

If LanguageStrict is set to 'yes', only languages explicitly passed in by the browser will be attempted (e.g., in our above example, 'en' would not be tried if 'en-us' were not found).

OtherGalleryLinks

Default: on

Values: [on|off]

Description: when disabled, no "Other galleries" message will display showing sub-galleries within this directory. You may still access sub-galleries using the caption.txt file (see "Sub-Gallery Thumbnails" under "CAPTION FILES").

AlwaysLink

Default: no

Values: [yes|no]

Description: when enabled, non-image media files (e.g., movies, etc.) will simply appear as a link below the image on the representative image page. When disabled, thumbnails and image navigation links will load a page with the multimedia file embedded (as if it were an image).

ThumbUse

Default: width

Values: width, height, aspect

Description: this setting determines how to thumbnail an image; width means that the value in ThumbWidth will be used and the height will scale accordingly; height means that the value in ThumbHeight will be used and the width will scale accordingly; aspect means that the ratio in ThumbAspect will be used and the height and width will scale by that factor.

ThumbWidth

Default: 100

Values: any positive integer value

Description: this setting is used when ThumbUse is set to width. This determines how wide the thumbnails will be. The height will be scaled to preserve the original image's width/height ratio.

ThumbHeight

Default: 100

Values: any positive integer value

Description: this setting is used when ThumbUse is set to height. This determines how high the thumbnails will be. The width will be scaled to preserve the original image's width/height ratio.

ThumbAspect

Default: 1/5

Values: any fractional value; may be expressed as a decimal number

Description: this setting will scale all images by this amount. The default (1/5) means that the image will be 1/5 of its original size.

ThumbDir

Default: .thumbs

Values: any valid directory name

Description: this is the name of the directory that will be created to store thumbnails. Only filenames (no pathnames containing '/') are allowed. A ThumbDir will be created in each gallery directory where images are found.

ThumbPrefix

Default: tn__

Values: any string of characters (no '/').

Description: this value will be prepended to each thumbnail image to distinguish it from a regular image.

ThumbColumns

Default: 0

Values: zero (0) or any positive integer value

Description: this determines the number of columns in the thumbnail gallery. This setting overrides the calcuated setting determined by BrowserWidth and can be set to any positive integer value.

BrowserWidth

Default: 640

Values: any positive integer value

Description: this setting determines the optimal browser width for your visitors. The number of columns displayed is determined by dividing the BrowserWidth setting by ThumbWidth (even if ThumbHeight is being used). For example, if BrowserWidth is set to 640 and ThumbWidth is set to 100, then there will be 640/100 = 6 columns of thumbnails in each gallery.

BreadcrumbHome

Default: off

Values: [on|off]

Description: when enabled, displays a link to the URL of '/' ("home") in the breadcrumb navigation links in a gallery.

CaptionFile

Default: caption.txt

Values: any valid filename

Description: this is the name of the file where image caption information will be stored. Only filenames (no pathnames containing '/') are allowed. If a CaptionFile exists, it will be read and captions found will be displayed with the image. More information about caption files may be found in "CAPTION FILES".

TemplateDir

Default: .templates

Values: any valid directory name

Description: this is the name of the directory where you will store your templates, if you wish to override the default look-and-feel of Gallery::Simple. This directory is always found in the GalleryRoot directory. Only filenames (no pathnames containing '/') are allowed. More information about templates may be found in "TEMPLATES".

ALTERNATIVE MEDIA

You can have non-image media (audio clips, movies, etc.) in your gallery, too, as long as you have an image to represent it. Upload your non-image media just as you would an image. Additionally, you'll need to upload an image that represents your media. For example, if your alternative media were a movie, you might take a screen capture of it and use that as your representative image.

Once you've uploaded the media file and a representative image, you'll then need to create a file called caption.txt in the same directory you uploaded the image to. The file should contain a line like the following:

    picnic.jpg:picnic.mov;320;255:First Summer Picnic

picnic.jpg is the name of your representative image; picnic.mov is your movie file (with dimensions), followed by the caption. Now when people browse your gallery, they'll see picnic.jpg in the thumbnail gallery. If they click the image, they'll be taken to a page that contains picnic.mov as an embedded movie.

[If AlwaysLink is enabled, a larger version of the representative image is shown, just as a normal image would, but there will also be a link beneath the image which links to the alternative media file.]

For more information about the caption file see "CAPTION FILES". For more information about customizing the look of the gallery, see "TEMPLATES".

CAPTION FILES

The format of a caption file is this:

  imagename:linkname:some caption text

imagename is the name of the image (in this directory) that the caption relates to. imagename is case-sensitive. linkname is optional.

linkname is a link where another media file (such as a Quicktime movie, mpeg file, or even a sub-directory) may be found (the file or directory must be in the same directory as the caption.txt file it is referenced in).

The final field is where you can put a brief (or long--it goes until the next newline character) description of this image. Here is a sample directory listing:

  January
  melissa.jpg
  jared.jpg
  PB140011.JPG
  joe_burns.mov
  joe_tabasco.jpg

and the corresponding caption file:

  January::January 2003
  melissa::Melissa shakes hands with Tom
  jared.jpg::Jared turfs it
  joe_tabasco.jpg:joe_burns.mov;320;255:Joe eating Tabasco sauce

We notice the following things about these images and the corresponding caption file:

January

This is a directory within our gallery; this will be treated as a "sub-gallery". The 'linkname' space is empty ("::") and is currently not used with sub-galleries. The directory will appear with the link "January 2003" instead of just "January".

melissa.jpg

This image has no alternative media--the 'linkname' space is empty ("::"). This image does have a comment (caption): "Melissa shakes hands with Tom".

jared.jpg

This image is like the previous one: no alternative media, but it does have a caption.

PB140011.JPG

This image is not mentioned in the caption file--no caption will be printed for this image.

joe_tabasco.jpg

A thumbnail of this image will appear in the gallery (thumbnail) page; when the thumbnail link is followed, a page with a movie file (joe_burns.mov) will appear along with the caption "Joe eating Tabasco sauce".

It is necessary to supply the width and height of the movie (in that order) with semicolons in the "link" field of the caption.txt file:

    joe_burns.mov;320;255

This is for correct rendering in Internet Explorer. The height should also include (the author has found by experimentation) about a 15 pixel buffer to show the movie player controls. This may not be enough (or too much) for your media player. If you are aware of a better way to embed multimedia content in web pages, please contact the author.

Sub-Gallery Thumbnails

Another interesting use for the 'linkname' space is that you can create picture representations of sub-galleries. For example, consider this entry:

    vacation.png:vacation-2001/:2001 Summer Vacation Photos

When someone clicks the vacation.png thumbnail, they'll be taken not to the vacation.png image (if the 'linkname' space did not reference a directory), but to a sub-gallery named vacation-2001.

You don't need to do sub-galleries this way, of course. It is done automatically for you with links on the left side of the screen under "Other galleries", but this provides yet another (graphical) way to do it.

TEMPLATES

Gallery::Simple image galleries and image pages may be customized on a per-gallery basis (i.e., per-virtualhost or per UserDir, but not per-subdirectory). This means that you can have one image gallery for your brother-in-law and allow him to make his gallery appear as he wants, and another gallery for Mom and allow her to customize her gallery in her way.

The Gallery::Simple template system is based on Template::Trivial (see Template::Trivial), a fast, minimalistic template system. Gallery::Simple has two template sets:

• thumbnail gallery ("gallery") templates (and associated template variables)

• image page templates (and associated template variables)

Each of these sets of templates (including template variables) are described below.

To customize a whole or part of the look (HTML) of Gallery::Simple, all you need to do is create (or edit, if the template already exists) a template file and upload it to a directory called .templates (see "TemplateDir") in the directory you have designated as the gallery root (see "GalleryRoot").

Gallery::Simple will automatically detect the new template and use it for the next browser request. No server restart is necessary.

Associated with each template are zero or more template variables; these variables are assigned values during the browser request (and the value assigned depends on the current gallery, the caption file and other environmental factors).

You may insert, rearrange, or remove template variables from the templates to achieve a new gallery and image page look. Please refer to Template::Trivial for more details on how to use templates.

In the sections below we describe the available templates and variables to customize any single Gallery::Simple gallery.

Gallery Templates

Gallery templates affect the HTML layout of the thumbnail gallery, including navigation links, the thumbnail table layout, "sub-galleries" (directories within the current gallery), breadcrumb links (top level navigation), etc.

The gallery template set consists of the following templates:

gallery_main.txt

Default value:

    <html>
    <head>
    <title>{GALLERY_NAME}</title>
    {GALLERY_STYLE}
    </head>
    
    <body>
    {GALLERY_TITLE}
    {BREADCRUMBS}
    {OTHER_GALLERIES}
    <center>
    <table width="400">
    <tr>
    <td width="25%">{DIR_FIRST}</td><td width="25%">{DIR_PREV}</td>
    <td width="25%">{DIR_NEXT}</a><td width="25%">{DIR_LAST}</td>
    </tr>
    </table>
    
    {GALLERY}
    </center>
    {GALLERY_FOOTER}
    </body>
    </html>

Variables: GALLERY_NAME, GALLERY_TITLE, GALLERY_STYLE, BREADCRUMBS, OTHER_GALLERIES, DIR_FIRST, DIR_PREV, DIR_NEXT, DIR_LAST, GALLERY

gallery_title.txt

Default value: (empty)

Variables: GALLERY_NAME

gallery_title_empty.txt

Default value: (empty)

gallery_style.txt

Default value:

    <style type="text/css">
    <!--
      body {
        font-family: Helvetica, sans-serif, Arial;
        font-size: large;
        color: #000000;
        background: none;
        margin: 20px;
      }
      p {
        margin: 15px;
      }
      td {
        text-align: center;
        vertical-align: top;
      }
      a {
        color: #BD9977;
        background: none;
        font-size: x-small;
        text-decoration: none;
      }
      img {
        border: 0
      }
      .breadcrumb {
        font-size: x-small;
        background: none;
      }
      .galleries {
        font-size: x-small;
        background: none;
      }
      .address {
        text-align: right;
        font-size: xx-small;
      }
    //-->
    </style>

gallery_footer.txt

Default value:

    <hr>
    <div class="address">
      <a href="http://scott.wiersdorf.org/perl/Apache-App-Gallery-Simple/">Apache::App::Gallery::Simple {VERSION}</a>
    </div>

Variables: VERSION

gallery_other.txt

Default value:

    <p class="galleries">Other galleries within this gallery:<br>
    {DIRECTORIES}</p>

Variables: DIRECTORIES

gallery_other_empty.txt

Default value:

    <p class="galleries">(No other galleries within this gallery)</p>

gallery_breadcrumbs.txt

Default value:

    <p class="breadcrumb">This gallery: {BREADCRUMB_PATH}</p>

gallery_breadcrumb.txt

Default value:

    &nbsp;<a href="{BREADCRUMB_LINK}">{BREADCRUMB}</a>&nbsp;-&gt;

Variables: BREADCRUMB_LINK, BREADCRUMB

gallery_deadcrumb.txt

Default value:

     {BREADCRUMB}

Variables: BREADCRUMB

gallery_homecrumb.txt

Default value:

    home

gallery_first.txt

Default value:

    <a href="{FIRST_LINK}">{FIRST_DEFAULT}</a>

Variables: FIRST_LINK, FIRST_DEFAULT, FIRST

gallery_first_empty.txt

Default value: (empty)

gallery_first_default.txt

Default value:

    First<br>Gallery

gallery_first_caption.txt

Default value:

    <br>({CAPTION})

Variable: CAPTION

gallery_previous.txt

Default value:

    <a href="{PREV_LINK}">{PREV_DEFAULT}{PREV}</a>

Variables: PREV_LINK, PREV_DEFAULT, PREV

gallery_previous_empty.txt

Default value: (empty)

gallery_previous_default.txt

Default value:

    Previous<br>Gallery

gallery_previous_caption.txt

Default value:

    <br>({CAPTION})

Variables: CAPTION

gallery_next.txt

Default value:

    <a href="{NEXT_LINK}">{NEXT_DEFAULT}{NEXT}</a>

Variables: NEXT_LINK, NEXT_DEFAULT, NEXT

gallery_next_empty.txt

Default value: (empty)

gallery_next_default.txt

Default value:

    Next<br>Gallery

gallery_next_caption.txt

Default value:

    <br>({CAPTION})

Variables: CAPTION

gallery_last.txt

Default value:

    <a href="{LAST_LINK}">{LAST_DEFAULT}</a>

Variables: LAST_LINK, LAST_DEFAULT, LAST

gallery_last_empty.txt

Default value: (empty)

gallery_last_default.txt

Default value:

    Last<br>Gallery

gallery_last_caption.txt

Default value:

    <br>({CAPTION})

Variables: CAPTION

gallery_dir_link.txt

Default value:

    <a href="{URI_DIR}">{DIRECTORY}</a><br>\n

Variables: URI_DIR, DIRECTORY

gallery_dir_caption.txt

Default value:

     ({CAPTION})

Variables: CAPTION

gallery_gallery_table.txt

Default value:

    <table>{ROWS}</table>

Variables: ROWS

gallery_gallery_empty.txt

Default value:

    <table><tr><td>(No photos in this gallery)</td></tr></table>

gallery_row_top.txt

Default value:

    <tr>

gallery_row_middle.txt

Default value:

    {ROW_END}{ROW_START}

Variables: ROW_END, ROW_START

gallery_row_bottom.txt

Default value:

    </tr>

gallery_cell.txt

Default value:

    <td align="center"><a href="{URI_IMAGE}"><img src="{URI_THUMB}" border="0"></a></td>

Variables: URI_IMAGE, URI_THUMB

Gallery Template Variables

We now describe the available template variables for the thumbnail gallery template set. Some variables are assigned template parse results ("parsed"), some variables are assigned a string ("assigned"), while other variables may be either parsed or assigned, depending on the context and other factors.

This is important to know which variables are parsed so that you know which templates to alter if you want to alter the contents of a variable. Variables whose value depends completely on environmental factors (such as working directory names, caption files, etc.) may not be altered via a template, but the variable may be removed or rearranged in its respective template.

BREADCRUMBS

Parsed (gallery_breadcrumbs.txt).

BREADCRUMB_PATH

Assigned. The path of directories up to the top level gallery as links. The current gallery is not a link.

BREADCRUMB

Assigned/parsed (gallery_homecrumb.txt). Part of the top level breadcrumb navigation; iteratively set to each path component (i.e., each directory name) up to the home directory. If a higher level directory has a caption in the caption file, this caption will be used instead.

BREADCRUMB_LINK

Assigned. Part of the top level breadcrumb navigation; alternatively set to each path component (i.e., each directory name) up to the home directory. This is part of the actual HTML link and should always be a valid URI.

BREADCRUMBS

Parsed (gallery_breadcumb.txt).

CAPTION

Assigned. Set to the comment or caption portion of the caption file.

DIRECTORIES

Parsed (gallery_dir_link.txt)

DIRECTORY

Assigned. Set to one of the directories or sub-directories within this directory.

FIRST

Assigned/parsed (gallery_first_caption.txt). If a caption is not available for this directory, the variable is set to an empty string.

This variable is not used in the default templates.

FIRST_DEFAULT

Parsed (gallery_first_default.txt).

FIRST_LINK

Assigned. Set to the URI of the first directory.

GALLERY_NAME

Assigned. Set to the caption for this directory, if any; otherwise set to the current relative URI.

GALLERY_TITLE

Parsed (gallery_title.txt, gallery_title_empty.txt).

GALLERY_NAME

Parsed (gallery_style.txt).

GALLERY_FOOTER

Parsed (gallery_footer.txt).

VERSION

Assigned. Set to the current version of Apache::App::Gallery::Simple.

LAST

analogous to FIRST

LAST_DEFAULT

analogous to FIRST_DEFAULT

LAST_LINK

analogous to FIRST_LINK

NEXT

Assigned/parsed (gallery_next_caption.txt). If a caption is not available for this directory, the variable is set to an empty string.

NEXT_DEFAULT

Parsed (gallery_next_default.txt).

NEXT_LINK

Assigned. Set to the URI of the next directory.

OTHER_GALLERIES

Parsed (gallery_other_empty.txt, gallery_other.txt).

PREV

Analogous to NEXT

PREV_DEFAULT

Analogous to NEXT_DEFAULT

PREV_LINK

Analogous to NEXT_LINK

ROWS

Parsed (gallery_row_top, gallery_row_middle, gallery_cell, gallery_row_bottom).

ROW_END

Parsed (gallery_row_bottom.txt).

ROW_START

Parsed (gallery_row_top.txt).

URI_DIR

Assigned. Set to the current directory name with trailing slash.

URI_IMAGE

Assigned. Set to the URI of the image name.

URI_THUMB

Assigned. Set to the URI of the image thumbnail.

Image Page Templates

Image page templates affect the image page HTML layout, including navigation links, additional media links, and the image itself.

The image page template set consists of the following templates:

image_main.txt

Default value:

    <html>
    <head>
    <title>{TITLE}</title>
    {IMAGE_STYLE}
    </head>
    <body>
    <center>
    <table width="400">
    <tr align="center" valign="top">
    <td width="20%">{IMG_FIRST}</td><td width="20%">{IMG_PREV}</td>
    <td width="20%">{DIR_UP}</a>
    <td width="20%">{IMG_NEXT}</a><td width="20%">{IMG_LAST}</td>
    </tr>
    </table>
    
    <table>
    <tr><td colspan="5">{MEDIA}</td></tr>
    <tr><td colspan="5">{LINK}{COMMENT}</td></tr>
    </table>
    </center>
    </body>
    </html>

Variables: TITLE, IMG_FIRST, IMG_PREV, DIR_UP, IMG_NEXT, IMG_LAST, MEDIA, LINK, COMMENT

image_media.txt

FIXME

image_style.txt

Default value:

    <style type="text/css">
    <!--
      body {
        font-family: Helvetica, sans-serif, Arial;
        font-size: large;
        background: none;
        color: #000000;
        margin: 20px;
      }
      p {
        margin: 15px;
      }
      td {
        text-align: center;
        vertical-align: top;
      }
      a {
        color: #BD9977;
        background: none;
        font-size: x-small;
        text-decoration: none
      }
      img {
        border: 0
      }
    //-->
    </style>

image_image.txt

Default value:

    <img src="{MEDIA_FILE}">

Variables: MEDIA_FILE

image_mov.txt

Default value:

<embed {MEDIA_SIZE}CONTROLLER="TRUE" SRC="{MEDIA_FILE}" AUTOSTART="TRUE" type="video/quicktime" BGCOLOR="#969696" LOOP="FALSE" BORDER="0" PLUGINSPAGE="http://www.apple.com/quicktime/download/indext.html"> </embed>

Variables: MEDIA_FILE, MEDIA_SIZE

image_mpeg.txt

Default value:

<embed {MEDIA_SIZE}CONTROLLER="TRUE" SRC="{MEDIA_FILE}" AUTOSTART="true" type="video/mpeg" BGCOLOR="#969696" LOOP="FALSE" BORDER="0"> </embed>

Variables: MEDIA_FILE, MEDIA_SIZE

image_avi.txt

Default value:

<embed {MEDIA_SIZE}CONTROLLER="TRUE" SRC="{MEDIA_FILE}" AUTOSTART="TRUE" type="video/x-msvideo" BGCOLOR="#969696" LOOP="FALSE" BORDER="0"> </embed>

Variables: MEDIA_FILE, MEDIA_SIZE

image_link.txt

Default value:

    <a href="{IMG_LINK}">More</a><br>

Variables: IMG_LINK

image_link_empty.txt

Default value: (empty)

image_up.txt

Default value:

    <a href="{UP_LINK}">{UP_DEFAULT}</a>

Variables: UP

image_up_default.txt

Default value:

    Back to<br>Gallery

image_first.txt

Default value:

    <a href="{FIRST_LINK}">{FIRST_DEFAULT}</a>

Variables: FIRST_LINK, FIRST_DEFAULT, FIRST_CAPTION

image_first_empty.txt

Default value: (empty)

first_default

Default value:

    First<br>Image

first_caption

Default value:

    <br>({CAPTION})

Variables: CAPTION

image_previous.txt

Default value:

    <a href="{PREVIOUS_LINK}">{PREVIOUS_DEFAULT}</a>

Variables: PREVIOUS_LINK, PREVIOUS_DEFAULT, PREVIOUS_CAPTION

image_previous_empty.txt

Default value: (empty)

image_previous_default.txt

Default value:

    Previous<br>Image

image_previous_caption.txt

Default value:

    <br>({CAPTION})

image_next.txt

Default value:

    <a href="{NEXT_LINK}">{NEXT_DEFAULT}</a>

Variables: NEXT_LINK, NEXT_DEFAULT, NEXT_CAPTION

image_next_empty.txt

Default value: (empty)

image_next_default.txt

Default value:

    Next<br>Image

image_next_caption.txt

Default value:

    <br>({CAPTION})

Variables: CAPTION

image_last.txt

Default value:

    <a href="{LAST_LINK}">{LAST_DEFAULT}</a>

Variables: LAST_LINK, LAST_DEFAULT, LAST_CAPTION

image_last_empty.txt

Default value: (empty)

image_last_default.txt

Default value:

    Last<br>Image

image_last_caption.txt

Default value:

    <br>({CAPTION})

Variables: CAPTION

Image Page Template Variables

We now describe the available template variables for the image page template set. Some variables are assigned template parse results ("parsed"), some variables are assigned a string ("assigned"), while other variables may be either parsed or assigned, depending on the context and other factors.

This is important to know which variables are parsed so that you know which templates to alter if you want to alter the contents of a variable. Variables whose value depends completely on environmental factors (such as working directory names, caption files, etc.) may not be altered via a template, but the variable may be removed or rearranged in its respective template.

TITLE

Assigned. Set to the image caption; if no caption is available, set to the image filename.

IMAGE_STYLE

Parsed (image_style.txt).

MEDIA_FILE

Assigned. Set to the real URI of the media file.

MEDIA_SIZE

Assigned. Set to the parameters from the caption.txt file. See "Multimedia Content" and "ALTERNATIVE MEDIA" for details.

IMG_FIRST

Parsed (image_first.txt, image_first_empty.txt).

IMG_PREV

Analogous to IMG_FIRST.

IMG_NEXT

Analogous to IMG_FIRST.

IMG_LAST

Analogous to IMG_FIRST.

IMG_LINK

Assigned. Set to the link field of the caption file, if applicable.

DIR_UP

Parsed (image_up.txt).

UP_LINK

Assigned. Set to the parent URI of the current image.

UP_DEFAULT

Parsed (image_up_default.txt).

FIRST_LINK

Assigned. Set to the first image URI in this gallery.

FIRST_DEFAULT

Parsed (image_first_default.txt).

FIRST_CAPTION

Parsed (image_first_caption.txt).

PREVIOUS_LINK

Analogous to FIRST_LINK

PREVIOUS_DEFAULT

Analogous to FIRST_DEFAULT

PREVIOUS_CAPTION

Analogous to FIRST_CAPTION

NEXT_LINK

Analogous to FIRST_LINK

NEXT_DEFAULT

Analogous to FIRST_DEFAULT

NEXT_CAPTION

Analogous to FIRST_CAPTION

LAST_LINK

Analogous to FIRST_LINK

LAST_DEFAULT

Analogous to FIRST_DEFAULT

LAST_CAPTION

Analogous to FIRST_CAPTION

MULTI-LANGUAGE SUPPORT

Gallery::Simple supports multiple languages for templates and caption files. The GalleryLang setting determines what language the caption.txt file will handle (be default, English). For example, suppose your web visitors are predominantly Spanish-speaking (or at least, Spanish-reading). You set GalleryLang in your Apache configuration file to 'es', which is the ISO-639 language code for Spanish.

Browsers that send the "Accept-Languages" header (most modern browsers do) and have "es" as their preferred language will receive the contents of the caption.txt file (because we told Gallery::Simple that 'es' was our default language for this gallery).

If you also want to service English-readers, you would create a caption.txt.en file that contained English captions. Now your English-reading visitors will be able to view your site in English.

The default setting for GalleryLang is 'en' (English). All incoming language codes are converted to lowercase, so you don't have to differentiate between 'en-US' and 'en-us'.

You may have as many caption.txt.(language code) files as you wish. If a caption is not available in one caption file and the browser specified alternative languages, the next caption file (if available) will be searched for a caption (also, if available).

You can also specify multi-language template directories in the same manner as caption files: simply name the template directory .templates.es (taking Spanish as our example again) for Spanish templates.

Template Changes Required for Multi-language Support

Every effort has been made to make adding additional languages to your gallery as painless as possible. To that end, all English text has been placed into small sets of small files.

To add Spanish support, for example, you would create .templates.es and change the template sets listed below. The default contents of these templates may be found elsewhere in this document.

The following gallery templates must be changed for multi-language support:

gallery_breadcrumbs.txt

gallery_first_default.txt

gallery_last_default.txt

gallery_next_default.txt

gallery_other.txt

gallery_other_empty.txt

gallery_previous_default.txt

The following image templates must be changed for multi-language support:

image_first_default.txt

image_last_default.txt

image_next_default.txt

image_previous_default.txt

image_up_default.txt

EXAMPLES

Here are a few simple examples of how to customize Gallery::Simple.

Gallery Columns

You wish to change the number of columns in the gallery. Use the ThumbColumns or BrowserWidth directive in the Apache configuration file.

Thumbnail size

You wish to change the size of the thumbnails in the gallery. Use the ThumbWidth directive in the Apache configuration file.

Alternative Gallery Navigation

You wish to use images instead of text for gallery navigation (moving between galleries). First you'll need to create some suitable images (e.g., arrows or something like that). Next, create (if it doesn't already exist) a directory named .templates (or whatever you may have TemplateDir set to) in the GalleryRoot directory (remember, GalleryRoot is relative to DocumentRoot for that virtual host or relative to the UserDir if this is a tilde-user account).

Next, create something like the following files, with the following contents in the templates directory (you should replace the image paths with the actual paths to your new images).

gallery_first.txt

    <a href="{FIRST_LINK}"><img src="/images/first.gif"></a>

gallery_previous.txt

    <a href="{PREV_LINK}"><img src="/images/previous.gif"></a>

gallery_next.txt

    <a href="{NEXT_LINK}"><img src="/images/next.gif"></a>

gallery_last.txt

    <a href="{LAST_LINK}"><img src="/images/last.gif"></a>

Image Captions

You wish to add a caption to an image. Create (or edit, if the file already exists) caption.txt (or the file specified by the CaptionFile directive in the Apache configuration file). Now add a line like the following:

    image1.jpg::Our House in the Evening

Multimedia Content

You wish to add a movie to your gallery. First create an image that will represent your movie (e.g., a video capture or something like that would be fine); upload both the movie and image to the gallery of your choice. Edit the caption.txt file in that gallery and add a line like the following:

    truck.jpg:truck.mov;320;255:A video clip of my truck

truck.jpg will be automatically thumbnailed and used in the thumbnail gallery. The thumbnail will link to a page that will play truck.mov (the dimensions of the movie are also specified for proper rendering in Internet Explorer). The movie will have a caption "A video clip of my truck" below it.

Multilanguage Captions

Some relatives in England want to see our pictures, but do not wish to see our barbaric Americanisms in the image captions. We can create a new caption file called caption.txt.en-uk for browsers that send 'en-uk' as their primary language preference.

Our default caption.txt file might look like this:

    highway.jpg::Two-way traffic
    soda.jpg::A carbonated beverage
    train.jpg::The subway
    watchout.jpg::Watch your step

While our caption.txt.en-uk file would contain these UK translations:

    highway.jpg::Dual carriageway
    soda.jpg::A fizzy drink
    train.jpg::The tube
    watchout.jpg::Mind the gap

Now web visitors whose browsers are configured to send 'en-uk' as their primary language preference will see the correct captions to our photos.

SAMPLES

The following sites run Apache::App::Gallery::Simple; if you want yours listed here, contact the author or current maintainer.

Tubbing Foundation of America

"Photo Album" link at http://www.tubbing.com/

TROUBLESHOOTING

The image pages work, but the thumbnail galleries come up with broken images

Make sure the image directory directory is writable by the UID that Apache runs as (usually www or nobody). This will allow Gallery::Simple to create a .thumbs directory (or whatever you have ThumbsDir set to) to write thumbnail images into. This means you have to 'chmod g+w photos' (or whatever directory that is) so that Gallery::Simple can create the thumbnail directory and populate it.

(Second favorite language) templates show up even though my default is set to English (and I am using the built-in Gallery::Simple templates)

This is the nature of the template system; to ensure that alternative templates are not attempted, create English templates in .templates--the same templates you used in your second favorite language.

Gallery::Simple will detect these templates and use them and not attempt to find other templates.

If this seems like a lot of work, you can also simply remove your second favorite language from your browser preferences.

If I get enough complaints about this, I'm likely to create an Apache directive that will stop at the default templates if they match the browser's language preference.

I don't like you you've done style sheets

I'm happy to receive criticism on my style sheets. I'm just learning how they work, so they'll likely contain bad, uh, style. I did put them in their own template, though, so they're easy enough to change.

I don't like the "No other galleries within this gallery" message

Create a .templates directory at your gallery root and create an empty file named gallery_other_empty.txt.

I really don't like the "No other galleries ..." message

Use the OtherGalleryLinks directive to disable all mention of sub-galleries (even if they exist).

Slow!

The first time a gallery is visited, all of the images must be "thumbnailed" (a copy of the image is reduced to a smaller size); this operation is somewhat slow, especially if you're waiting for it to happen in a browser.

Once this thumbnailing has taken place, however, the thumbnails will only have to be re-created if you alter the original image in some way, in which case Gallery::Simple will detect it and re-thumbnail the altered image.

I get an error when I update an image and then try to view the gallery

There was a bug in versions prior to 1.06 that triggered Perl's taint warning; update Gallery::Simple and all should be well (versions prior to 1.03 may have template compatibility issues if you have customized templates. If you don't have customized templates, you should not have a problem).

I can't delete the thumbnail directory, or anything in it

This is because your UID is different than your web server's. You have some options:

• become the UID of the web server (e.g., via 'su' or some other mechanism)

• run a CGI script under the UID of the web server that removes the directory

• create the thumbnail directory beforehand as your user (too late now, of course); then you'll own it and can delete it whenever you want to

• Upgrade to version 1.06 or later of this module. This will cause thumbnail directories to be deleted from otherwise empty galleries (i.e., galleries with no images)

SUPPORT

Additional documentation, alternative look template sets, alternative language template sets, and mailing list available at:

    http://scott.wiersdorf.org/perl/Apache-App-Gallery-Simple/

CAVEATS

• '&' in your caption.txt files should be replaced with '&amp;' <' should be replaced with '&lt;'

• The thumbnail directory must be writable by the UID that Apache runs under (usually www or nobody) in order for thumbnails to be written to disk. If the thumbnail directory does not exist, its parent directory must also be writable by Apache's UID.

SECURITY

Because Gallery::Simple writes image thumbnails with the UID that Apache runs under (e.g., 'nobody' or 'www', etc.), it is possible to trick Gallery::Simple to write into areas unintended by the administrator.

Every effort is made to ensure that Gallery::Simple does not write into unintended locations, but there are race conditions and possibly situations the author has not foreseen.

If you are an administrator and wish to offer Gallery::Simple to users on your system, consider restricting shell and CGI access to trusted users only to prevent the creation of symbolic links and other such risky actions.

If you find a flaw in the logic or other potential security issues, please report it to the author or current maintainer as soon as possible. Patches always welcome!

AUTHOR

Scott Wiersdorf, <scott@perlcode.org>

SEE ALSO

perl(1).

cpanm Apache::App::Gallery::Simple

perl -MCPAN -e shell
install Apache::App::Gallery::Simple