ImagePlugin

Use this plugin to control the display and alignment of images using an easy syntax and support for server-side resizing and thumbnailing. There are a set of pre-defined layout formats for images as well as a free layout configurability.

Short example:

You type:

%IMAGE{"Sandbox/ImagePluginTest/Westminstpalace.jpg"
  type="frame" 
  align="none" 
  caption="caption text"
}%

You get:

If installed:

Images to be displayed can be located

• at the topic as specified,
• at the location specified in the IMAGEALBUM preference variable,
• at the current topic or
• at a remote URL.

If you specify a remote url using http://... the image is downloaded (using CPAN:LWP::Simple) into a local cache and then processed as usual. WARNING: please be aware of any copyrights of the images you mirror this way.

The topic and IMAGEALBUM parameters can be of the for [<web>.]<topic> . For example putting

   * Set IMAGEALBUM = %SYSTEMWEB%.ImagePlugin

into the current topic will search all images at the given topic.

Syntax

%IMAGE{"foo.gif" ...}%

There are four predefined format types (plain, simple, link, thumbnail, frame, float) that can be used by setting the type paramenter (see below). In addition there is a free-form format parameter to specify any other possible html layout. The Wikipedia format is also supported. See Wikipedia:Wikipedia:Extended_image_syntax.

%IMAGE{"clear"}% will create a proper clear for floats elements.

Arguments

The image name is mandatory. Further arguments are optional.

Name	Values	Default
align	left|center|right|none	right
alt	alt text	image filename
caption	caption text	empty
class	(see html specs)	imageFrame, imageFloat, ... depending on the type
desc	description text	title text
footer	text to be appended to the html output	empty
format	image layout format string	set by type argument
header	text to be prepended to the html output	empty
height	integer value	image width
href	hyperlink when clicking on the image	url of the source image
id	(see html specs)	empty
mousein	javascript executed if moving the mouse over the image	empty
mouseout	javascript executed if moving the mouse off the image	empty
refresh	on/off/img to trigger recomputing images	off
size	geometry specification	image geometry
zoom	on/off to scale images, if set to "on" scaling up images is allowed, otherwise it downscales only	off
style	(see html specs)	empty
title	title text	alt value
tooltip	on/off	off
tooltipwidth	width of tooltip image	300
tooltipheight	height of tooltip image	300
topic	valid topic name	topic part of IMGALBUM value or current topic
type	simple, plain, link, thumb[nail], frame, float	plain
warn	on/off, surpress error warnings	on
web	valid web name	web part of IMGALBUM value or current topic
width	integer value	image width

Tooltip preview

The tooltip argument allows rendering image previews in a tooltip. This option only has effect if Foswiki:Extensions.JQueryPlugin is installed that comes with the jquery.tooltip plugin used to render the image tooltip here.

Image geometry

The image geometry in the size parameter can be specified in a format <width>[px][x<height>[px]], that is width and height can be given as integers with an optional px, where the height is optional, separated with a 'x' in between. Note, that the given width and height values are the maximum width and maximum height that the image will have keeping its aspect ratio. If you want to deform it to an exact measure use the width and height arguments.

Note, that you must set zoom="on" to scale images up. Otherwise images smaller than the given geometry will stay as they are. For instance, when generating thumbnails it is preferable to keep small icons as they are instead of bloating them up to a standard thumbnail size.

Format specification

Format strings given in header, footer and format may contain the following pseudo variables:

Name	Value
$align	value of align argumet
$alt	value of alt argumet
$caption	caption text
$class	value of class argumet
$desc	value of desc argument
$dollar	replaced with dollar sign ($)
$height	image height
$href	hyperlink url when clicking on an image
$id	value of id argumet
$magnifyIcon	enlage-icon
$mousein	value of mousein argument
$mouseout	value of mouseout argument
$n	replaced with a linefeed (\n)
$nop	replaced with empty string
$origheight	image height of the original image
$origsrc	url of the original image (not the resized one)
$origwidth	image width of the original image
$percnt	replaced with percent sign (%)
$src	image source url
$style	value of style argumet
$text	link text to be displayed in the "link" layout type
$title	value of title argument
$width	image width

After the layout has been formatted any further TopicMarkup that might be contained is expanded afterwards. Note, that using $percnt and $dollar evaluation order of TopicMarkup can be changed so that arguments are expanded after the IMAGE tag has been computed, whereas the default evaluation order is left-to-right-inside-out.

REST image service

The ImagePlugin implements a REST handler resize to generate thumbnails for image attachments on the fly. This handler is then called in an img tag like this:

<img src='%PUBURLPATH%/rest/ImagePlugin/resize?
  topic=web.topic;
  file=attachment;
  width=300;
  height=300'
  ...
