New Foswiki release 2.1.6 is available with important security fixes.
Sourceforge foswiki email lists being discontinued. Subscribe to the new Foswiki announce and discuss lists at MailingLists

PHOTOGALLERY -- render photo gallery from attachments

The %PHOTOGALLERY% macro is handled by the PhotoGalleryPlugin.


Parameter Description Default
"..." or
Selects the images (attachments) to use for the gallery. Multiple selections can be given by separating them with a comma (selection1,selection2,...,selectionN). Each selection can be:
- /regex/: a case insensitive regular expression enclosed in dashes,
- name: an attachment name, or
- name1..name2: a range extracted from the alphabetically sorted list of all attachments, or
- name1--name2: a range extracted from the list of all attachments ordered by attachment date
i.e. all attachements
with .jpg or .jpeg
(any case) extension
web and
The web and topic to use the attachments from. The parameters will be normalised, i.e. topic can be in the form web.topic. current web
and topic
size Sets the size in pixels for the thumbnails (50..500). 150 1
quality Sets the thumbnail quality factor (1..100). 85 1
sort Selects how to sort the selected attachments (date, name, random or off). Prefix with "-" to reverse the order (-date, -name). Sort on name is case-insensitive. date
width Selects how many thumbnails to show in one row (0 = auto, i.e. as many as there is space). 0
float Float gallery on the left or right (only if width > 0) or keep gallery centred (none). none
remaining Filter-out photos already used by previous galleries (in the same topic) (on or off). off
quiet Do not complain if no images matched the images spec (on or off). off
unique Remove duplicates due to overlapping selections (on or off). on
random Randomly pick a number of images from the list of selected images. 0
admin Display admin action menu if the user has permissions (on or off) or is the owner of the attachment (user). user 1
uidelay Time in seconds until the caption and control elements disappear when idle. Set to 0 to disable hiding the user interface. 4.0
ssdelay Slideshow delay between images in seconds. 5.0
caption Caption format specifier, a string with normal variables in the $var form and "magic" variables in the form (pre)$var[fmt](post), where:
- var is the variable to expand,
- fmt is an optional formatting/scaling parameter for some variables, and
- pre and post are optional strings to prefix and postfix to the expanded variable if it expands to anything.

In a first pass the following normal variables ($var) are expanded:
- $percent, $percnt, $p: Expand to a % character (for escaping other macros).
- $BR: Expands to a %BR% macro, which will insert a line break (<br/> HTML tag).

Then the following magic variables (var) are expanded:
- $n and $N: The photo number and the total number of photos.
- $name and $comment: The attachment name and comment.
- $CreateDate and $date: The exposure time (if available from EXIF data) and the attachment date, respectively. The optional fmt is a %GMTIME% style format string (with an appropriate default 1).
- $size: The file size. The fmt parameter can be MB or KB to scale the size to mega and kilo bytes instead of bytes.
- $ImageWidth and $ImageHeight: The image dimensions in pixels.
- $ImageSize: An appropriately formatted image dimension string (e.g. "3000x2000 6MP").
- $WikiName: The wiki name of the attachment user.
- $ExposureTime, $FocalLength, $ApertureValue, $ISO: appropriately formatted camera parameters (if available from EXIF data).
- $UserComment, $Make, $Model: Unmodified EXIF data fields of the same name (if available).
- $MakeModel: A sanitised concatenation of the "Make" and "Model" EXIF data fields (if available).
- $Lat, $Lon, and $Alt: geographic latitude, longitude and altitude in decimal degrees and metres (if available from EXIF data).
- $Coords: An appropriately formatted geographic location (coordinates) (if available from EXIF data).

