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