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:
caption text
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
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 |
