Photo Gallery Plugin

A gallery plugin for JPEG photos from digital cameras (and PNG, GIF and SVG graphics)

Description

This plugin renders galleries from photos attached to topics. Galleries render as a grid of square thumbnails. Thumbnails are created using the Epeg library ("insanely fast JPEG thumbnail scaling") via the Image::Epeg Perl module. Clicking on a thumbnail zooms the image to the original attached photo. Currently PhotoSwipe by Dmitry Semenov is used to display the photos. It allows zooming and browsing the image gallery with the keyboard, the mouse and finger swipes on touch devices. This plugin adds a slideshow functionality not currently present in the original PhotoSwipe gallery. The thumbnails expose a tools menu by hovering over their top right corner. Available tools include losslessly rotating the photo using exiftran, editing the attachment comment, correcting the attachment timestamp to the photo exposure date, moving the attachment to another topic, and deleting the attachment.

This plugin is primarily intended to be used with JPEG images and it works best with photos from digital cameras that have EXIF data embedded. It can display PNG, GIF and SVG graphics as well. It needs a fairly recent browser to support various Javascript and image scaling and transition magic.

The plugin also ships with a bulk attach script with built-in help. An optional a skin extension to allow bulk uploading of images (or any file, even without activating or using this plugin) via the normal attach action is included as well. Currently DropzoneJS by Matias Meno is used to support bulk uploading.

See Foswiki::Plugins::PhotoGalleryPlugin for developer details.

---

Screenshots

Here are a few screenshots of the plugin in action:

---

Usage

%PHOTOGALLERY% Macro

See VarPHOTOGALLERY on how to use it. See Sandbox.PhotoGalleryPluginTest for some examples.

Bulk Attach Script

The script can be found in the Foswiki installation folder in tools/photogallerypluginattach.pl. Run it as the same user Foswiki runs as (often this is the www-data system user).

The script will "properly" attach images using the Foswiki engine (as opposed to directly "hack" it into the topic database). This makes sure that the attachment owner and all other meta data are correct and it also uses the automatic JPEG rotatation and timestamp features described above (if this plugin is activated). The script is not limited to photos or this plugin in general. It can be used to attach arbitrary files (even without this plugin installed).