Lastly, multiple consecutive, leading and trailing %BR% (i.e. empty lines) will be removed. So you could use $Comment$BR$CreateDate$BR$Coords as a format and it would only produce the lines (breaks) neccessary.
$comment($BR )
$CreateDate(, )
$ExposureTime(, )
$FocalLength(, )
$ApertureValue(, )
$ISO(, )
$Coords(, )
$MakeModel(, )
thumbcap Caption format for thumbails if different from caption format. Set to "" to disable thumbnail captions. see caption
zoomcap Caption format for zoomed photo view if different from caption format. Set to "" to disable captions in viewer. see caption
dayheading Split gallery into sections by adding headings between different days. Use off to disable inserting headings. Use a numerical, decimal hour of day value to specify when a new day starts. E.g. 0 (or on) will consider midnight and 3.5 will consider 03.30h (half past three in the night) as the start of a new day. off
headingfmt A %GMTIME% style format string to format the headings inserted by dayheading. It also expands the standard FormatTokens ($n etc.) $n---++ $wday $day $month $year$n 1

1 These defaults depend on plugin configuration defaults. Your administrator may have chosen to change these.

Multiple %PHOTOGALLERY% macros are allowed in the same topic.


  • %PHOTOGALLERY% – renders a gallery with all photos attached to the current topic
  • %PHOTOGALLERY{ "/^IMG_.+\.JPG$/" }% – uses all "IMG_*.JPG" photos (also "img_*.jpg" as the match is case insensitive)
  • %PHOTOGALLERY{ topic="SomeWeb.SomeTopic" }% – uses all photos from the specified topic
  • %PHOTOGALLERY{ "IMG_1262.jpg,IMG_1265.jpg" }% – uses the two specifed attachments
  • %PHOTOGALLERY{ "IMG_1265.jpg..IMG_1323.jpg" }% – uses all photo from number 1265 to number 1323
  • %PHOTOGALLERY{ "IMG_1265.jpg..IMG_1270.jpg,IMG_1280.jpg..IMG_1290.jpg" }% – uses all photo from number 1265 to number 1270 and from number 1280 to 1290
  • %PHOTOGALLERY{ "/\.jpe?g/,/\.jpe?g/,/\.jpe?g/" sort="off" unique="off" }% – uses all attached photos three times
  • %PHOTOGALLERY{ "doesnotexist" }% – outputs an error message instead of a gallery
  • %PHOTOGALLERY{ remaining="on" quiet="on" }% – outputs a gallery with all remaining photos (those not shown in previous calls to %PHOTOGALLERY% in the same topic) if there are any
  • %PHOTOGALLERY{ random="1" width="1" float="right" }% – show a random single image floating at the right
  • %PHOTOGALLERY{ "/.+\.(jpe?g|png|gif|svg)$/" }% – uses all JPG, PNG, GIF and SVG photos and graphics

See PhotoGalleryPluginTest for some live examples.

Admin Actions

Galleries renderd with the option admin="user" or admin="on" add a tools menu to the thumbnails, if the user has permissions to change the attachment or is the attachment's owner. A gear icon appears in the top right corner of such thumbnails when hovering them with the mouse. The admin menu pops up when hovering the gear icon. The following admin actions are available from the menu:

  • rotate left and rotate right rotate the photo by 90 degrees to the left and the right respectively. The rotation is lossless. These actions are only available for JPEG images.
  • edit allows editing the attachment comment
  • timestamp sets the attachment timestamp to the photo exposure time. The menu entry is only shown if the photo has the necessary EXIF data and if the attachment time differs from the exposure time.
  • delete will delete the photo by moving it to the Trash.TrashAttachment topic (see also FileAttachment)
  • move allows moving a photo to another topic. The provided dialog input field uses JQueryUIAutocomplete to suggest topic names as you type. By default it will look for topic names in the current web. If you specify the web sperated by a dot (e.g. "Main.searchtext") it will look in that web. If you prefix the search text with a dot (e.g. ".searchtext") it will look for matching topic names in all webs.

PhotoGalleryPlugin, PhotoGalleryPluginTest
Topic revision: r14 - 25 Feb 2018, PhilippeKehl - This page was cached on 21 Mar 2018 - 02:26.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License