Aaron Straup Cope

NAME

Image::Shoehorn::Gallery - generate "smart" HTML slideshows from a directory of image files.

SYNOPSIS

 use Image::Shoehorn::Gallery;

 Image::Shoehorn::Gallery->create({
                                   source      => "~/my-images",
                                   directory   => "/htdocs/images",
                                   url         => "http://mysite.com/images",
                                   static      => 1,
                                   scales      => [
                                                   [ "thumb","75x50"  ],
                                                   [ "default", "50%" ],
                                                   [ "small","25%"    ],
                                                   [ "medium","50%"   ],
                                                ],
                                   scale_if    => { x => 400 , y => 300 },
                                   iptc        => ["headline","caption/abstract"],
                                   set_lang    => "en-ca",
                                   set_styles  => {
                                                  image => [
                                                            {title=>"my css",href=>"/styles.css"},
                                                           ],
                                                 },
                                   set_index_images => { default => 1 },
                                  });

DESCRIPTION

Image::Shoehorn::Gallery generates HTML slideshows from a directory of image files. But wait, there's more!

Image::Shoehorn uses XML::Filter::XML_Directory_2XHTML, XML::SAX::Machines and a small army of Image::* packages allowing you to :

  • Create one, or more, scaled versions of an image, and their associate HTML pages. Scaled version may also be defined but left to be created at a later date by Apache::Image::Shoehorn.

    Associate HTML are always "baked", rather than "fried" (see also : http://www.aaronsw.com/weblog/000404 )

  • Read a user-defined list of IPTC and EXIF metadata fields from each image and include the data in the HTML pages.

  • Generate named indices and next/previous links by reading IPTC "headline" data.

  • Define one, or more, SAX filters to be applied to "index" and individual "image" documents before they are passed the final XML::SAX::Writer filter for output.

    The default look and feel of the gallery pages is pretty plain, but you could easily define a "foofy design" XSL stylesheet to be applied with the XML::Filter::XSLT SAX filter:

     <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                     version = "1.0" >
    
      <xsl:template match = "/">
      <html>
       <xsl:copy-of select = "html/head" />
       <body>
    
        <!-- lots of foofy design stuff -->
        <xsl:copy-of select = "/html/body/*" />
        <!-- lots of foofy design stuff -->
    
       </body>
      </html>
      </xsl:template>
    
     </xsl:stylesheet>
  • Generates valid XHTML (strict) and CSS!

PACKAGE METHODS

__PACKAGE__->create(\%args)

This is the magic spell that will create your galleries.

Valid arguments are :

  • source

    String.

    This is the path to the directory that you want to read images from.

  • destination

    String.

    This is the path to directory that you want to write images, and HTML files, to. If undefined, then the value of source will be used.

  • directory

    String.

    Deprecated in favour of source and destination. If present, it will be used as *both* the source and destination directories.

  • url

    String.

    The URL that maps to directory on your webserver.

  • maxdepth

    Int.

    The maximum number of sub directories to munge and render.

  • static

    Boolean.

    Used in conjunction with the scales option for generating scaled versions of an image and their URLs.

    If false, or not defined, the package will assume that you have configured Apache::Image::Shoehorn to generate scaled versions of an image.

    If true, then the package will output image URLs that map to static images on the filesystem and ask Image::Shoehorn to create the new files, or update existing ones.

    Note, however, that the "thumb" (thumbnail) image will be generated regardless of whether or not you are using Apache::Image::Shoehorn. This is actually a feature since you would peg your machine having to create all those thumbnails the first time you loaded an especially large index page.

  • scales

    Array reference containing one, or more, array referece.

    Each of the child arrays should contain (2) elements :

    • name

      A name like "small" or "medium". This name is used as part of the naming scheme for images that have been scaled and their associate HTML pages.

      Names can be pretty much anything you'd like, with the exception of "thumb" and "default" which are discussed below.

    • scale

      These are required whether or not you are going to be generate static images. Even if you are going to render your images on the fly using Apache::Image::Shoehorn, the HTML spec (hi Karl) mandates that you provide height and widgth attributes for your img elements. So...

      Takes arguments in the same form as Image::Shoehorn which are, briefly :

      • n%

      • nxn

      • xn

      • nx

      There are two special scale names :

      • thumb

        You must define a thumb scale. It is used to generate thumbnails for the index page which are, in turn, used when generating the individual HTML pages for each image.

      • default

        This feature is only supported for images that are rendered statically :-(.

        Suppose your source images are very large and you would like to use a scaled version as the default image in your gallery. You may want to do this because you are concerned about people doing bad things with your high quality images or you don't want to pay the additional charges that your web-hosting service will charge you for all those 2-3 MB files. Or both.

        The default image is the default view and its dimensions are what all other scales are keyed off of.

        For example, your source image is 1200x840 and you define two scales (not including the 'thumb' scale.) The first is called 'small' and the second 'default'; both have a value of '50%'.

        Note: the hooks for creating default images are smart about paying attention to the scaleif options, discussed below.

        Since you have defined a default image, it will be created in your source directory with the same basename as the source image itself. It will be half the size of the original, 600x420. The 'small' version will be created and will be half the size of the 'default' image, rather than the source, or 300x210.

        Remember to use this feature carefully if your source and destination directories are the same. You could easily overwrite all your source images with newer default "sources".

  • scaleif

    Hash reference.

    Define height and width values that will be used to determine whether or not an image should actually be scaled.

    For example, it is unlikely that you will need to create a small version (say 25% the size of the original) if your source file is 100 by 150 pixels. You might - that's your business - but atleast this way you can opt out.

    Images will only be scaled if their height or width is greater than the height and/or width listed in this argument.

    You may define one or both of the following :

    • x

      Int.

      The minimum width that an image must have to be scaled.

    • y

      Int.

      The minimum height that an image must have to be scaled.

    Note that although multiple image files may not be created, if the source image is smaller than the dimensions passed in this argument, their associate HTML files will be generated. Don't worry, they'll point to the same unscaled image.

    Think of it as the glass being half full.

  • iptc

    Array reference.

    A list of IPTC fields to read from an image. Fields are presented in the order they are defined.

    For a complete list of IPTC fields, please consult the Image::IPTCInfo.

  • exif

    Array reference.

    A list of EXIF fields to read from an image. Fields are presented in the order they are defined.

    For a complete list of EXIF fields, please consult http://www.ba.wakwak.com/~tsuruzoh/Computer/Digicams/exif-e.html

  • set_lang

    String.

    Set the language code for your HTML documents.

  • set_styles

    Hash reference.

    Used to override the default CSS for either and "index" page or an individual "image" page.

    Valid hash keys are :

    • index

    • image

    Where each key expects an array ref of hash refs whose keys are :

    • href

    • title

      Default is ""

    • rel

      Default is "stylesheet"

    • media

      Default is "all".

    Styles will be added in the order that they are defined in the array ref.

    The default CSS styles are outlined below.

  • set_filters

    Hash reference

    Define one or more additional filters to be applied to either an "index" or individual "image" page.

    Valid hash keys are :

    • index

    • image

    Filters are applied last, before events are finally handed off to XML::SAX::Writer and in the order that they are defined.

    Example:

     package MySAX;
     use base qw (XML::SAX::Base);
    
     sub start_element {
        my $self = shift;
        my $data = shift;
    
        $self->SUPER::start_element($data);
    
        if ($data->{Name} eq "body") {
           $self->SUPER::start_element({Name=>"h1"});
           $self->SUPER::characters({Data=>"hello world"});
           $self->SUPER::end_element({Name=>"h1"});
        }
     }
    
     package main;
    
     # The following will add <h1>hello world</h1>
     # at the top of all your 'image' pages. Woot!
    
     use Image::Shoehorn::Gallery;
     Image::Shoehorn::Gallery->create({
                                       # ...
    
                                       set_filters => { image => [ MySAX->new() ]},
                                      });
  • set_index_images

    Hash reference.

    Define images to associate with files in a directory listing. Valid keys are :

    • image

      Image to associate with a file whose media type is "image"

      Default is to generate and include a thumbnail, as defined by the "thumb" scale option (see above.)

    • directory

      Image to associate with a directory.

    • file

      Image to associate with a file whose media type is not "image"

      Example :

       # Use the default Apache icons
      
       my %images = (
                     directory => {
                                   src    => "/icons/dir.gif",
                                   height => "20",
                                   width  => "20",
                                   alt    => "ceci n'est pas un dossier",
                                  },
                     file => {
                              src    => "/icons/unknown.gif",
                              height => "20",
                              width  => "20",
                              alt    => "ceci n'est pas un fichier",
                             },
                     );
      
       Image::Shoehorn::Gallery->create({
                                         # ...
                                         set_index_images => \%images,
                                        });
    • default

      Boolean.

      This is just a shortcut to use the default image handler and the handlers for files and directories example described above.

      If you are not using Apache for your web server and/or have not aliased the Apache icons folder to /icons, it won't do you much good.

    Valid keys arguments are either :

    • hash reference

      Containing key/value pairs for the following image attributes :

      • src

      • height

      • width

      • alt

    • code reference

      The code reference will be passed the absolute path of the current image and is expected to return a hash reference similar to the one described above.

    This is an XML::Filter::XML_Directory_2XHTML-ism. Please consult docs for further details.

  • set_encoding

    String.

    Default is "UTF-8"

  • force

    Int.

    By default neither the scaled version of an image, nor the associate HTML files, will be created unless the source image has a more recent modification date.

    You can use this option to override this check.

    If the value is greater than zero, HTML files will be regenerated.

    If the value is greater than one, images and HTML files will be regenerated.

  • verbose

    Boolean.

NAMING CONVENTIONS

Let's say you've got an image named :

 20020603-my-new-toy.jpg

You've defined two "views" to be generated : small and medium. The following files will be created :

 20020603-my-new-toy.html
 20020603-my-new-toy-thumb.jpg **
 20020603-my-new-toy-small.jpg *
 20020603-my-new-toy-small.html
 20020603-my-new-toy-medium.jpg *
 20020603-my-new-toy-medium.html

 *  If you are rendering scaled images on the fly, with I<Apache::Image::Shoehorn>, 
    these files not be created until such a time as they are actually viewed

 ** Thumbnails are always generated, regardless of the I<static> flag. As mentioned 
    earlier, this is a feature. If you have a directory with many images, you will peg
    your web server the first time you have to render all those images for the index
    listing.

The package uses XML::Filter::XML_Directory_2XHTML which, a few steps up the inheritance tree, uses XML::Filter::XML_Directory_Pruner to exclude certain specific files from the directory (index) listing. The exact rule set currently used it :

  $xhtml->exclude(
                  starting => ["\\."],
                  ending   => ["html","tmp","~"],
                  # e.g. ending with "-thumb.jpg","-small.jpg" or "-medium.jpg"
                  matching => ["^(.*)-(".join("|","thumb",@{$views}).")\.([^\.]+)\$"],
                 );

The plan is to, eventually, teach XML::Filter::XML_Directory_Pruner to include and exclude widgets based on media type, at which point we could simply do :

 $xhtml->include( media => "image" );

But until then, it is recommended that you make sure your source images don't match the "matching" pattern describe above. Or if you just think I'm an idiot and have a better rule-set, send my a note and I'll probably include it.

CSS

The following CSS classes are defined for the HTML generated by the package.

They are provided as a reference in case you want to specify your own CSS stylesheet.

"index" page

 body {
      background-color: #ffffff;
      margin:0;
 }

 .breadcrumbs {
               display:block;
               background-color: #f5f5dc;
               padding:5px;
               margin-bottom:5px;
               border-bottom: solid thin;
  }

 .breadcrumbs-spacer {}

 .directory { margin-bottom:5px;clear:left; padding: 5px;}

 .file      { margin-bottom:5px;clear:left;padding: 5px;}

 .thumbnail { display:block;width:100px;float:left;}

 .file ul   { float:left;}

"image" page

 body {
        background-color: #ffffff;
        margin:0;
      }

 .breadcrumbs {
   display:block;
   background-color: #f5f5dc;
   padding:5px;
   margin-bottom:5px;
   border-bottom: solid thin;
 }

 .breadcrumbs-spacer {}

 .directory {
   padding: 5px;
 }

 .file {
   padding: 5px;
 }

 .menu {
        margin-bottom:5px;
        padding:5px;
 }

 .menu-link-previous {
                padding-right : 10px;
 }

 .menu-link-previous img {
                margin-right:15px;
 }

 .menu-link-index {
                 font-weight:600;
 }

 .menu-link-next {
                padding-left : 10px;
 }

 .menu-link-next img {
                margin-left:15px;
 }

 .content {
        padding-top:20px;
      }

 .image { 
        position:absolute;
        top:auto;
        right:auto;
        left:170px;
        bottom:auto;
 }

 .meta { 
        min-width:150px;
        max-width:150px;
        margin:5px;
 }  

 .links {
        border: solid thin;
        margin-bottom: 5px;
 }

 .links span {
        display:block;
        padding:3px;
 }

 .iptc { 
        background-color : #fffff0;
        border-top: solid thin; 
        border-left: solid thin;
        border-right: solid thin;
        margin-bottom : 5px;
      }

 .iptc span { 
        display:block; 
        padding:3px;
        border-bottom:solid thin;
 }

 .iptc-field { 
        background-color : #f5f5dc;
        color:#a52a2a;
        border-bottom:solid thin #000;
        }

 .exif { 
        background-color : #f5f5dc;
        border-top: solid thin; 
        border-left: solid thin; 
        border-right: solid thin; 
        margin-bottom : 5px; 
        }

 .exif span { 
        display:block; 
        padding:3px;
        border-bottom:solid thin;
 }

 .exif-field { 
        color:#a52a2a;
        background-color:#cccc99;
        border-bottom:solid thin #000;
        }

VERSION

0.22

AUTHOR

Aaron Straup Cope

DATE

September 02, 2002

TO DO

  • Teach Apache::Image::Shoehorn how to deal with 'default' images, as described above.

  • Add an "import_styles" method, to take advantage of @import hack for hiding CSS from old browsers. Might just add {import=>1} option to "set_styles".

  • Figure out why I keep getting errors when I try passing STYLESHEET::DATA (or copies of it) to the XSLT munger.

  • Set/get config options using closures.

  • Add hooks to read a conf file - this allow involves hacking Apache::Image::Shoehorn so that it can also read the same conf file

  • Add hooks for generating slides from a "virtual" directory; specifically a list of disparate files.

  • Add hooks for supporting XML::Filter::Sort

  • Consider interactive option that would prompt user for IPTC data as files are being processed.

  • Design and implement nightmarish XPath to generate XSLT stylesheet from a user-defined template. I promised Karl I would do this for v 0.3 but we'll see...

BACKGROUND

http://aaronland.net/weblog/archive/3940

http://aaronland.net/weblog/archive/4474

http://www.la-grange.net/2002/07/22.html

EXAMPLE

http://perl.aaronland.info/image/shoehorn/gallery/www/example/index.html

REQUIREMENTS

XML::Filter::XML_Directory_2XHTML

XML::Filter::XSLT

XML::SAX::Machines

XML::SAX::Writer

Image::Shoehorn

Image::IPTCInfo

Image::Info

Digest::MD5

BUGS

Undoubtedly. So far, it works for me.

LICENSE

Copyright (c) 2002, Aaron Straup Cope. All Rights Reserved.

This is free software, you may use it and distribute it under the same terms as Perl itself.