/
ImagePlugin.txt
319 lines (279 loc) · 16.4 KB
/
ImagePlugin.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
%META:TOPICINFO{author="ProjectContributor" date="1437152721" format="1.1" version="1"}%
---+!! <nop>%TOPIC%
%FORMFIELD{"Description"}%
%TOC%
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:*
<verbatim>
%IMAGE{"Sandbox/ImagePluginTest/Westminstpalace.jpg"
type="frame"
align="none"
caption="caption text"
}%
</verbatim>
*You get:*
<div style="margin:7px;_width:418px;max-width:418px;">
<a href='%PUBURLPATH%/Sandbox/ImagePluginTest/Westminstpalace.jpg' class='imageHref' title='caption text'>
<img src="%ATTACHURLPATH%/WestminstpalaceSample.png" alt="WestminstpalaceSample.png" width='416' height='339' />
</a>
</div>
*If installed:*
%IMAGE{"Sandbox/ImagePluginTest/Westminstpalace.jpg"
type="frame"
align="none"
caption="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
<verbatim>
* Set IMAGEALBUM = %SYSTEMWEB%.ImagePlugin
</verbatim>
into the current topic will search all images at the given topic.
---++ Syntax
=%<nop>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.
=%<nop>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 |
| =crop= | on/northwest/north/northeast/west/center/east/southwest/south/southeast/off: scrop the image to fit the image into the given aspect ratio; other values than on/off specify the area the croped image gravitates to relative to the original (on=center) | off |
| =data= | json added to the image class used by the jquery stub | empty |
| =desc= | description text | title text |
| =footer= | text to be appended to the html output | empty |
| =format= | image layout format string | set by type argument |
| =frame= | extract a specific frame or layer from the source file; this comes in handy when rendering a thumbnail for a video clip |
| =layer= | alias for =frame= |
| =header= | text to be prepended to the html output | empty |
| =height= | integer value | image width |
| =output= | image format to convert the input source to | same as source image, except tiff and svg being converted to png |
| =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 |
| =rotate= | rotate image by the given dregrees | keep original orientation |
| =size= | geometry specification | image geometry |
| =style= | (see html specs) | empty |
| =title= | title text | *alt* value |
| =tooltipheight= | height of tooltip image | 300 |
| =tooltip= | on/off renders an image preview in a tooltip | off |
| =tooltipcrop= | on/northwest/north/northeast/west/center/east/southwest/south/southeast/off: same as =crop= but used for the tooltip | |
| =tooltipwidth= | width 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 |
| =zoom= | on/off to scale images, if set to "on" scaling up images is allowed, otherwise it downscales only | off |
---+++ 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 |
| =$data= | value of =data= 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 |
| =$thumbfile= | thumbnail image file name |
| =$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 <nop>TopicMarkup that might be
contained is expanded afterwards. Note, that using =$percnt= and =$dollar=
evaluation order of <nop>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 <nop>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:
<verbatim>
<img src='%SCRIPTURLPATH{"rest"}%/ImagePlugin/resize?
topic=web.topic;
file=attachment;
width=300;
height=300'
...
/>
</verbatim>
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
<verbatim>%IMAGE{"Westminstpalace.jpg" size="100" align="left" caption="This is my caption"}%</verbatim>
* Resize to %<nop>THUMBNAIL_SIZE% size, and center image
<verbatim>%IMAGE{"Westminstpalace.jpg" type="thumb" align="center"}%</verbatim>
---++ Configuration
---+++ Links to external images
You can turn on downloading and mirroring of images that link to external sites,
Example: http://www.google.com/intl/en_ALL/images/logo.gif
<verbatim>
$Foswiki::cfg{ImagePlugin}{RenderExternalImageLinks} = 1;
</verbatim>
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.
<verbatim>
$Foswiki::cfg{ImagePlugin}{AutoAttachExternalImages} = 1;
</verbatim>
---+++ Image processing backend
The plugin makes use of either CPAN:Image::Magick or [[http://www.graphicsmagick.org/][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.
<verbatim>
$Foswiki::cfg{ImagePlugin}{Mode} = 'Image::Magick';
</verbatim>
---++ Installation Instructions
%$INSTALL_INSTRUCTIONS%
---++ Dependencies
%$DEPENDENCIES%
---++ Change History
%TABLE{columnwidths="7em" tablewidth="100%"}%
| 06 Apr 2016 | fixed attaching inline data images |
| 01 Apr 2016 | fixed resize rest handler returning invalid image data; \
working around buggy implementations of imagemagick core-dumping on exit |
| 26 Sep 2015 | fixed rewrite of html img tags to bail out when width/height units aren't px values; \
don't auto-render svg to png anymore |
| 17 Jul 2015 | optionally extract and convert inline svg to real images; \
optionally process html img tags and downscale them on the server; \
add support for Foswiki-2.x |
| 16 Dec 2014 | work around call to unofficial internal api to get absolute pub urls;\
support extracting thumbnails from movies (mp4,mov,m4v,mpeg,mpg and wmv) |
| 17 Sep 2014 | added feature to convert inline image data to proper attachments |
| 08 Sep 2014 | added =rotate= parameter |
| 04 Sep 2014 | implemented =frame= and =layer= parameter for thumbnail extraction from videos, animations and layered images |
| 28 Aug 2014 | only render the first frame of a gif animation generating thumbnails; \
fix orientation of thumbnail as specified in the EXIF metadata; \
fully specify REST security flags; \
new parameter =output= |
| 28 May 2014: | fixed thumbnail handling in afterRenameHandler |
| 16 Apr 2014: | brought back =thumb= image type |
| 04 Apr 2014: | flag rest handlers that don't require authentication |
| 18 Mar 2014: | support blanks in image names |
| 3 Aug 2013: | rework image tooltip code to use jquery-ui instead of deprecated jquery.tooltip |
| 8 May 2013: | return a 1x1 pixel when calling the image rest handler for a non-existing image |
| 24 May 2013: | update thumbnails whenever a new image of the same name was uploaded |
| 6 May 2013: | some more svg fixes; cleaning up thumbnails now when images are renamed or moved |
| 9 Oct 2012: | added svg support |
| 6 Aug 2012: | respect noautolink tags when rendering external image links |
| 25 Jun 2012: | fixed attaching external images to the right topic; \
removed unused option =AutoAttachThumbnails=; \
fixed processing of non-attached external images; \
fixed downloading of urls that look like image links but return a different content type |
| 09 Jan 2012: | added new option 'thumbfile' to format string (Foswiki:Main/JoenioCosta);\
speed improvement by not "ping-ing" each image on display; \
rendering thumbnails using newer method available in image::magick 6.5.x, the old method faild resizing and cropping on some platforms;\
removing =longdesc= from default image templates; \
now also caching urls to external images that include url params |
| 29 Jun 2011: | fixed detection of image links to the own wiki not to try an external download+mirror |
| 10 Jan 2011: | fixed parsing of mediawiki like params; \
fixed jquery interface to foswiki preferences; \
fixed dependency on !ZonePlugin to only be required for old foswiki versions; \
make result of resize REST service cacheable, i.e. don't use a redirect; \
fixed expansion of standard escapes; \
improved crop parameter to specify the location of the remaining image relative to the original; \
added data parameter to interface with jquery code; \
using md5 now to properly cache thumbnails; \
mirroring external images now obeys the ATTACHFILESIZELIMIT preference; |
| 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 <nop>I18N workaround |
| 18 Aug 2006: | fixed html errors; \
removed references to <nop>ImgPlugin thus not showing the magnify-clip; \
some html and css fixes to resemble closer to the <nop>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 <nop>ImgPlugin |
%META:FILEATTACHMENT{name="WestminstpalaceSample.png" attr="h" comment="" date="1437152721" path="WestminstpalaceSample.png" size="107728" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="logo.gif" attachment="logo.gif" attr="h" date="1437152721" path="http://www.google.com/intl/en_ALL/images/logo.gif" size="8558" user="ProjectContributor" version="1"}%
%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="Craig Meyer, Michael Daum"}%
%META:FIELD{name="Copyright" title="Copyright" value="© 2006, Craig Meyer, %BR% © 2006-2016 Michael Daum http://michaeldaumconsulting.com"}%
%META:FIELD{name="Home" title="Home" value="Foswiki:Extensions/%TOPIC%"}%
%META:FIELD{name="License" title="License" value="GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]])"}%
%META:FIELD{name="Release" title="Release" value="%25$RELEASE%25"}%
%META:FIELD{name="Description" title="Release" value="%25$SHORTDESCRIPTION%25"}%
%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/ImagePlugin"}%
%META:FIELD{name="Support" title="Support" value="Foswiki:Support/%TOPIC%"}%
%META:FIELD{name="Version" title="Version" value="%25$VERSION%25"}%