1 [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]
4 This plugin provides the [[ikiwiki/directive/album]] [[ikiwiki/directive]],
5 which turns a page into a photo album or image gallery, containing all
6 images attached to the album or its subpages. It also provides the
7 [[ikiwiki/directive/albumsection]] and [[ikiwiki/directive/albumimage]]
10 This plugin automatically enables the [[filecheck]], [[img]], [[inline]],
11 [[trail]] and [[transient]] plugins. The [[meta]] plugin is also
16 * [HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/)
17 as an entry point to the album
18 * Each thumbnail links to
19 [a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/)
20 with a full size image, optional next/previous thumbnail links, and
21 optional [[plugins/comments]]
25 [[!template id=gitbranch branch=cbaines/album]]
26 This uses the album plugin, with some altered css, and with the css applied to
29 * [Simple album, rendered using mutiple themes](http://cbaines.net/projects/ikiwiki/album/dest/basic)
30 using the ikiwiki logo.
34 [[!template id=gitbranch branch=smcv/album5 author="[[Simon_McVittie|smcv]]"]]
36 Available from [[smcv]]'s git repository, in the `album5` branch.
37 I've called it `album` to distinguish it from
38 [[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
39 a better name for this functionality.
41 (The Summer of Code [[plugins/contrib/gallery]] plugin does the
42 next/previous UI in Javascript using Lightbox, which means that
43 individual photos can't be bookmarked in a meaningful way, and
44 the best it can do as a fallback for non-Javascript browsers
45 is to provide a direct link to the image.)
47 Updated, June 2014: integrated changes from [[KathrynAndersen]],
48 Lukas Lipavsky and kjs
50 ### Manual installation
52 First, you need a version of ikiwiki with the [[trail]] plugin merged in
53 (version 3.20120203 or later).
55 Manual installation requires these files (use the "raw" link in gitweb
58 * [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/IkiWiki/Plugin/album.pm)
59 in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
60 * [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/templates/albumviewer.tmpl),
61 [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/templates/albumitem.tmpl),
62 [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/templates/albumnext.tmpl) and
63 [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/templates/albumprev.tmpl),
64 in your configured `templatedir`, or a `templates` subdirectory of your wiki repository
65 * the album-related bits from the end of the
66 [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/doc/style.css)
67 (put them in your local.css)
69 ## Changing the templates
71 When a viewer page is generated or inlined into an album, the template can
72 contain these extra variables:
74 * `<TMPL_VAR ALBUM>` - page name of the album
75 * `<TMPL_VAR ALBUMURL>` - relative URL to the album
76 * `<TMPL_VAR ALBUMTITLE>` - title of the album, usually taken from
77 a [[ikiwiki/directive/meta]] directive
78 * `<TMPL_VAR CAPTION>` - caption for the image
79 * `<TMPL_VAR THUMBNAIL>` - a small [[ikiwiki/directive/img]] for the image
80 * `<TMPL_VAR IMAGEWIDTH>` - width of the full-size image in pixels
81 * `<TMPL_VAR IMAGEHEIGHT>` - height of the full-size image in pixels
82 * `<TMPL_VAR IMAGEFILESIZE>` - size of the image, e.g. `1.2 MiB`
83 * `<TMPL_VAR IMAGEFORMAT>` - format of the image, typically `JPEG`
85 The template for the viewer page can also contain:
87 * `<TMPL_VAR IMG>` - a large [[ikiwiki/directive/img]] to display the image
88 * `<TMPL_VAR PREV>` - a link to the previous viewer, typically with a
90 * `<TMPL_VAR NEXT>` - a link to the next viewer, typically with a
93 ## Including album entries elsewhere
95 To display images from elsewhere in the wiki with the same appearance as
96 an [[ikiwiki/directive/album]] or [[ikiwiki/directive/albumsection]],
97 you can use an [[ikiwiki/directive/inline]] with the `albumitem`
100 \[[!inline pages="..." sort="-age" template="albumitem"]]
104 * There's currently a hard-coded list of extensions that are treated as
105 images: `png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video
106 types could be added in future.
108 * Videos aren't currently handled very well; ideally, something like
109 totem-video-thumbnailer would be used.
111 * The plugin doesn't do anything special to handle albums that are subpages
112 of each other. If, say, `debconf` and `debconf/monday` are both albums,
113 then `debconf/monday/p100.jpg` will currently be assigned to one or the
114 other, arbitrarily. It should probably pick the closest (longest) album name.
115 (I'm not sure that it can do this reliably, though, since the scan stage
116 runs in an undefined order.)
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. (I'm not sure what we could do better,
123 * If there's no `albumimage` in a viewer page, one should probably be appended
128 * The generated viewer page should extract as much metadata as possible from
129 the photo's EXIF tags (creation/modification dates, author, title, caption,
130 copyright). [[smcv]] once had a half-written implementation which runs
131 `scanimage` hooks, and an `exiftool` plugin using [[!cpan Image::ExifTool]]
132 as a reference implementation of that hook, but has lost that code somewhere :-(
134 * There should be an option to reduce the size of photos and write them into
135 an underlay (perhaps just the transient underlay), for this workflow:
137 * your laptop's local ikiwiki has two underlays, `photos` and `webphotos`
138 * `photos` contains full resolution photos with EXIF tags
139 * for each photo that exists in `photos` but not in `webphotos`, the album
140 plugin automatically resamples it down to a web-compatible resolution
141 ([[smcv]] uses up to 640x640), optimizes it with `jpegoptim`, strips out
142 all EXIF tags, and and writes it into the corresponding location
144 * `webphotos` is what you rsync to the web server
145 * the web server's ikiwiki only has `webphotos` as an underlay
147 * Eventually, there could be a specialized CGI user interface to batch-edit
148 all the photos of an album (so for each photo, you get an edit box each for
149 title, author, copyright etc.) - this would work by making programmatic
150 edits to all the `albumimage` directives.