Merge commit 'remotes/smcv/ready/among'
[ikiwiki.git] / 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 ## Writing the album
69
70 The album contains one `\[[!album]]` directive. It may also
71 contain any number of `\[[!albumsection]]` directives, for
72 example the demo album linked above could look like:
73
74     \[[!album]]
75     <!-- replaced with one uncategorized photo -->
76
77     ## Gamarra
78
79     \[[!albumsection filter="link(gamarra)"]]
80     <!-- all the Gamarra photos -->
81
82     ## Smokescreen
83
84     \[[!albumsection filter="link(smokescreen)"]]
85     <!-- all the Smokescreen photos -->
86
87     ...
88
89 The `\[[!album]]` directive is replaced by an
90 [[ikiwiki/directive/inline]] which automatically includes every
91 page that has an `\[[!albumimage]]` directive linking it to this
92 album, except those that will appear in an `\[[!albumsection]]`.
93
94 The `inline` is in `archive`/`quick` mode, but includes some
95 extra information about the images, including file size and a
96 thumbnail (again, made using [[ikiwiki/directive/img]]). The
97 default template is `albumitem.tmpl`, which takes advantage
98 of these things.
99
100 Each `\[[!albumsection]]` is replaced by a similar inline, which
101 selects a subset of the photos in the album.