doc/plugins/contrib/album.mdwn

   1 [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]
   2 [[!tag type/chrome]]
   3
   4 This plugin provides the [[ikiwiki/directive/album]] [[ikiwiki/directive]],
   5 which turns a page into a photo album or image gallery, containing all
   6 images attached to the album or its subpages. It also provides the
   7 [[ikiwiki/directive/albumsection]] and [[ikiwiki/directive/albumimage]]
   8 directives.
   9
  10 This plugin automatically enables the [[filecheck]], [[img]], [[inline]],
  11 [[trail]] and [[transient]] plugins. The [[meta]] plugin is also
  12 recommended.
  13
  14 ## Demo
  15
  16 * [HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/)
  17   as an entry point to the album
  18 * Each thumbnail links to
  19   [a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/)
  20   with a full size image, optional next/previous thumbnail links, and
  21   optional [[plugins/comments]]
  22
  23 ## Installation
  24
  25 [[!template id=gitbranch branch=smcv/album4 author="[[Simon_McVittie|smcv]]"]]
  26
  27 Available from [[smcv]]'s git repository, in the `album4` branch.
  28 I've called it `album` to distinguish it from
  29 [[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
  30 a better name for this functionality.
  31
  32 (The Summer of Code [[plugins/contrib/gallery]] plugin does the
  33 next/previous UI in Javascript using Lightbox, which means that
  34 individual photos can't be bookmarked in a meaningful way, and
  35 the best it can do as a fallback for non-Javascript browsers
  36 is to provide a direct link to the image.)
  37
  38 Updated, April 2012: rebased onto the version of [[trail]] that got merged
  39
  40 ### Manual installation
  41
  42 First, you need a version of ikiwiki with the [[trail]] plugin merged in
  43 (version 3.20120203 or later).
  44
  45 Manual installation requires these files (use the "raw" link in gitweb
  46 to download):
  47
  48 * [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/IkiWiki/Plugin/album.pm)
  49   in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
  50 * [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumviewer.tmpl),
  51   [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumitem.tmpl),
  52   [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumnext.tmpl) and
  53   [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumprev.tmpl),
  54    in your configured `templatedir`, or a `templates` subdirectory of your wiki repository
  55 * the album-related bits from the end of the
  56   [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/doc/style.css)
  57   (put them in your local.css)
  58
  59 ## Changing the templates
  60
  61 When a viewer page is generated or inlined into an album, the template can
  62 contain these extra variables:
  63
  64 * `<TMPL_VAR ALBUM>` - page name of the album
  65 * `<TMPL_VAR ALBUMURL>` - relative URL to the album
  66 * `<TMPL_VAR ALBUMTITLE>` - title of the album, usually taken from
  67   a [[ikiwiki/directive/meta]] directive
  68 * `<TMPL_VAR CAPTION>` - caption for the image
  69 * `<TMPL_VAR THUMBNAIL>` - a small [[ikiwiki/directive/img]] for the image
  70 * `<TMPL_VAR IMAGEWIDTH>` - width of the full-size image in pixels
  71 * `<TMPL_VAR IMAGEHEIGHT>` - height of the full-size image in pixels
  72 * `<TMPL_VAR IMAGEFILESIZE>` - size of the image, e.g. `1.2 MiB`
  73 * `<TMPL_VAR IMAGEFORMAT>` - format of the image, typically `JPEG`
  74
  75 The template for the viewer page can also contain:
  76
  77 * `<TMPL_VAR IMG>` - a large [[ikiwiki/directive/img]] to display the image
  78 * `<TMPL_VAR PREV>` - a link to the previous viewer, typically with a
  79   thumbnail
  80 * `<TMPL_VAR NEXT>` - a link to the next viewer, typically with a
  81   thumbnail
  82
  83 ## Including album entries elsewhere
  84
  85 To display images from elsewhere in the wiki with the same appearance as
  86 an [[ikiwiki/directive/album]] or [[ikiwiki/directive/albumsection]],
  87 you can use an [[ikiwiki/directive/inline]] with the `albumitem`
  88 template:
  89
  90         \[[!inline pages="..." sort="-age" template="albumitem"]]
  91
  92 ## Bugs
  93
  94 * `thumbnailsize` doesn't actually work, they're always 96x96.
  95   [[KathrynAndersen]] suggested a fix on the [[discussion]] page;
  96   search for her name and look for a context diff.
  97
  98 * The album index is limited to 10 images. kjs suggested a fix on
  99   the [[discussion]] page: the plugin should pass `show => 0`
 100   to `preprocess_inline`.
 101
 102 * There's currently a hard-coded list of extensions that are treated as
 103   images: `png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video
 104   types could be added in future.
 105
 106 * Videos aren't currently handled very well; ideally, something like
 107   totem-video-thumbnailer would be used.
 108
 109 * The plugin doesn't do anything special to handle albums that are subpages
 110   of each other. If, say, `debconf` and `debconf/monday` are both albums,
 111   then `debconf/monday/p100.jpg` will currently be assigned to one or the
 112   other, arbitrarily. It should probably pick the closest (longest) album name.
 113   (I'm not sure that it can do this reliably, though, since the scan stage
 114   runs in an undefined order.)
 115
 116 * The plugin doesn't do anything special to handle photos with similar names.
 117   If you have `p100.jpg` and `p100.png`, one will get a viewer page called
 118   `p100` and the other will be ignored. (I'm not sure what we could do better,
 119   though.)
 120
 121 * If there's no `albumimage` in a viewer page, one should probably be appended
 122   automatically.
 123
 124 ## TODO
 125
 126 * The generated viewer page should extract as much metadata as possible from
 127   the photo's EXIF tags (creation/modification dates, author, title, caption,
 128   copyright). [[smcv]] has a half-written implementation which runs
 129   `scanimage` hooks, and has an `exiftool` plugin using [[!cpan Image::ExifTool]]
 130   as a reference implementation of that hook.
 131
 132 * There should be an option to reduce the size of photos and write them into
 133   an underlay (perhaps just the transient underlay), for this workflow:
 134
 135   * your laptop's local ikiwiki has two underlays, `photos` and `webphotos`
 136   * `photos` contains full resolution photos with EXIF tags
 137   * for each photo that exists in `photos` but not in `webphotos`, the album
 138     plugin automatically resamples it down to a web-compatible resolution
 139     ([[smcv]] uses up to 640x640), optimizes it with `jpegoptim`, strips out
 140     all EXIF tags, and and writes it into the corresponding location
 141     in `webphotos`
 142   * `webphotos` is what you rsync to the web server
 143   * the web server's ikiwiki only has `webphotos` as an underlay
 144
 145 * Eventually, there could be a specialized CGI user interface to batch-edit
 146   all the photos of an album (so for each photo, you get an edit box each for
 147   title, author, copyright etc.) - this would work by making programmatic
 148   edits to all the `albumimage` directives.