/>

Arguments to the resize handlers are:

Name	Values	Default
topic	specifies the topic where the image is attached	BASEWEB.BASETOPIC
file	specifies the image filename
width	width of thumbnail
height	height of thumbnail
size	geometry of thumbnail
zoom	switch on/off upscaling
refresh	on/off/img to trigger recomputing images	off

Examples

• See also Sandbox.ImagePluginTest for an exhaustive sample and test page
• Resize to 100 pixels, text flows right, with caption

  %IMAGE{"Westminstpalace.jpg" size="100" align="left" caption="This is my caption"}%

• Resize to %THUMBNAIL_SIZE% size, and center image

  %IMAGE{"Westminstpalace.jpg" type="thumb" align="center"}%

Configuration

Links to external images

You can turn on downloading and mirroring of images that link to external sites, Example:

$Foswiki::cfg{ImagePlugin}{RenderExternalImageLinks} = 1;

This will download the image and mirror it on the local site. Use the refresh url parameter to check if the external images has updated.

If you also turn on attaching a mirrored image to the current topic, an additional attachment-record is generated for the downloaded external image. Attachments will be marked as hidden. Note, that any auto-attached image will update the topic and with it its timestamp.

$Foswiki::cfg{ImagePlugin}{AutoAttachExternalImages} = 1;

Attaching auto-generated thumbnails

Automatically generated thumbnails are attached to the current topic when you switch on

$Foswiki::cfg{ImagePlugin}{AutoAttachThumbnails} = 1;

This might be of interest when you'd like to access these thumbnails using other plugins.

Image processing backend

The plugin makes use of either CPAN:Image::Magick or Graphics::Magick, a fork of the former. Both are compatible as far as they are used here. Graphics::Magick does seem to perform faster than Image::Magick; some Image::Magick might be broken on your server distribution. By default Image::Magick is used as it is the more common extension for perlbased image processing.

$Foswiki::cfg{ImagePlugin}{Mode} = 'Image::Magick';

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

Plugin Info

Plugin Author:	Craig Meyer, Foswiki:Main.MichaelDaum
Copyright:	© 2006, Craig Meyer, © 2006-2010 Michael Daum http://michaeldaumconsulting.com
License:	GPL (GNU General Public License)
Release:	2.31
Version:	6307 (2010-02-12)
Change History:
12 Feb 2010:	made imagetooltip a proper jQuery plugin; using Foswiki:Extensions/ZonePlugin for faster page loads
17 Nov 2009:	added zoom parameter; fixed manual refresh via url params
24 Sep 2009:	updated imageplugin.template to help XHTML validation (stop rendering empty id attribute)
14 Sep 2009:	using Foswiki's proxy settings instead of ENV; disabled tooltip previews for Internet Explorers
18 Aug 2009:	removed bonus % in template (Foswiki:Main.AndreLichtsteiner, Foswiki:Main.WillNorris)
24 Apr 2009:	converted to foswiki plugin; added thumbnail REST handler; added tooltip preview using jquery; added mirroring of external images; moved image type definitions into a template
11 Feb 2009:	updated documentation examples (Foswiki:Main.WillNorris)
07 Jan 2009:	certified for foswiki/compat
03 Jul 2008:	fixed parsing the type parameter; fixing docu about the default THUMBNAIL_SIZE; added new default format plain; plainify text to be used in a html attribute position, e.g. titles; default to no img alignment; refresh images on a ?refresh=on url param; using LWP::UserAgent instead of LWP::Simple to mirror images; using Resize instead of Scale for higher quality thumbnails; don't encrypt the href param
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
03 Jan 2008:	added processing of remote images
18 Dec 2006:	fixed image lookup order; fixed html formats; added I18N workaround
18 Aug 2006:	fixed html errors; removed references to ImgPlugin thus not showing the magnify-clip; some html and css fixes to resemble closer to the MediaWiki examples
17 Aug 2006:	width and height arguments had no effect; floating images not clearing proberly on IE
16 June 2006:	released into the public
10 May 2006:	Initial version by forking ImgPlugin
Dependency:	$Foswiki::Plugins::VERSION 1.1
CPAN Dependencies:	Name Version Description Image::Magick >=6.2.4.5 Required. LWP::UserAgent >=0 Required. Graphics::Magick >=1.1.11 Optional. Foswiki::Plugins::JQueryPlugin >=3740 Optional. Foswiki::Plugins::ZonePlugin >=1.0 Required.
Other Dependencies:
Perl Version:	5.8
Home:	Foswiki:Extensions/ImagePlugin
Support:	Foswiki:Support/ImagePlugin