ImageGalleryPlugin

Displays image gallery with auto-generated thumbnails from attachments

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

cascade control-end-gray control-end control-left-gray control-left control-right-gray control-right control-start-gray control-start cross wave wintermountains
12 images found.

Syntax

Arguments

This plugin introduces two tags:
  • %IMAGEGALLERY{...}%: render an image gallery
  • %NRIMAGES%: returns the number of images attachted to a (list of) topics
that both take the following arguments:

Argument Description
topic comma separated list of topics whose attachments should be displayed
(default: the current topic)
limit maximum number of images to display (default: 0, meaning no limit).
include regular expression an image must match to be part of the gallery
exclude regular expression an image must not match to be part of the gallery
frontend select gallery interface, possible values are default, slimbox, prettyphoto, photoswipe and html; NOTE, specifying a frontend disables the format parameter (see below for an explanation)
field specify which property of the image has to match using include or exclude; possible values: name, comment (default: name)
size the thumbnail size, the actual geometries of a size can be configured below; possible values: tiny, small, medium, large, huge (default: medium)
columns number of thumbnails to be displayed in one row of the gallery
(default: 4)
docrels flag to disable/enable document relations between images; possible values are on, off, 0, 1 (default: on)
maxwidth maximal display width of an image; images are scaled not to exceed this limit while preserving aspect ratio
(default: 640)
maxheight maximal display height of an image
(default: 480)
minwidth minimal display width of an image; images are scaled not to fall below this limit while preserving aspect ratio
(default: 0)
minheight minimal display height of an image
(default: 0)
header header part of the gallery; only used if there is a format
format html format of an image
(default: <a href="$origurl"><img src="$imageurl" title="$comment" width="$width" height="$height"/></a>)
footer footer part of the gallery; only used if there is a format
titles toggles image and thumnail titles on and off
(default: off)
title html format of an image title; "off" will hide the image's title
(default: $comment ($imgnr/$nrimgs))
thumbtitle html format of a thumbnail title; "off" will hide the thumbnail's title
(default: $comment)
sort set the initial order of the images, can be name, date, size or comment (default:date)
reverse invert the initial order of the images, can be on or off (default:off)
class add an additional css class attribute to the image gallery wrapper; might be used to add additional features such as in %IMAGEGALLERY{class="jqPhotoSwipe jqMasonry"}%

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

Frontends

The frontend parameter specifies which user interface to use to display the lightbox in the browser:

  • default: use the best user interface given other extensions installed; it checks for photoswipe, prettyphoto, and slimbox in the given order and uses the first available on the system
  • photoswipe: you need to install JQPhotoSwipeContrib to use this interface
  • prettyphoto: you need to install JQPrettyPhotoContrib to use this interface
  • slimbox: this is a default lightbox interface shipped with Foswiki
  • html: use an html interface to render the gallery without using any javascript frontend; NOTE: this works best with AngularSkin/AngularPlugin to still render the gallery as a single-page application

Without any frontend or format parameter specified will the system use the best interface available.

Variables

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

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

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):

Class Description
igp division for the complete output of the image gallery
igpThumbNails division of all thumbnails
igpThumbNailsTable table of thumbnail images
igpThumbNail table cell of one thumbnail image
igpThumbNailTitle table cell of the thumbnail title
igpPictureTable table of the display image and the navigation bar
igpPicture table cell of the display image
igpPictureTitle division of the title of the display image
igpNavigation table cell of the navigation bar
igpRedDot span surrounding the red dot
igpAlert span surrounding error messages

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.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

NameVersionDescription
Image::Magick>=6.2.4.5Required.
Graphics::Magick>=1.1.11Optional.
Foswiki::Plugins::JQueryPlugin>=3.74Optional

Change History

05 Dec 2016 added option {DefaultSize}
27 May 2016 added support for Foswiki:Extensions/JQPhotoSwipeContrib and Foswiki:Extensions/AngularSkin; improved support for Foswiki:Extensions/LazyLoadPlugin; fixed frontend parameter; added class parameter
31 Aug 2015 fixing deprecated unescaped left brace in regexes
16 Dec 2014 add support for svg, tiff, xcf and psd
28 Aug 2014 only render the first frame of a gif animation generating thumbnails; fix orientation of thumbnail as specified in the EXIF metadata
29 Nov 2012 removed useless call to expandCommonVariables; removed non-functional UserListByPhotograph
06 Jun 2011 added support for Foswiki:Extensions/LazyLoadPlugin and Foswiki:Extensions/JQPrettyPhotoContrib; deferring expansion of IMAGEGALLERY until other plugins have updated the page
12 Feb 2010 new frontend parameter defaulting to "lightbox" when Foswiki:Extensions/JQueryPlugin is installed
03 Jul 2009 shipping minified and compressed css files now
24 Apr 2009 converted to foswiki plugin
12 Feb 2009 interface improvements; creating more accurate thumbnails
31 Jan 2009 added VarIMAGEGALLERY and VarNRIMAGES documentation topics
29 Dec 2008 temporary fix to work under Foswiki
14 Nov 2008 made format string for galleries more flexible
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 Aurelio 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 T*-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 Martin Cleaver; 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 Marcel Trap; added support for multiple topics (proposed by Martin Cleaver; 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
15 Mar 2002 Initial (internal) version

PackageForm edit

Author Michael Daum, Will Norris
Version 7.20
Release 05 Dec 2015
Description Displays image gallery with auto-generated thumbnails from attachments
Repository https://github.com/foswiki/ImageGalleryPlugin
Copyright 2002-2009, Will Norris; 2005-2016, Michael Daum http://michaeldaumconsulting.com
License GPL (GNU General Public License)
Home Foswiki:Extensions/ImageGalleryPlugin
Support Foswiki:Support/ImageGalleryPlugin
Topic attachments
I Attachment Action Size Date Who Comment
MakefileEXT Makefile manage 124 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
cascade.jpgjpg cascade.jpg manage 30 K 05 Dec 2016 - 09:37 ReginaHuntington  
control-end-gray.pngpng control-end-gray.png manage 423 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
control-end.pngpng control-end.png manage 422 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
control-left-gray.pngpng control-left-gray.png manage 380 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
control-left.pngpng control-left.png manage 396 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
control-right-gray.pngpng control-right-gray.png manage 399 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
control-right.pngpng control-right.png manage 400 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
control-start-gray.pngpng control-start-gray.png manage 411 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
control-start.pngpng control-start.png manage 415 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
cross.pngpng cross.png manage 655 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
style.csscss style.css manage 1 K 05 Dec 2016 - 09:37 ReginaHuntington  
style.css.gzgz style.css.gz manage 527 bytes 05 Dec 2016 - 09:37 ReginaHuntington  
style.uncompressed.csscss style.uncompressed.css manage 1 K 05 Dec 2016 - 09:37 ReginaHuntington  
wave.jpgjpg wave.jpg manage 17 K 05 Dec 2016 - 09:37 ReginaHuntington  
wintermountains.jpgjpg wintermountains.jpg manage 32 K 05 Dec 2016 - 09:37 ReginaHuntington  
Topic revision: r3 - 26 Dec 2016, ReginaHuntington
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback