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