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