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

%IMAGEGALLERY{size="large" exclude="logo"}%

Syntax

%IMAGEGALLERY{...}%

Argument	Description	Default
topic	comma separated list of topics whose attachments should be displayed	current topic
class	add an additional css class attribute to the image gallery wrapper	igp + class depending on the frontend and layout being used; there are a few special classes that add a hover effect to the images: zoomInImages, zoomOutImages, brightenImages, darkenImages
exclude	regular expression an image must not match to be part of the gallery
field	specify which property of the image has to match using include or exclude; possible values: name, comment (default: name)
footer	footer part of the gallery	/lt;/div>
format	format of an image	%IMAGE{"$name" topic="$web.$topic" align="left" size="$size" crop="$crop" caption="$title" tooltip="$tooltip" filter="$filter"}%=
frontend	select gallery interface, possible values are default, slimbox, prettyphoto, photoswipe	photoswipe, prettyphoto or slimbox (in the given prioirty)
header	header part of the gallery	<div class="$class clearfix" data-item-selector=".imageSimple">
include	regular expression an image must match to be part of the gallery
showhidden	boolean flag to include images that are hidden; set to off to hide hidden images	on
layout	thumbnail layout algorithm, can be either packery (using Foswiki:Extensions/JQPackeryContrib) or masonry or undefined
limit	maximum number of images to display	0, meaning no limit
reverse	invert the initial order of the images, can be on or off	off
size	the thumbnail size, the actual geometries of a size can be configured below; possible values: tiny, small, medium, large, huge (default: medium)
sort	set the initial order of the images, can be name, date, size or comment	date
titles	toggles image and thumnail titles on and off	off
warn	toogles display of error messages, i.e. when no image was found	on

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

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

Format variables

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.

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. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Plugins::ImagePlugin	>=10.00	Required
Foswiki::Plugins::JQueryPlugin	>=3.74	Optional

Change History

26 Oct 2020	added support for native lazy loading of images; added showhidden parameter to exclude hidden images from the gallery
27 Jul 2017	massive rewrite using Foswiki:Extensions/ImagePlugin as a backend now; removed NRIMAGES macro; oo-ified implementation; added support for various frontends implementing a lightshow preview, for now photoswipe, prettyphoto and slimbox
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