doc/plugins/contrib/album.mdwn

   1 [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]
   2 [[!tag type/chrome]]
   3
   4 Available from [[smcv]]'s git repository, in the `album` branch
   5 ([[users/smcv/gallery|users/smcv/gallery]] contains some older
   6 thoughts about this plugin).
   7
   8 This plugin formats a collection of images into a photo album,
   9 in the same way as many websites: good examples include the
  10 PHP application [Gallery](http://gallery.menalto.com/), Flickr,
  11 and Facebook's Photos "application". I've called it `album`
  12 to distinguish it from [[contrib/gallery|plugins/contrib/gallery]],
  13 although `gallery` might well be a better name for this functionality.
  14
  15 The web UI I'm trying to achieve consists of one
  16 [HTML page of thumbnails](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/)
  17 as an entry point to the album, where each thumbnail links to
  18 [a "viewer" HTML page](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/img_0068/)
  19 with a full size image, next/previous thumbnail links, and
  20 [[plugins/comments]].
  21
  22 (The Summer of Code [[plugins/contrib/gallery]] plugin does the
  23 next/previous UI in Javascript using Lightbox, which means that
  24 individual photos can't be bookmarked in a meaningful way, and
  25 the best it can do as a fallback for non-Javascript browsers
  26 is to provide a direct link to the image.)
  27
  28 ## Writing the viewers
  29
  30     \[[!albumimage image=foo.jpg album=myalbum
  31         title=...
  32         caption=...
  33         copyright=...
  34         size=...
  35         viewertemplate=...
  36     ]]
  37
  38 Each viewer contains one `\[[!albumimage]]` directive. This
  39 sets the `image` filename, the `album` in which this image appears,
  40 and an optional `caption`, and can override the `size` at which to
  41 display the image and the `viewertemplate` to use to display the
  42 image.
  43
  44 It can also have `title`, `copyright` and `date` parameters, which
  45 are short-cuts for [[ikiwiki/directive/meta]] directives.
  46
  47 The viewer can also have any other content, but typically the
  48 directive will be the only thing there.
  49
  50 Eventually, there will be a specialized CGI user interface to
  51 edit all the photos of an album at once, upload a new photo
  52 (which will attach the photo but also write out a viewer page
  53 for it), or mark an already-uploaded photo as a member of an
  54 album (which is done by writing out a viewer page for it).
  55
  56 The `\[[!albumimage]]` directive is replaced by an
  57 [[ikiwiki/directive/img]], wrapped in some formatting using a
  58 template (by default `albumviewer.tmpl`). The template can (and
  59 should) also include "next photo", "previous photo" and
  60 "up to gallery" links.
  61
  62 The next/previous links are themselves implemented by
  63 [[inlining|ikiwiki/directive/inline]] the next or previous
  64 photo, using a special template (by default `albumnext.tmpl`
  65 or `albumprev.tmpl`), in `archive`/`quick` mode.
  66
  67 ## Writing the album
  68
  69 The album contains one `\[[!album]]` directive. It may also
  70 contain any number of `\[[!albumsection]]` directives, for
  71 example the demo album linked above could look like:
  72
  73     \[[!album]]
  74     <!-- replaced with one uncategorized photo -->
  75
  76     ## Gamarra
  77
  78     \[[!albumsection filter="link(gamarra)"]]
  79     <!-- all the Gamarra photos -->
  80
  81     ## Smokescreen
  82
  83     \[[!albumsection filter="link(smokescreen)"]]
  84     <!-- all the Smokescreen photos -->
  85
  86     ...
  87
  88 The `\[[!album]]` directive is replaced by an
  89 [[ikiwiki/directive/inline]] which automatically includes every
  90 page that has an `\[[!albumimage]]` directive linking it to this
  91 album, except those that will appear in an `\[[!albumsection]]`.
  92
  93 The `inline` is in `archive`/`quick` mode, but includes some
  94 extra information about the images, including file size and a
  95 thumbnail (again, made using [[ikiwiki/directive/img]]). The
  96 default template is `albumitem.tmpl`, which takes advantage
  97 of these things.
  98
  99 Each `\[[!albumsection]]` is replaced by a similar inline, which
 100 selects a subset of the photos in the album.