ThumbnailPlugin < Extensions

You are here: Foswiki>Extensions Web>ThumbnailPlugin (09 Dec 2009, CrawfordCurrie) (raw view)
<!--
This topic is part of the documentation for Development.ThumbnailPlugin and is
automatically generated from Subversion. Do not edit it! Your edits
will be lost the next time the topic is uploaded!

If you want to report an error in the topic, please raise a report at
http://foswiki.org/view/Tasks/ThumbnailPlugin
-->
---+!! !Development.ThumbnailPlugin

Thumbnails for everyone

%TOC%

---++ Syntax Rules
---+++ %<nop>THUMBNAIL{ name="filename" variant="size" }%

Given an image file name, returns the name of its thumbnail file of the given size.

Normally, you don't give the size, as it will default from a preference variable. But if you want an especially large (or small) icon selectively, the syntax allows for that.

This plugin can be enabled on a per-topic, web, or site basis using the THUMBNAILPLUGIN_ENABLE preference variable.

When this plugin is enabled for a topic, any image attachment that is saved will have one or more thumbnails autogenerated for it. Image attachments types currently supported are: *.jpg .gif .png*

The thumbnail's size will be determined from the preference variable THUMBNAILPLUGIN_SIZE, which defaults to 150 (pixels).

The preference variables can be set in the containing topic, your home topic, the containing web's !WebPreferences topic, or the site !WebPreferences topics. If a preference is set in multiple places, the value closest to the topic using the plugin will be used.

Use multiple sizes for accessibility as well as for esthetics. However, they do take time to generate, so don't go _too_ wild.

Used with the !AttachLinkPlugin and !ImgPlugin, it becomes easy to do things like display hyperlinks to images as thumbnails of that image. Examples below. But if that's what you want, use %<nop>THUMBVIEW instead.

Note that the THUMBNAILPLUGIN_ENABLE preference controls thumbnail generation on upload; it does not control expansion of the %<nop>THUMBNAIL and %<nop>THUMBVIEW variables.
---+++ %<nop>THUMBVIEW{ name="filename" variant="size" topic="topic" web="web" caption="string" cpos="position" align="string" border="" height="" width="" id="" class="" link="filename" ltopic="topic" lweb="web" fullpath="" }%

This is a lot simpler than it looks, as all the defaults are reasonable.

   * name - Filename of image to be displayed. Required.
   * variant - Thumnail size to be displayed. Defaults to the first value of the THUMBNAILPLUGIN_SIZE preference variable.
   * topic - the topic to which the image is attached. Defaults to the current topic.
   * web - the web containing the topic to which the image is attached. Defaults to the current web.
   * caption - string to be used to caption the thumbnail. If present, the thumbnail will be displayed within a small table. If not, no caption will be used.
   * cpos - caption position: top, bottom, left or right. Where to position the caption. Default is bottom.
   * align, border, height, width, id, class - usual HTML tags, applied to the thumbnail or the table that contains it.
   * attrs="string" - arbitrary html tag='value' list if you really need that level of control - e.g. onclick= or some such
   * link - filename of attachment to be displayed when the thumbnail image is clicked. Defaults to the name argument (that is, the full size version of the thumbnail)
   * ltopic, lweb - topic & web to which the link target is attached. Default to the topic, web arguments.
   * nolink - set to 1 if you don't want the thumbnail to be clickable.
   * lid, lclass, ltarget, lname - HTML parameters applied (without the leading l) to the link.
   * fullpath - set to 1 if you want the link references to include the hostname; 0 will just specify the resource. Default is THUMBNAILPLUGIN_FULLPATH, or 0 if undefined.
   * lalign, lborder, lheight, lwidth, lid, lclass - usual HTML tags, applied to the link.
   * lattrs="string" - arbitrary html tag='value' list for the link if you really need that level of control
---++ attachutil

The !Development.ThumbnailPlugin distribution also includes __attachutil__, which is a utility script for manipulating attachments. Although it has special support for !Development.ThumbnailPlugin, it is generally useful, especially for refactoring topics. (Perhaps someone would like to package it as a separate Contrib.)

__attachutil__ is located in the __tools__ directory, and has the following commands:
   * <p>attachutil attach -h -r -c 'comment' web.topic files</p>
      * Attaches listed files to web.topic.
      * -h will mark the files 'hidden' (not shown in the attachment table)
      * -r will replace existing attachment of the same name if it exists
      * -c provides the attachment's comment (shown in the attachment table)
   * <p>attachutil hide web.topic attachments</p>
      * Mark existing attachments as hidden

   * attachutil unhide web.topic attachments 
      * Mark existing attachments as visible

   * attachutil list -v web.topic attachments 
      * list attachments; default is to list all
      * -v will show thumbnail sizes

   * attachutil move -r web.topic web.topic attachments 
      * Move existing attachments from web.topic1 to web.topic 2
      * May specify destination web, topic, or web.topic
      * Default destination is same web, same topic
      * Will move thumbnails

   * attachutil remove web.topic attachments 
      * Remove existing attachments from topic
      * Actually, moves them to the configured Trash web, attachment
      * Will add a sequence number if the name already exists in the trash, unless -r is specified.

   * attachutil thumb sizes web.topic attachments 
      * Adds sizes (one or more) thumbnails to existing attachments
      * Use when auto thumbnail generation was not enabled at initial upload, or when you need new size(s)
      * sizes are in pixels, space separated list
      * Ignores attachments that are not a known image type

   * attachutil update web.topic attachments 
      * Updates file size, date attributes of existing attachments
      * Useful if you've broken the rules and manipulated attachments with non-wiki tools

General rules:
   * Default web is =Sandbox= - though this may be changed in the future.
   * -v will list each action on stderr
   * -u username will change the (OS) user to username if script is run as root/uid 0. 
      * Default is 'apache'
      * Helps keep file ownership correct for thumbnails.
   * -r will replace existing attachment
   * attachment names can be wildcarded (shell-style glob); use shell quotes
   * You can alias (or softlink) any command to save typing.

