doc/plugins/contrib/album.mdwn

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