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
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 |
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.
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 |