NAME
    Apache::Album - Simple mod_perl Photo Album

SYNOPSIS
    Add to httpd.conf

     <Location /albums>
       SetHandler perl-script
       PerlHandler Apache::Album
    #   PerlSetVar  AlbumDir            /albums_loc
    #   PerlSetVar  ThumbNailUse        Width  
    #   PerlSetVar  ThumbNailWidth      100
    #   PerlSetVar  ThumbNailAspect     2/11
    #   PerlSetVar  ThumbSubDir         thumbs
    #   PerlSetVar  DefaultBrowserWidth 640
    #   PerlSetVar  NumberOfColumns     0
    #   PerlSetVar  OutsideTableBorder  0
    #   PerlSetVar  InsideTablesBorder  0
    #   PerlSetVar  BodyArgs            BGCOLOR=white
    #   PerlSetVar  Footer              "<EM>Optional Footer Here</EM>"
    #   PerlSetVar  EditMode            0
    #   PerlSetVar  AllowFinalResize    0
    #   PerlSetVar  FinalResizeDir      thumbs
    #   PerlSetVar  ReverseDirs         0
    #   PerlSetVar  ReversePics         0
     </Location>

ABSTRACT
    This is a simple photo album. You simply copy some gif's/jpeg's
    to a directory, create an optional text block (in a file called
    caption.txt) to go at the top, and the module does the rest. It
    does however require that PerlMagick be installed.

    Default settings in the httpd.conf file may be overriden by
    using .htaccess files.

INSTALLATION
      perl Makefile.PL
      make
      make install

    (no test necessary)

CONFIGURATION
    The configuration can be a little tricky, so here is a little
    more information. It's important to realize that there are two
    separate, but related directories. One is where the physical
    pictures reside, the other is where the "virtual" albums reside.

    Consider a filesystem called /albums exists and it is this
    filesystem that will house the images. Also consider that
    multiple people will have albums there, so you would create a
    directory for each user:

      /albums/jdw/albums_loc
      /albums/travis/albums_loc

    Then in your httpd.conf file you would have the following entry
    to allow pictures in those directories to be viewed:

      Alias /jdw /albums/jdw/

    At this point you could view a full sized picture under the
    directory /albums/jdw/albums_loc as the url /jdw/albums_loc.

    To have an album that creates thumbnails/captions of those
    pictures you would need an entry like:

     <Location /jdw/albums>
      SetHandler perl-script
      AllowOverride None
      Options None
      PerlHandler Apache::Album
      PerlSetVar  AlbumDir /jdw/albums_loc
      PerlSetVar  Footer   "<a href=\"mailto:woody@bga.com\">Jim Woodgate</a>"
     </Location>

    Note how AlbumDir points to the url where the files exist, and
    the url you use to access the album will be just like that url,
    only substituting albums for albums_loc.

    If anyone knows of a way to accomplish this same thing, but
    using a DirectoryIndex instead, please let me know. I tried and
    could not get it to work!

