doc/plugins/contrib/album.mdwn

   1 [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]
   2 [[!template id=gitbranch branch=smcv/album author="[[Simon_McVittie|smcv]]"]]
   3 [[!tag type/chrome]]
   4
   5 Available from [[smcv]]'s git repository, in the `album` branch
   6 ([[users/smcv/gallery|users/smcv/gallery]] contains some older
   7 thoughts about this plugin).
   8
   9 This plugin formats a collection of images into a photo album,
  10 in the same way as many websites: good examples include the
  11 PHP application [Gallery](http://gallery.menalto.com/), Flickr,
  12 and Facebook's Photos "application".
  13
  14 I've called it `album` to distinguish it from
  15 [[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
  16 a better name for this functionality.
  17
  18 The web UI I'm trying to achieve consists of one
  19 [HTML page of thumbnails](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/)
  20 as an entry point to the album, where each thumbnail links to
  21 [a "viewer" HTML page](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/img_0068/)
  22 with a full size image, next/previous thumbnail links, and
  23 [[plugins/comments]].
  24
  25 (The Summer of Code [[plugins/contrib/gallery]] plugin does the
  26 next/previous UI in Javascript using Lightbox, which means that
  27 individual photos can't be bookmarked in a meaningful way, and
  28 the best it can do as a fallback for non-Javascript browsers
  29 is to provide a direct link to the image.)
  30
  31 <h2 id="album"><code>album</code> directive</h2>
  32
  33 Each page containing an `album` directive is treated as a photo album.
  34
  35 Every image attached to an album or its subpages is considered to be part of
  36 the album. A "viewer" page, with the wiki's default page extension, will be
  37 generated to display the image, if there isn't already a page of the same
  38 name as the image: for instance, if `debconf` is an album and
  39 `debconf/tuesday/p100.jpg` exists, then `debconf/tuesday/p100.mdwn` might
  40 be created.
  41
  42 There's currently a hard-coded list of extensions that are treated as images:
  43 `png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video types could
  44 be added in future. Videos aren't currently handled very well;
  45 ideally, something like totem-video-thumbnailer would be used.
  46
  47 The `album` directive also produces an [[ikiwiki/directive/inline]] which
  48 automatically includes all the viewers for this album, except those that
  49 will appear in an <a href="#albumsection">albumsection</a> (if every image
  50 is in a section, then the `album` directive won't have any visible effect).
  51
  52 The `inline` is in `archive` and `quick` mode, but can include some
  53 extra information about the images, including file size and a thumbnail made
  54 using [[ikiwiki/directive/img]]). The default template is `albumitem.tmpl`,
  55 which takes advantage of these things.
  56
  57 <h2 id="albumsection"><code>albumsection</code> directive</h2>
  58
  59 The `albumsection` directive is used to split an album into sections. It can
  60 only appear on a page that also has the <a href="#album">album</a> directive.
  61
  62 The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages
  63 are matched. The `albumsection` directive displays all the images that match
  64 the filter, and the `album` directive displays any leftover images, like
  65 this:
  66
  67     # Holiday photos
  68
  69     \[[!album]]
  70     <!-- replaced with a list of any uncategorized photos, which might be
  71          empty -->
  72
  73     ## People
  74
  75     \[[!albumsection filter="tagged(people)"]]
  76     <!-- replaced with a list of photos tagged 'people', including
  77          any that are also tagged 'landscapes' -->
  78
  79     ## Landscapes
  80
  81     \[[!albumsection filter="tagged(landscapes)"]]
  82     <!-- replaced with a list of photos tagged 'landscapes', including
  83          any that are also tagged 'people' -->
  84
  85 <h2 id="albumimage"><code>albumimage</code> directive</h2>
  86
  87 Each viewer page produced by the <a href="#album">album</a> directive
  88 contains an `albumimage` directive, which is replaced by an
  89 [[ikiwiki/directive/img]], wrapped in some formatting using a
  90 template (by default it's `albumviewer.tmpl`). That template can also include
  91 links to the next photo, the previous photo and the album it's in; the default
  92 template has all of these.
  93
  94 The next/previous links are themselves implemented by evaluating a template,
  95 either `albumnext.tmpl` or `albumprev.tmpl` by default.
  96
  97 The directive can also have parameters:
  98
  99 * `title`, `copyright` and `date` are short-cuts for the corresponding
 100   [[ikiwiki/directive/meta]] directives
 101
 102 * `caption` sets a caption which is displayed in the album and viewer
 103   pages
 104
 105 The viewer page can also have other contents before or after the actual
 106 image viewer.
 107
 108 ## Bugs
 109
 110 * The plugin doesn't do anything special to handle albums that are subpages
 111   of each other. If, say, `debconf` and `debconf/monday` are both albums,
 112   then `debconf/monday/p100.jpg` will currently be assigned to one or the
 113   other, arbitrarily.
 114
 115 * The plugin doesn't do anything special to handle photos with similar names.
 116   If you have `p100.jpg` and `p100.png`, one will get a viewer page called
 117   `p100` and the other will be ignored.
 118
 119 * If there's no `albumimage` in a viewer page, one should probably be appended
 120   automatically.
 121
 122 ## TODO
 123
 124 * The documentation should mention how to replicate the appearance of
 125   `album` and `albumsection` using an `inline` of viewer pages.
 126
 127 * The documentation should mention all the template variables and
 128   all the parameters.
 129
 130 * The generated viewer page should include most or all of the possible
 131   parameters to the `albumimage` directive, with empty values, as a
 132   template for editing.
 133
 134 * The generated viewer page should extract as much metadata as possible from
 135   the photo's EXIF tags (creation/modification dates, author, title, caption,
 136   copyright). [[smcv]] has a half-written implementation which runs
 137   `scanimage` hooks, and has an `exiftool` plugin using [[!cpan Image::ExifTool]]
 138   as a reference implementation of that hook.
 139
 140 * There should be an option to reduce the size of photos and write them into
 141   an underlay, for this workflow:
 142
 143   * your laptop's local ikiwiki has two underlays, `photos` and `webphotos`
 144   * `photos` contains full resolution photos with EXIF tags
 145   * for each photo that exists in `photos` but not in `webphotos`, the album
 146     plugin automatically resamples it down to a web-compatible resolution
 147     ([[smcv]] uses up to 640x640), optimizes it with `jpegoptim`, strips out
 148     all EXIF tags, and and writes it into the corresponding location
 149     in `webphotos`
 150   * `webphotos` is what you rsync to the web server
 151   * the web server's ikiwiki only has `webphotos` as an underlay
 152
 153 * Eventually, there could be a specialized CGI user interface to batch-edit
 154   all the photos of an album (so for each photo, you get an edit box each for
 155   title, author, copyright etc.) - this would work by making programmatic
 156   edits to all the `albumimage` directives.