ImageGalleryPlugin

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/ImageGalleryPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/ImageGalleryPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Description

This plugin helps you in viewing pictures that are attached to a topic in a nice thumbnail gallery. Clicking on a thumbnail zooms the image. You might navigate within your images using a navigation toolbar to visit the next, previous, first or last image in your gallery. Images and thumbnails are resized according to the given settings and are cached thereafter. The order of images can be customized by putting a sequence number into the attachment comment. An image attachment can be managed by clicking on the red dot in its title. The plugin will generate the document relations "parent", "first", "last", "next", "previous" for each image to improve navigation (only a few browsers support this, e.g. mozilla). The image gallery is highly customizable using cascading stylesheets and html formats (see below).

Example

action-item	addon	air
airplane	analyze	application
as	attachfile	award
barcode	bat	bed

Syntax

Arguments

This plugin introduces two TWiki variables:

• %IMAGEGALLERY{...}%: render an image gallery
• %NRIMAGES%: returns the number of images attachted to a (list of) topics

Both variables handle the following arguments:

Note, that only topic is meaningful to %NRIMAGES%.

Variables

The parameters "format", "title" and "thumbtitle" can use the following variables to refer to image properties:

Variable <-- -->	Description
$wikiusername	the wikiusername who uploaded the image
$width	the display width of the image
$web	the web the image is located
$version	the version of the image attachment
$username	the username who uploaded the image
$topic	the topic the image is located
$thumbwidth	the thumbnail width of the image
$thumburl	the url path of the thumbnail image
$thumbheight	the thumbnail height of the image
$sizeK	the size of the image in kilobytes
$size	the size of the image
$reddot	render a red-dot anchor to access the attachment
$origwidth	the original width of the image
$origurl	the url path pointing to the original image attachment
$origheight	the original height of the image
$nrimages	the total number of images in the gallery
$name	the filename of the image
$n	a linefeed
$imgnr	the sequence number of the image
$imageurl	the url path of the display image
$height	the display height of the image
$date	the date when the image has been uploaded
$comment	the comment of the image (with its sequence number stripped off)

Query Parameters

The IGP will check for certain query parameters in the url. These are:

• id=<n;>: distinguish multiple IMAGEGALLERYs in the same topic
• filename=<name>: display the given file of the image set
• refresh=on: recompute all images and thumbnails in the IGP cache

Each IMAGEGALLERY has an anchor, namely a <a name="igp<n>"/>, that is used to scroll the display appropriately.

Customization

First of all this plugin should come with reasonable default values, so that you will get a nice image gallery (with regards to my taste) right on. There are several things that are customizable:

• customize a gallery using a compination of the arguments described above
• add custom cascading styles in a topic to format the gallery
• alter the default cascading styles in the style.css file attached to this topic
• customize the plugin settings below

Cascading Stylesheets

The plugin emits the following css classes (see the comments in the style.css file):

Adjusting the image sequence

By default the image gallery will display images in the order that they where uploaded. This determines their natural order. When you want to change this order you can prefix the comment of the attachment with a sequence number. For example: given a picture whose comment is "My old bike" that should be put at position 12 in your image gallery then change the comment to "12 - My old bike". This will put the image at the desired position. Sequence numbers don't necessarily need to be unique, that is if there's another picture with a comment like "12 - My new bike" then the natural order of the both is relevant. In general, a picture will be put at position <nr> if its attachment comment has the format

  <nr><space>-<space><comment>

Note, that the $comment variable will only display <comment> , that is with <nr><space>-<space> stripped off.

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

• Download the ZIP file
• Unzip it in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/ImageGalleryPlugin.txt
  lib/TWiki/Plugins/ImageGalleryPlugin/Core.pm
  lib/TWiki/Plugins/ImageGalleryPlugin.pm
  pub/TWiki/ImageGalleryPlugin/style.css

• Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

Plugin Info

<-- 

 Set SHORTDESCRIPTION = Show image gallery with auto-generated thumbnails from attachments
 
-->

Plugin Author:	TWiki:Main.MichaelDaum, TWiki:Main.WillNorris
Copyright:	© 2002-2003, Will Norris; © 2005-2008, Michael Daum http://michaeldaumconsulting.com; © 2008-2011 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	2011-07-21 - v3.74
Change History:	<-- versions below in reverse order -->
2011-07-21	TWikibug:Item6772: No images found error if image name has dots in name -- TWiki:Main.JoshuaTharp; change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2010-04-26	TWikibug:Item6433: Doc improvements -- TWiki:Main.PeterThoeny
16 Jul 2008	don't crash on images that start with a digits pattern
07 Jul 2008	fixing use of string as hash
03 Jul 2008	applying patch by Aurélio A. Heckert (see Bugs:Item5753); using Resize instead of Scale for higher quality thumbnails; hiding reddot when the user has no edit access to the target topic
03 Mar 2008	make implementation of image mage configurable, defaulting to Graphics::Magick as Image::Magick has got issues using perl accellerators like mod_perl, speedy-cgi
17 Jan 2008	default to sorting by name instead of by date
13 Nov 2007	replaced plugin topic settings with configure settings
19 Sep 2007	store auto-computed images in an images subdir of its own
19 Feb 2007	make proper use TWiki-4 API; don't use inline css, put them into the html header instead
24 Jul 2006	working around Image::Magick crashes reading svg image files
20 Mar 2006	added sort and reverse arguments; fixed updating thumbnails when a new image version is created
20 Feb 2006	added include, exclude and field arguments
16 Feb 2006	renamed thumbnail so that it does not interfer with auto-attachment
14 Sep 2005	don't strictly depend on normalizeFilename()
15 June 2005	new release
10 May 2005	fixed igp id clash error found by TWiki:Main/MartinCleaver; capture ImageMagick error messages; don't trust attachment info - check for attachment existence as well; added refresh query parameter to recompute images
09 May 2005	fixed errors reported by TWiki:Main/MarcelTrap; added support for multiple topics (proposed by TWiki:Main/MartinCleaver; added %NRIMAGES% tag
	fix error when called from within rename view
03 May 2005	fixed thumbnail resizing; reintroduced titles parameter; support for multiple galleries per topic
27 Apr 2005	complete rewrite
01 Aug 2003	Updates from feedback from a Windows installation
25 Jul 2003	Initial version posted to TWiki.org
15 Mar 2002	Initial (internal) version
CPAN Dependencies:	CPAN:Image::Magick or CPAN:Graphics::Magick
Other Dependencies:	none
Perl Version:	5.8
Plugin Home:	TWiki:Plugins/ImageGalleryPlugin
Feedback:	TWiki:Plugins/ImageGalleryPluginDev
Appraisal:	TWiki:Plugins/ImageGalleryPluginAppraisal

Related topics: TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory