ikiwiki/doc/plugins/contrib/album.mdwn

141 lines
6.2 KiB
Plaintext
Raw Normal View History

2009-06-16 19:07:58 +02:00
[[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]
[[!tag type/chrome]]
2011-11-14 00:50:06 +01:00
This plugin provides the [[ikiwiki/directive/album]] [[ikiwiki/directive]],
which turns a page into a photo album or image gallery, containing all
images attached to the album or its subpages. It also provides the
[[ikiwiki/directive/albumsection]] and [[ikiwiki/directive/albumimage]]
directives.
2009-06-16 19:07:58 +02:00
2011-11-14 00:50:06 +01:00
This plugin automatically enables the [[filecheck]], [[img]], [[inline]],
[[trail]] and [[transient]] plugins. The [[meta]] plugin is also
recommended.
2011-11-10 00:43:00 +01:00
2011-11-14 00:50:06 +01:00
## Changing the templates
2011-11-14 00:50:06 +01:00
When a viewer page is generated or inlined into an album, the template can
contain these extra variables:
2009-06-16 19:07:58 +02:00
2011-11-14 00:50:06 +01:00
* `<TMPL_VAR ALBUM>` - page name of the album
* `<TMPL_VAR ALBUMURL>` - relative URL to the album
* `<TMPL_VAR ALBUMTITLE>` - title of the album, usually taken from
a [[ikiwiki/directive/meta]] directive
* `<TMPL_VAR CAPTION>` - caption for the image
* `<TMPL_VAR THUMBNAIL>` - a small [[ikiwiki/directive/img]] for the image
* `<TMPL_VAR IMAGEWIDTH>` - width of the full-size image in pixels
* `<TMPL_VAR IMAGEHEIGHT>` - height of the full-size image in pixels
* `<TMPL_VAR IMAGEFILESIZE>` - size of the image, e.g. `1.2 MiB`
* `<TMPL_VAR IMAGEFORMAT>` - format of the image, typically `JPEG`
2009-06-16 19:07:58 +02:00
2011-11-14 00:50:06 +01:00
The template for the viewer page can also contain:
2009-06-16 19:07:58 +02:00
2011-11-14 00:50:06 +01:00
* `<TMPL_VAR IMG>` - a large [[ikiwiki/directive/img]] to display the image
* `<TMPL_VAR PREV>` - a link to the previous viewer, typically with a
thumbnail
* `<TMPL_VAR NEXT>` - a link to the next viewer, typically with a
thumbnail
2011-11-14 00:50:06 +01:00
## Including album entries elsewhere
2011-11-14 00:50:06 +01:00
To display images from elsewhere in the wiki with the same appearance as
an [[ikiwiki/directive/album]] or [[ikiwiki/directive/albumsection]],
you can use an [[ikiwiki/directive/inline]] with the `albumitem`
template:
2011-11-14 00:50:06 +01:00
\[[!inline pages="..." sort="-age" template="albumitem"]]
2011-11-14 00:50:06 +01:00
----
2009-06-16 19:07:58 +02:00
[[!template id=gitbranch branch=smcv/album4 author="[[Simon_McVittie|smcv]]"]]
2009-06-16 19:07:58 +02:00
Available from [[smcv]]'s git repository, in the `album4` branch.
2011-11-14 00:50:06 +01:00
I've called it `album` to distinguish it from
[[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
a better name for this functionality.
2009-06-16 19:07:58 +02:00
2011-11-14 00:50:06 +01:00
(The Summer of Code [[plugins/contrib/gallery]] plugin does the
next/previous UI in Javascript using Lightbox, which means that
individual photos can't be bookmarked in a meaningful way, and
the best it can do as a fallback for non-Javascript browsers
is to provide a direct link to the image.)
Updated, April 2012: rebased onto the version of [[trail]] that got merged
2011-11-14 00:50:06 +01:00
## Manual installation
2012-04-07 00:46:44 +02:00
First, you need a version of ikiwiki with the [[trail]] plugin merged in
(version 3.20120203 or later).
2009-06-16 19:07:58 +02:00
Manual installation requires these files (use the "raw" link in gitweb
to download):
* [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/IkiWiki/Plugin/album.pm)
2011-11-14 00:50:06 +01:00
in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
* [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumviewer.tmpl),
[albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumitem.tmpl),
[albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumnext.tmpl) and
[albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumprev.tmpl),
2011-11-14 00:50:06 +01:00
in your configured `templatedir`, or a `templates` subdirectory of your wiki repository
* the album-related bits from the end of the
[stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/doc/style.css)
2011-11-14 00:50:06 +01:00
(put them in your local.css)
2009-06-16 19:07:58 +02:00
2011-11-14 00:50:06 +01:00
## Demo
2009-07-31 23:18:20 +02:00
2011-11-14 00:50:06 +01:00
* [HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/)
as an entry point to the album
* Each thumbnail links to
[a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/)
with a full size image, optional next/previous thumbnail links, and
optional [[plugins/comments]]
2009-06-16 19:07:58 +02:00
2011-11-14 00:50:06 +01:00
## Bugs
2009-06-16 19:07:58 +02:00
2011-11-14 00:50:06 +01:00
* There's currently a hard-coded list of extensions that are treated as
images: `png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video
types could be added in future.
2011-11-14 00:50:06 +01:00
* Videos aren't currently handled very well; ideally, something like
totem-video-thumbnailer would be used.
* The plugin doesn't do anything special to handle albums that are subpages
of each other. If, say, `debconf` and `debconf/monday` are both albums,
then `debconf/monday/p100.jpg` will currently be assigned to one or the
2011-06-06 00:10:45 +02:00
other, arbitrarily. It should probably pick the closest (longest) album name.
2011-11-14 00:50:06 +01:00
(I'm not sure that it can do this reliably, though, since the scan stage
runs in an undefined order.)
* The plugin doesn't do anything special to handle photos with similar names.
If you have `p100.jpg` and `p100.png`, one will get a viewer page called
2011-11-14 00:50:06 +01:00
`p100` and the other will be ignored. (I'm not sure what we could do better,
though.)
* If there's no `albumimage` in a viewer page, one should probably be appended
automatically.
2009-06-16 19:07:58 +02:00
## TODO
2009-06-16 19:07:58 +02:00
* The generated viewer page should extract as much metadata as possible from
the photo's EXIF tags (creation/modification dates, author, title, caption,
copyright). [[smcv]] has a half-written implementation which runs
2010-05-09 20:13:05 +02:00
`scanimage` hooks, and has an `exiftool` plugin using [[!cpan Image::ExifTool]]
as a reference implementation of that hook.
2009-06-16 19:07:58 +02:00
* There should be an option to reduce the size of photos and write them into
an underlay (perhaps just the transient underlay), for this workflow:
2009-06-16 19:07:58 +02:00
* your laptop's local ikiwiki has two underlays, `photos` and `webphotos`
* `photos` contains full resolution photos with EXIF tags
* for each photo that exists in `photos` but not in `webphotos`, the album
plugin automatically resamples it down to a web-compatible resolution
([[smcv]] uses up to 640x640), optimizes it with `jpegoptim`, strips out
all EXIF tags, and and writes it into the corresponding location
in `webphotos`
* `webphotos` is what you rsync to the web server
* the web server's ikiwiki only has `webphotos` as an underlay
2009-06-16 19:07:58 +02:00
* Eventually, there could be a specialized CGI user interface to batch-edit
all the photos of an album (so for each photo, you get an edit box each for
title, author, copyright etc.) - this would work by making programmatic
edits to all the `albumimage` directives.