clear sandbox/test commit
[ikiwiki.git] / doc / plugins / contrib / album.mdwn
blobdaf16fd3c34176f71b6ca846af9434632418f8a7
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]]
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).
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".
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.
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]].
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.)
31 <h2 id="album"><code>album</code> directive</h2>
33 Each page containing an `album` directive is treated as a photo album.
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 in the [[transient underlay|todo/transient_pages]] to display the
38 image, if there isn't already a page of the same name as the image: for
39 instance, if `debconf` is an album and `debconf/tuesday/p100.jpg` exists,
40 then `debconf/tuesday/p100.mdwn` might be created.
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.
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).
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.
57 <h2 id="albumsection"><code>albumsection</code> directive</h2>
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.
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:
67     # Holiday photos
69     \[[!album]]
70     <!-- replaced with a list of any uncategorized photos, which might be
71          empty -->
73     ## People
75     \[[!albumsection filter="tagged(people)"]]
76     <!-- replaced with a list of photos tagged 'people', including
77          any that are also tagged 'landscapes' -->
79     ## Landscapes
81     \[[!albumsection filter="tagged(landscapes)"]]
82     <!-- replaced with a list of photos tagged 'landscapes', including
83          any that are also tagged 'people' -->
85 <h2 id="albumimage"><code>albumimage</code> directive</h2>
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.
94 The next/previous links are themselves implemented by evaluating a template,
95 either `albumnext.tmpl` or `albumprev.tmpl` by default.
97 The directive can also have parameters:
99 * `title`, `copyright` and `date` are short-cuts for the corresponding
100   [[ikiwiki/directive/meta]] directives
102 * `caption` sets a caption which is displayed in the album and viewer
103   pages
105 The viewer page can also have other contents before or after the actual
106 image viewer.
108 ## Bugs
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.
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.
119 * If there's no `albumimage` in a viewer page, one should probably be appended
120   automatically.
122 ## TODO
124 * The documentation should mention how to replicate the appearance of
125   `album` and `albumsection` using an `inline` of viewer pages.
127 * The documentation should mention all the template variables and
128   all the parameters.
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.
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.
140 * There should be an option to reduce the size of photos and write them into
141   an underlay (perhaps just the transient underlay), for this workflow:
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
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.