ImagePlugin

Introduction

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{"WestminstpalaceSample.png"
  type="frame" 
  align="none" 
  caption="caption text"
}%

You get:

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 = TWiki.ImagePlugin

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.

(hidden feature: %IMAGE{"clear"}% will create a proper clear for your floats )

Arguments

The image name is mandatory. Further arguments are optional.

Name	Values	Default
title	title text	alt value
caption	caption text	empty
footer	text to be appended to the html output	empty
header	text to be prepended to the html output	empty
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
style	(see html specs)	empty
alt	alt text	image filename
size	geometry specification	image geometry
height	integer value	image width
width	integer value	image width
class	(see html specs)	imageFrame, imageFloat, ... depending on the type
warn	on/off, surpress error warnings	on
type	simple|link|thumb[nail]|frame|float"	plain
align	left|center|right|none	right
format	image layout format string	set by type argument
desc	description text	title text
topic	valid TWiki topic name	topic part of IMGALBUM value or current topic
href	hyperlink when clicking on the image	url of the source image
web	valid TWiki web name	web part of IMGALBUM value or current topic

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 extact measure use the width and height arguments.

Format specification

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

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

Examples

• %IMAGE{"foo.gif" size="100" align="left" caption="This is my caption"}% (resize to 100 pixels, text flows right, with caption)
• %IMAGE{"foo.gif" type="thumb" align="center"}% (Resize to %THUMBNAIL_SIZE% size, and center image)

Plugin Installation Instructions

• Download the ZIP file
• Unzip ImagePlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/Sandbox/ImagePluginTest.txt
  data/TWiki/ImagePlugin.txt
  lib/TWiki/Plugins/ImagePlugin/Core.pm
  lib/TWiki/Plugins/ImagePlugin.pm
  pub/Sandbox/ImagePluginTest/STS-32_crew.jpg
  pub/Sandbox/ImagePluginTest/Tst.png
  pub/Sandbox/ImagePluginTest/Westminstpalace.jpg
  pub/TWiki/ImagePlugin/WestminstpalaceSample.png
  pub/TWiki/ImagePlugin/magnify-clip.png
  pub/TWiki/ImagePlugin/style.css

• Optionally, run ImagePlugin_installer to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
• Alternatively, manually make sure the dependencies listed in the table below are resolved.

  Name	Version	Description
  Graphics::Magick	>=1.1.11	Required.
  Image::Magick	>=6.2.4.5	Optional.

• Configure the Plugin:
  • Run the configure script to enable the Plugin
  • Change the Plugin settings as needed
• Test if the installation was successful:
  • For complete example see ImagePluginTest

Plugin Info

• Set SHORTDESCRIPTION = Control the display and alignment of images using an easy syntax

Plugin Author:	TWiki:Main.CraigMeyer
Copyright:	© 2006, TWiki:Main.CraigMeyer, © 2006-2008 Michael Daum http://michaeldaumconsulting.com, © 2006-2010 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	19301 (2010-08-01)
Change History:
2010-08-01:	TWikibug:Item6530 - doc fixes; changing TWIKIWEB to SYSTEMWEB
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
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	CPAN:Graphics::Magick; CPAN:LWP::UserAgent; CPAN:Digest::MD5
Other Dependencies:
Perl Version:	5.8
Benchmarks:	GoodStyle nn%, FormattedSearch nn%, ImagePlugin nn%
Plugin Home:	http://twiki.org/cgi-bin/view/Plugins/ImagePlugin
Feedback:	http://twiki.org/cgi-bin/view/Plugins/ImagePluginDev
Appraisal:	http://twiki.org/cgi-bin/view/Plugins/ImagePluginAppraisal

Related Topics: TWikiPlugins, UserDocumentationCategory