Example: tools/photogallerypluginattach.pl -C -g -u WikiUsername Main.HolidaysInTheUpsideDown /path/to/photos/*jpg

Thumbnail REST Service

There is a REST handler (see CommandAndCGIScripts) at %SCRIPTURLPATH{"rest"}%/PhotoGalleryPlugin/resize. It takes the following parameters:

• topic – (required) the topic from which to take the attachment (Web.Topic format)
• name – (required) name of the attachment in that topic
• quality – (optional) JPEG quality factor of the generated thumbnail
• width – (required) width in pixels of the generated thumbnail
• height – (required) height in pixels of the generated thumbnail
• ver &ndash: (optional) attachment version, used to invalidate cache
• uid – (optional) image version (serial), used to invalidate cache

The handler returns a thumbnail in JPEG format. It caches the thumbnail and respects attachment/topic view permissions.

Example: <img src="%SCRIPTURLPATH{"rest"}%/PhotoGalleryPlugin/thumb?topic=Sandbox.PhotoGalleryPluginTest;name=IMG_1262.jpg;quality=85;uid=0;width=200;height=150"/>

Gives (if plugin is activated):

---

Preferences

Plugin Configuration and Defaults

The following settings are available in the configure interface for several of VarPHOTOGALLERY's defaults:

• {Plugins}{PhotoGalleryPlugin}{ExifTranPath} – path to the exiftran utility
• {Plugins}{PhotoGalleryPlugin}{QualityDefault} – the default thumbnail quality factor
• {Plugins}{PhotoGalleryPlugin}{DateFmtDefault} – the default time format to render timestamps
• {Plugins}{PhotoGalleryPlugin}{CaptFmtDefault} – the default caption format for thumbnails and photos
• {Plugins}{PhotoGalleryPlugin}{AdminDefault} – the default admin mode
• {Plugins}{PhotoGalleryPlugin}{SizeDefault} – the default thumbnail size
• {Plugins}{PhotoGalleryPlugin}{HeadingFmtDefault} – the default day heading format

The plugin does not use any preference settings.

Skin Extensions

This plugin comes with two skin extensions to the PatternSkin.

The first adds two options (checkboxes) to the upload form, namely an option to activate lossless rotation of JPEG images based on EXIF camera orientation meta data, and an option to set the attachment upload date to the photo exposure time (from EXIF).

The second replaces the upload form with bulk upload form that allows batch uploading multiple files, editing filenames and comments and more.

The skin extensions come in the form of a skin templates. See the Installation section below.

---

Installation

Plugin

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.

This plugin needs the exiftran utility installed on the system in order to provide the photo rotation feature described above. In Linux distributions the package is typically called "exiftran" and can be installed through "package managers" or "software centres". Try the command sudo apt-get install exiftran on Debian and derivates.

The Image::Epeg Perl module, required for fast JPEG thumbnail generation, might not be available as a system package. It can be downloaded from CPAN and be built and installed manually (see e.g. here).

For other graphics formats Graphics::Magick or Image::Magick is used to generate thumbnails. No thumbnails will be shown if none of these is available.

Skin Extensions

To activate the upload form options described above add (prepend) photogallery (for JPEG rotation and timestamp options) and/or bulkupload (for bulk uploading) to the SKIN list in Main.SitePreferences. See Skins for details.

The bulkupload skin extension also works without activating this plugin. Installing the RenderPlugin is recommended with this skin extension (see Dependencies below).

Cache

The plugin caches data (EXIF meta data, thumbnails) in the working/work_areas/PhotoSwipePlugin directory. It will keep the timestamps of the used files up-to-date. The plugin ships with a script to clean up the cache by removing old files from the cache directory. It is suggested to install a cronjob to run the script on a regular basis. Run tools/photogalleryplugincleanup.pl -h to see the built-in help for more details. Alternatively, standard system tools, such as "tmpreaper", can be used to remove old files. No harm is done removing them all from time to time.

Upgrading

If you have page caching enabled you may need to clear the page cache after upgrading this plugin. See PageCaching for details.

---

Dependencies

Name	Version	Description
JSON	>=0.1	Required for REST handler feedback (not sure which version is the minimal requirement)
Image::ExifTool	>=0.1	Required for extracting and displaying photo meta data (not sure which version is the minimal requirement)
File::Copy	>=0.1	Required for photo manipulation operations (not sure which version is the minimal requirement)
Error	>=0.1	Required for error handling (not sure which version is the minimal requirement)
POSIX	>=0.1	Required for file operations (not sure which version is the minimal requirement)
Digest::MD5	>=0.1	Required for caching (not sure which version is the minimal requirement)
Storable	>=0.1	Required for caching (not sure which version is the minimal requirement)
File::Touch	>=0.1	Required for caching (not sure which version is the minimal requirement)
List::Util	>=0.1	Required (not sure which version is the minimal requirement)
Image::Epeg	>=0.13	Required for fast thumbnail generation
Image::Magick	>=0.1	Optional (this or Graphics::Magick) for PNG/GIF/SVG thumbnail generation (not sure which version is the minimal requirement)
Graphics::Magick	>=0.1	Optional (this or Image::Magick) for PNG/GIF/SVG thumbnail generation (not sure which version is the minimal requirement)
Foswiki::Plugins::JQueryPlugin	>=6.32	Required for everything
Foswiki::Contrib::FamFamFamContrib	>=1.9	Required for action menu items
Foswiki::Plugins	>=2.1	Required plugin interface
Foswiki::Plugins::RenderPlugin	>=4.10	Optional for the bulk upload skin extension

---

Change History

Date	Version	Comments
9 Jan 2021	v1.16	- minor fixes - fix html problem with filenames that contain WikiWords - fix bug where clicking a thumb would sometimes open another picture
5 Jul 2018	v1.15	- fix attachment meta data - fix bulk upload skin extension for installations that don't use the strikeone request validation thingy - fix gallery layout for a Firefox weirdness when layout.css.devPixelsPerPx is non-integer (HiDPI screens)
28 Jun 2018	v1.14	- fix an uncritical warning - remove leading and trailing whitespace from edited filenames - fix for installations that don't use the strikeone request validation thingy
25 Feb 2018	v1.13	- fix default parameter - handle errors in regular expression in images parameter - add example on how to select all supported picture and graphics
25 Dec 2017	v1.12	- Add random parameter to randomly select a number of attachments. - Add reverse date and name and random sorting (sort paramter). - Allow empty thumbcap and zoomcap to disable captions. - Add minimal support for PNG, GIF and SVG graphics. - Document thumbnail REST handler. - Various minor code/css/docu improvements.
23 Dec 2017	v1.11	- highlight last viewed photo's thumbnail when exiting fullscreen viewer - add width and float parameters for more layout control
23 Dec 2017	v1.10	photo gallery plugin: - documentation cleanup - when leaving viewer, only scroll page if thumb is not fully visible, only animate y axis bulk upload skin extension: - allow specifying for what files a upload form attribute is usable, and used that to allow the rotate and timestamp attributes only for jpeg images - allow double-clicking attribute checkboxes to propagate state to other pending files - notify (warn) user if attachment table could not be refresed (RenderPlugin missing)
11 Mar 2017	v1.9	- set minimal Foswiki required to release 2.1.3, see Foswiki:System/ReleaseNotes02x01 - update photogallery.tmpl to use the new mechanism of adding attachment properties to the attach dialog, see Foswiki:Tasks/Item14092 - allow re-ordering pending items in the upload queue (bulk upload skin extension)
23 Dec 2016	v1.8	- widen file size column in bulk upload form to avoid clipping of text - remove all use of JQueryUITooltip in bulk upload form as it doesn't work well, rely on browser tooltip instead - allow renaming the file name in the bulk upload form before uploading - consider that Foswiki may change the uploaded file name to remove illegal characters - various style improvements in the bulk upload form - scroll thumbnail view to last viewed photo on exit of fullscreen - remove dead links from fullscreen caption
12 Nov 2016	v1.7	- move file upload properties to the upload items in the bulk upload form for easier editing - completely replace PatternSkin upload form with bulk upload form - minor improvements and documentation updates
9 Sep 2016	v1.6	- bulk upload improvements: replace unreliable jquery ui tooltips on buttons with a help twisty, highlight uploaded files in attachments table - improve file properties editing in bulk upload form - display average upload speed in bulk upload progress bar - improved, simplified and optimised image info caching code (no visible changes) - prevent thumbnails from being unnecessarily regenerated on PageCaching refresh and other circumstances - improve and cleanup various code and documentation bits
19 Jun 2016	v1.5	- add bulk upload skin extension that extends the standard PatternSkin attach page with bulk upload capabilities - remove TopicInteractionPlugin skin extension - make the whole thumbnail area clickable while the thumbnail image is being loaded - various cleanup and small improvements
29 May 2016	v1.4	- minor cleanup (remove duplicate function, fix dependency file)
16 May 2016	v1.3	- add possibility to automatically split galleries into individual days by injecting customisable headings - minor documentation improvements
1 May 2016	v1.2	- add cache cleanup script - improve bulk upload script - force meta data and thumbnail cache update when attachment version changes - fix plugin crash when all attachments are unreadable (file gone, but FILEATTACHMENT still there) - fix display of timestamp admin menu entry - allow saving empty comment - improved various bits in the plugin code
21 Apr 2016	v1.1	- cleanup and improve docu - fix setting EXIF exposure date on upload - add bulk upload script
15 Apr 2016	v1.0	- initial released version