README

   1 NAME
   2     Apache::Gallery - mod_perl handler to create an image gallery
   3
   4 SYNOPSIS
   5     See the INSTALL file in the distribution for installation instructions.
   6
   7 DESCRIPTION
   8     Apache::Gallery creates an thumbnail index of each directory and allows
   9     viewing pictures in different resolutions. Pictures are resized on the
  10     fly and cached. The gallery can be configured and customized in many
  11     ways and a custom copyright image can be added to all the images without
  12     modifying the original.
  13
  14 CONFIGURATION
  15     In your httpd.conf you set the global options for the gallery. You can
  16     also override each of the options in .htaccess files in your gallery
  17     directories.
  18
  19     The options are set in the httpd.conf/.htaccess file using the syntax:
  20     PerlSetVar OptionName 'value'
  21
  22     Example: PerlSetVar GalleryCacheDir '/var/tmp/Apache-Gallery/'
  23
  24     GalleryAutoRotate
  25         Some cameras, like the Canon G3, can detect the orientation of a the
  26         pictures you take and will save this information in the
  27         'Orientation' EXIF field. Apache::Gallery will then automatically
  28         rotate your images.
  29
  30         This behavior is default but can be disabled by setting
  31         GalleryAutoRotate to 0.
  32
  33     GalleryCacheDir
  34         Directory where Apache::Gallery should create its cache with scaled
  35         pictures. The default is /var/tmp/Apache-Gallery/ . Here, a
  36         directory for each virtualhost or location will be created
  37         automaticly. Make sure your webserver has write access to the
  38         CacheDir.
  39
  40     GalleryTemplateDir
  41         Full path to the directory where you placed the templates. This
  42         option can be used both in your global configuration and in
  43         .htaccess files, this way you can have different layouts in
  44         different parts of your gallery.
  45
  46         No default value, this option is required.
  47
  48     GalleryInfo
  49         With this option you can define which EXIF information you would
  50         like to present from the image. The format is: '<MyName =>
  51         KeyInEXIF, MyOtherName => OtherKeyInEXIF'
  52
  53         Examples of keys: ShutterSpeedValue, ApertureValue, SubjectDistance,
  54         and Camera
  55
  56         You can view all the keys from the EXIF header using this
  57         perl-oneliner:
  58
  59         perl "-e" 'use Data::Dumper; use Image::Info qw(image_info); print
  60         Dumper(image_info(shift));' filename.jpg
  61
  62         Default is: 'Picture Taken => DateTimeOriginal, Flash => Flash'
  63
  64     GallerySizes
  65         Defines which widths images can be scaled to. Images cannot be
  66         scaled to other widths than the ones you define with this option.
  67
  68         The default is '640 800 1024 1600'
  69
  70     GalleryThumbnailSize
  71         Defines the width and height of the thumbnail images.
  72
  73         Defaults to '100x75'
  74
  75     GalleryThumbnailSizeLS
  76         If set to '1', GalleryThumbnailSize is the long and the short side
  77         of the thumbnail image instead of the width and height.
  78
  79         Defaults to '0'.
  80
  81     GalleryCopyrightImage
  82         Image you want to blend into your images in the lower right corner.
  83         This could be a transparent png saying "copyright my name 2001".
  84
  85         Optional.
  86
  87     GalleryWrapNavigation
  88         Make the navigation in the picture view wrap around (So Next at the
  89         end displays the first picture, etc.)
  90
  91         Set to 1 or 0, default is 0
  92
  93     GalleryAllowOriginal
  94         Allow the user to download the Original picture without resizing or
  95         putting the CopyrightImage on it.
  96
  97         Set to 1 or 0, default is 0
  98
  99     GallerySlideshowIntervals
 100         With this option you can configure which intervals can be selected
 101         for a slideshow. The default is '3 5 10 15 30'
 102
 103     GallerySortBy
 104         Instead of the default filename ordering you can sort by any stat
 105         attribute. For example size, atime, mtime, ctime.
 106
 107     GalleryDirSortBy
 108         Set this variable to sort directories differently than other items,
 109         can be set to size, atime, mtime and ctime; setting any other value
 110         will revert to sorting by name.
 111
 112     GalleryMemoize
 113         Cache EXIF data using Memoize - this will make Apache::Gallery
 114         faster when many people access the same images, but it will also
 115         cache EXIF data until the current Apache child dies.
 116
 117     GalleryUseFileDate
 118         Set this option to 1 to make A::G show the files timestamp instead
 119         of the EXIF value for "Picture taken".
 120
 121     GallerySelectionMode
 122         Enable the selection mode. Select images with checkboxes and get a
 123         list of filenames.
 124
 125     GalleryEXIFMode
 126         You can choose how Apache::Gallery should display EXIF info from
 127         your images.
 128
 129         The default setting is 'namevalue'. This setting will make
 130         Apache::Gallery print out the names and values of the EXIF values
 131         you configure with GalleryInfo. The information will be parsed into
 132         $INFO in pictureinfo.tpl.
 133
 134         You can also set it to 'values' which will make A::G parse the
 135         configured values into the var $EXIFVALUES as 'value | value |
 136         value'
 137
 138         If you set this option to 'variables' the items you configure in
 139         GalleryInfo will be available to your templates as $EXIF_<KEYNAME>
 140         (in all uppercase). That means that with the default setting
 141         "Picture Taken => DateTimeOriginal, Flash => Flash" you will have
 142         the variables $EXIF_DATETIMEORIGINAL and $EXIF_FLASH avilable to
 143         your templates. You can place them anywhere you want.
 144
 145     GalleryRootPath
 146         Change the location of gallery root. The default is ""
 147
 148     GalleryRootText
 149         Change the name that appears as the root element in the menu. The
 150         default is "root:"
 151
 152     GalleryMaxThumbnailsPerPage
 153         This options controls how many thumbnails should be displayed in a
 154         page. It requires $BROWSELINKS to be in the index.tpl template file.
 155
 156     GalleryImgFile
 157         Pattern matching the files you want Apache::Gallery to view in the
 158         index as thumbnails.
 159
 160         The default is '\.(jpe?g|png|tiff?|ppm)$'
 161
 162     GalleryDocFile
 163         Pattern matching the files you want Apache::Gallery to view in the
 164         index as normal files. All other filetypes will still be served by
 165         Apache::Gallery but are not visible in the index.
 166
 167         The default is
 168         '\.(mpe?g|avi|mov|asf|wmv|doc|mp3|ogg|pdf|rtf|wav|dlt|txt|html?|csv|eps)
 169         $'
 170
 171     GalleryTTFDir
 172         To use the GalleryCopyrightText feature you must set this option to
 173         the directory where your True Type fonts are stored. No default is
 174         set.
 175
 176         Example:
 177
 178                 PerlSetVar      GalleryTTFDir '/usr/share/fonts/'
 179
 180     GalleryTTFFile
 181         To use the GalleryCopyrightText feature this option must be set to
 182         the name of the True Type font you wish to use. Example:
 183
 184                 PerlSetVar      GalleryTTFFile 'verdanab.ttf'
 185
 186     GalleryTTFSize
 187         Configure the size of the CopyrightText that will be inserted as
 188         copyright notice in the corner of your pictures.
 189
 190         Example:
 191
 192                 PerlSetVar      GalleryTTFSize '10'
 193
 194     GalleryCopyrightText
 195         The text that will be inserted as copyright notice.
 196
 197         Example:
 198
 199                 PerlSetVar      GalleryCopyrightText '(c) Michael Legart'
 200
 201     GalleryCopyrightColor
 202         The text color of your copyright notice.
 203
 204         Examples:
 205
 206         White: PerlSetVar GalleryCopyrightColor '255,255,255,255'
 207
 208         Black: PerlSetVar GalleryCopyrightColor '0,0,0,255'
 209
 210         Red: PerlSetVar GalleryCopyrightColor '255,0,0,255'
 211
 212         Green: PerlSetVar GalleryCopyrightColor '0,255,0,255'
 213
 214         Blue: PerlSetVar GalleryCopyrightColor '0,0,255,255'
 215
 216         Transparent orange: PerlSetVar GalleryCopyrightColor '255,127,0,127'
 217
 218     GalleryCopyrightBackgroundColor
 219         The background-color of a GalleryCopyrightText
 220
 221         r,g,b,a - for examples, see GalleryCopyrightColor
 222
 223     GalleryQuality
 224         The quality (1-100) of scaled images
 225
 226         This setting affects the quality of the scaled images. Set this to a
 227         low number to reduce the size of the scaled images. Remember to
 228         clear out your cache if you change this setting. Quality seems to
 229         default to 75, at least in the jpeg and png loader code in Imlib2
 230         1.1.0.
 231
 232         Examples:
 233
 234         Quality at 50: PerlSetVar GalleryQuality '50'
 235
 236     GalleryUnderscoresToSpaces
 237         Set this option to 1 to convert underscores to spaces in the listing
 238         of directory and file names, as well as in the alt attribute for HTML
 239         <img> tags.
 240
 241     GalleryCommentExifKey
 242     Set this option to e.g. ImageDescription to use this field as comments
 243     for images.
 244
 245     GalleryEnableMediaRss
 246     Set this option to 1 to enable generation of a media RSS feed. This can
 247     be used e.g. together with the PicLens plugin from http://piclens.com
 248
 249 FEATURES
 250     Rotate images
 251         Some cameras, like the Canon G3, detects the orientation of a
 252         picture and adds this info to the EXIF header. Apache::Gallery
 253         detects this and automaticly rotates images with this info.
 254
 255         If your camera does not support this, you can rotate the images
 256         manually, This can also be used to override the rotate information
 257         from a camera that supports that. You can also disable this behavior
 258         with the GalleryAutoRotate option.
 259
 260         To use this functionality you have to create file with the name of
 261         the picture you want rotated appened with ".rotate". The file should
 262         include a number where these numbers are supported:
 263
 264                 "1", rotates clockwise by 90 degree
 265                 "2", rotates clockwise by 180 degrees
 266                 "3", rotates clockwise by 270 degrees
 267
 268         So if we want to rotate "Picture1234.jpg" 90 degrees clockwise we
 269         would create a file in the same directory called
 270         "Picture1234.jpg.rotate" with the number 1 inside of it.
 271
 272     Comments
 273         To include comments for a directory you create a <directory>.comment
 274         file where the first line can contain "TITLE: New title" which will
 275         be the title of the page, and a comment on the following lines. To
 276         include comments for each picture you create files called
 277         picture.jpg.comment where the first line can contain "TITLE: New
 278         title" which will be the title of the page, and a comment on the
 279         following lines.
 280
 281         Example:
 282
 283                 TITLE: This is the new title of the page
 284                 And this is the comment.<br />
 285                 And this is line two of the comment.
 286
 287         The visible name of the folder is by default identical to the name
 288         of the folder, but can be changed by creating a file
 289         <directory>.folder with the visible name of the folder.
 290
 291         It is also possible to set GalleryCommentExifKey to the name of an
 292         EXIF field containing the comment, e.g. ImageDescription. The EXIF
 293         comment is overridden by the .comment file if it exists.
 294
 295 DEPENDENCIES
 296     Perl 5
 297     Apache with mod_perl
 298     URI::Escape
 299     Image::Info
 300     Image::Size
 301     Text::Template
 302     Image::Imlib2
 303     X11 libraries (ie, XFree86)
 304     Imlib2 Remember the -dev package when using rpm, deb or other package
 305     formats!
 306
 307 AUTHOR
 308     Michael Legart <michael@legart.dk>
 309
 310 COPYRIGHT AND LICENSE
 311     Copyright (C) 2001-2005 Michael Legart <michael@legart.dk>
 312
 313     Templates designed by Thomas Kjaer <tk@lnx.dk>
 314
 315     Apache::Gallery is free software and is released under the Artistic
 316     License. See http://www.perl.com/language/misc/Artistic.html for
 317     details.
 318
 319     The video icons are from the GNOME project. http://www.gnome.org/
 320
 321 THANKS
 322     Thanks to Thomas Kjaer for templates and design of
 323     http://apachegallery.dk Thanks to Thomas Eibner and other for patches.
 324     (See the Changes file)
 325
 326 SEE ALSO
 327     perl, mod_perl, Image::Imlib2, CGI::FastTemplate, Image::Info, and
 328     Image::Size.
 329