This plugin requires the *[[http://search.cpan.org/search?query=GD&mode=all][GD]]* and *[[http://search.cpan.org/search?query=Image::MetaData::JPEG&mode=all][Image::MetaData::JPEG]]* libraries from CPAN.

---++ CAVEAT

This is a working prototype. Because of limitations of the current plugin interface, thumbnail auto-creation is unclean.
   * Do not rely on the filenames or locations of the thumbnail files, which are subject to change.
   * Do not name attachments <anything>_thumbnail_size.<anything> - these are the currently auto-created files.
   * You probably will *not* want the {AutoAttachPubFiles} configuration option set, as the thumbnail files are not (yet) first class attachments.
   * Until the plugin interface issues are resovled, this may break in future versions of the wiki.

It is intended, but not guaranteed that updates to correct these issues will not require changes to your topics. They may require running an upgrade script.

Although this warning may sound a bit scary, the plugin seems useful in its current state -- feedback is welcome
---++ Examples

=%<nop>ATTACHMENT{"foo.jpg" label="%<nop>IMG{"%<nop>THUMBNAIL{"foo.jpg"}%" align="left" }%"}%=

This is equivalent to the previously-required HTML markup

=&lt;a href="%<nop>ATTACHURL%/foo.jpg"&gt;&lt;img src="%<nop>ATTACHURL%/foo_thumbnail_150.jpg" align="left" /&gt;&lt;/a&gt;=

or the slightly better:

=%<nop>ATTACHMENT{ "foo.jpg" label="%<nop>IMG{ "foo_thumb_150.jpg" align="left" width="40" class="none" }%}%=

Of course, neither of the previous methods support multiple sizes as easily, nor are they as well abstracted from the attachment implementation.

The easiest, and recommended use is:

=%<nop>THUMBVIEW{"foo.jpg"}%=

This will display a default sized thumbnail of foo, making it clickable to the full-sized version.

=%<nop>THUMBVIEW{"foo.jpg" caption="foo revealed"}%=

is about as complex as is ordinarily needed.
<verbatim>alias attach='/blah/foswiki/tools/attachutil attach'
alias list='/blah/foswiki/tools/attachutil list'
ln -s /blah/foswiki/tools/attachutil hide
attach TestTopic100 *.jpg *.png
list TestTopic100 '*.png'
./hide TestTopic100 'Secret*.png'
/blah/foswiki/tools/attachutil thumb 100 200 400 TestTopic100 'My*.png'</verbatim>

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write *%<nop>&lt;plugin&gt;_&lt;setting&gt;%*, i.e. *%<nop>NEWPLUGIN_SHORTDESCRIPTION%*

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic: 
      * Set SHORTDESCRIPTION = Maintains thumbnails of attachments
   * THUMBNAILPLUGIN_ENABLE = on, off : enables thumbnail auto-creation on save. Inherits by the usual preference rules.
   * THUMBNAILPLUGIN_SIZE= decimal_number : defines the default size of auto-created thumbnails. You can specify a (space or comma-separated) list, in which case multiple thumbnails (1 of each size) will be generated. The first (or only) size listed is the default variant used by %<nop>THUMBNAIL%.
   * THUMBNAILPLUGIN_FULLPATH = on, off: default fullpath parameter: on will include hostname (protocol and port) in links; off will not. You may want to set this on a global basis for things like GenPDF.

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the Foswiki server.

   * Download the ZIP file from the Plugin Home (see below)
   * Unzip *%TOPIC%.zip* in your Foswiki installation directory. Content:
| *File:* | *Description:* |
| ==data/System/%TOPIC%.txt== | Plugin topic |
| ==data/System/%TOPIC%.txt,v== | Plugin topic repository |
| ==lib/Foswiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
| ==tools/attachutil== | Attachment utility |
   * Configure the Plugin: 
      * Run the [[%SCRIPTURL%/configure%SCRIPTSUFFIX%][configure]] script to enable the Plugin
      * Change the Plugin settings as needed

---++ Plugin Info

| Plugin Author: | Foswiki:Main.TimotheLitt |
| Copyright: | © 2008, 2009, Foswiki:Main.TimotheLitt |
| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]], Perl artistic) |
| Plugin Version: | 29 Jan 2009 (V1.1.1) |
| Change History: | <!-- versions below in reverse order --> |
|  29 Jan 2009 | V1.1.1 - V1.1 ported over to Foswiki again by Kenneth Lavrsen. No feature changes at all from 1.1 |
|  02 Jan 2009 | V1.1 - Add THUMBVIEW, attachutil, handle per-topic preferences as intended |
|  23 Dec 2008 | V1.0.1 - Foswiki version by Kenneth Lavrsen. Bugs fixed so it actually gets enabled. Code tidied. Documentation improved. | 
|  20 Dec 2008 | V1.0 - Initial version |
| Foswiki Dependency: | $Foswiki::Plugins::VERSION 1.1 |
| CPAN Dependencies: | GD:: Image::MetaData::JPEG |
| Other Dependencies: | none |
| Perl Version: | 5.005 |
| Plugin Home: | http://foswiki.org/Extensions/%TOPIC% |
| Feedback: | http://foswiki.org/Extensions/%TOPIC%Dev |

__Related Topics:__ [[%SYSTEMWEB%.Plugins][Plugins]], %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.DefaultPreferences Foswiki:Extensions.AttachmentPlugin Foswiki:Extensions.ImgPlugin
PackageForm edit

ExtensionClassification	Interface and Visualisation
ExtensionType	PluginPackage
Compatibility	Foswiki-1.0.0 (TWiki version available at twiki.org)
DemoUrl
SupportUrl	ThumbnailPlugin
DevelopedInSVN	Yes
ModificationPolicy	CoordinateWithAuthor
Topic attachments
I	Attachment	Action	Size	Date	Who
md5	ThumbnailPlugin.md5	manage	0.2 K	29 Jan 2009 - 02:22	KennethLavrsen
tgz	ThumbnailPlugin.tgz	manage	14.7 K	29 Jan 2009 - 02:22	KennethLavrsen
zip	ThumbnailPlugin.zip	manage	18.5 K	29 Jan 2009 - 02:22	KennethLavrsen
EXT	ThumbnailPlugin_installer	manage	4.3 K	29 Jan 2009 - 02:22	KennethLavrsen
Topic revision: r8 - 09 Dec 2009, CrawfordCurrie
Extensions
Quick Links

Tools

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. see CopyrightStatement.