DESCRIPTION
    This module sets up a virtual set of photo albums starting at
    the `Location' definition. This virtual directory is mapped to a
    physical directory under `AlbumDir'. Under `AlbumDir' create a
    sub-directory for each photo album, and copy image files into
    each subdirectory. You must also make the permissions for each
    subdirectory so that the id which runs Apache can write to the
    directory.

    At this point, if you have PerlMagick installed, you can go to
    *http://your.site/albums/album_name* Apache::Album will create
    thumbnails for each of the images, and send the caption.txt file
    along with the thumbnails to the client's browser. The
    thumbnails are links to the full sized images.

    The caption.txt file
      The caption.txt file consists of two parts. The first part is
      text/html that will be placed at the top of the html document.
      The second part is a mapping of filenames to captions. The
      module will do some simple mangling of the image file names to
      create the caption. But if it finds a mapping in the
      caption.txt file, that value is used instead. The value
      __END__ signifies the end of the first section and the
      beginning of the second.

        For example:

        Image   -> Bob_and_Jenny.jpg
        Caption -> Bob and Jenny       (the auto-generated caption)

        override in caption.txt
        Bob_and_Jenny.jpg: This is me with my sister <EM>Jenny</EM>.

      Here is a sample caption.txt file:

        <H1>My Birthday Party</H1>

        <center>This is me at my Birthday Party!.</center>

        __END__
        pieinface.gif: Here's me getting hit the face with a pie.
        john5.jpg: This is <A HREF="mailto:johndoe@nowhere.com">John</A>

    ThumbNail Types
      `ThumbNailUse' can either be set to "width" or "aspect". If
      `ThumbNailUse' is set to "width", thumbnails that need to be
      created will be `ThumbNailWidth' wide, and the height will be
      modified to keep the same aspect as the original image.

      If `ThumbNailUse' is set to "aspect", thumbnails that need to
      be created will be transformed by the value of
      `ThumbNailAspect'. `ThumbNailAspect' can be either a floating
      point number like 0.25 or it can be a ratio like 2 / 11.

      If an image file is updated, the corresponding thumbnail file
      will be updated the next time the page is accessed. In
      practice I have found that Netscape will used the cached
      images even if they are updated. I normally have to flush the
      cache and reload to see the new images.

      At any time you can `rm -f tn__*' in the
      `AlbumDir'/album_name/ directory, the next time the page is
      loaded all the thumbnails will be regenerated. (Naturally
      image names that start with tn__ should be renamed before
      placing them in the album directory.)

    ThumbSubDir
      If you want your thumbnails to be in a different directory
      than the original pictures, set `ThumbSubDir' which is the
      subdirectory the thumbnails will be created in and viewed
      from. (This could also be used to allow multiple sets of
      thumbnails).

    DefaultBrowserWidth
      A general number of how wide you want the final table to be,
      not an absolute number. If the next image would take it past
      this "invisible line", a new row is started.

    NumberOfColumns
      Instead of using DefaultBrowserWidth and a guess at the number
      of pixels, NumberOfColumns can be set to the maximum number of
      columns in a table. The default is 0 (which causes
      DefaultBrowserWidth to be used instead).

    BodyArgs
      This entire string is passed in the <BODY> tag. Useful for
      setting background images, background color, link colors, etc.
      If set in the httpd.conf file, you must put quotes around the
      value, and escape any quotes in the value. If this value is
      set in the .htaccess file, this is not necessary:

        In httpd.conf: PerlSetVar BodyArgs "BACKGROUND=gray.gif text=\"#FFFFFF\""
        In .htaccess : PerlSetVar BodyArgs BACKGROUND=gray.gif text="#FFFFFF"

    OutsideTableBorder
      This variable's value is passed to the outer table's BORDER
      attribute.

    InsideTablesBorder
      This variables's value is passed to all the inner table's
      BORDER attributes. Note that the name of the
      `InnerTablesBorder' has an 's' in it, as it modifes all the
      inner tables.

    Footer
      This text/html will placed at the bottom of the page after all
      the thumbnails, but before the end of the page. Useful for
      links back to a home page, mailto: tag, etc.

    EditMode
      Allows the user to create new albums and upload pictures.
      Obviously there are security implications here, so if EditMode
      is turned on that location should probably have some kind of
      security. Albums can share the same AlbumDir, so you can have
      something like:

      /albums - ReadOnly version, no security /albums_edit - Allow
      new album creation and picture uploads, require authentication

      both using the same AlbumDir.

    AllowFinalResize
      If this is set to true, the user will have 3 additional
      options when viewing the full sized picture. The thumbnail can
      still be selected to view the full picture, or Sm (Small), Med
      (Medium), or Lg(Large) can be selected to bring the picture
      down to fit better in a 640x480, 800x600, or 1024x758 screen.

    ReverseDirs
      When viewing albums, they will be sorted by name. If this is
      set to true the order will be reversed. (Useful if you want to
      use things like dates/months as the directory names, this will
      put the most recent albums first.

    ReversePics
      When viewing pictures, they will be sorted by name. If this is
      set to true, the order of the pictures will be reversed.

OTHER FEATURES
    For people with lots of bandwidth and memory, Apache::Album can
    generate a single page with all the full sized pictures (or all
    the Small(sm), Medium(med) or Large(lg) pictures if
    AllowFinalResize is turned on). This is enabled by passing
    ?all_full_images=sm|med|lg|full to the url of an album, for
    example:

      `http://your.web.server/albums/specific_album/?all_full_images
      =sm'

    Will create a page with all the picutres in an album, but none
    will be larger than 640x480. The pictures will have captions as
    if the pictures were being viewed one at a time.

LIMITATIONS
    PerlMagick is a limiting factor. If PerlMagick can't load the
    image, no thumbnail will be created.

COPYRIGHT
    Copyright (c) 1998-2000 Jim Woodgate. All rights reserved. This
    program is free software; you can redistribute it and/or modify
    it under the same terms as Perl itself.

AUTHOR
    Jim Woodgate woody@bga.com

SEE ALSO
    perl(1), the Image::Magick manpage(3).