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