]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blob - doc/plugins/contrib/album.mdwn
67fb2c915f0193982adf3f68ea64a6d055e3fbd5
[git.ikiwiki.info.git] / doc / plugins / contrib / album.mdwn
1 [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]
2 [[!tag type/chrome]]
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]]
8 directives.
10 This plugin automatically enables the [[filecheck]], [[img]], [[inline]],
11 [[trail]] and [[transient]] plugins. The [[meta]] plugin is also
12 recommended.
14 ## Changing the templates
16 When a viewer page is generated or inlined into an album, the template can
17 contain these extra variables:
19 * `<TMPL_VAR ALBUM>` - page name of the album
20 * `<TMPL_VAR ALBUMURL>` - relative URL to the album
21 * `<TMPL_VAR ALBUMTITLE>` - title of the album, usually taken from
22   a [[ikiwiki/directive/meta]] directive
23 * `<TMPL_VAR CAPTION>` - caption for the image
24 * `<TMPL_VAR THUMBNAIL>` - a small [[ikiwiki/directive/img]] for the image
25 * `<TMPL_VAR IMAGEWIDTH>` - width of the full-size image in pixels
26 * `<TMPL_VAR IMAGEHEIGHT>` - height of the full-size image in pixels
27 * `<TMPL_VAR IMAGEFILESIZE>` - size of the image, e.g. `1.2 MiB`
28 * `<TMPL_VAR IMAGEFORMAT>` - format of the image, typically `JPEG`
30 The template for the viewer page can also contain:
32 * `<TMPL_VAR IMG>` - a large [[ikiwiki/directive/img]] to display the image
33 * `<TMPL_VAR PREV>` - a link to the previous viewer, typically with a
34   thumbnail
35 * `<TMPL_VAR NEXT>` - a link to the next viewer, typically with a
36   thumbnail
38 ## Including album entries elsewhere
40 To display images from elsewhere in the wiki with the same appearance as
41 an [[ikiwiki/directive/album]] or [[ikiwiki/directive/albumsection]],
42 you can use an [[ikiwiki/directive/inline]] with the `albumitem`
43 template:
45         \[[!inline pages="..." sort="-age" template="albumitem"]]
47 ----
49 [[!template id=gitbranch branch=smcv/album4 author="[[Simon_McVittie|smcv]]"]]
51 Available from [[smcv]]'s git repository, in the `album4` branch.
52 I've called it `album` to distinguish it from
53 [[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
54 a better name for this functionality.
56 (The Summer of Code [[plugins/contrib/gallery]] plugin does the
57 next/previous UI in Javascript using Lightbox, which means that
58 individual photos can't be bookmarked in a meaningful way, and
59 the best it can do as a fallback for non-Javascript browsers
60 is to provide a direct link to the image.)
62 Updated, April 2012: rebased onto the version of [[trail]] that got merged
64 ## Manual installation
66 First, you need a version of ikiwiki with the [[trail]] plugin merged in.
68 Manual installation requires these files (use the "raw" link in gitweb
69 to download):
71 * [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/IkiWiki/Plugin/album.pm)
72   in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
73 * [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumviewer.tmpl),
74   [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumitem.tmpl),
75   [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumnext.tmpl) and
76   [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumprev.tmpl),
77    in your configured `templatedir`, or a `templates` subdirectory of your wiki repository
78 * the album-related bits from the end of the
79   [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/doc/style.css)
80   (put them in your local.css)
82 ## Demo
84 * [HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/)
85   as an entry point to the album
86 * Each thumbnail links to
87   [a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/)
88   with a full size image, optional next/previous thumbnail links, and
89   optional [[plugins/comments]]
91 ## Bugs
93 * There's currently a hard-coded list of extensions that are treated as
94   images: `png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video
95   types could be added in future.
97 * Videos aren't currently handled very well; ideally, something like
98   totem-video-thumbnailer would be used.
100 * The plugin doesn't do anything special to handle albums that are subpages
101   of each other. If, say, `debconf` and `debconf/monday` are both albums,
102   then `debconf/monday/p100.jpg` will currently be assigned to one or the
103   other, arbitrarily. It should probably pick the closest (longest) album name.
104   (I'm not sure that it can do this reliably, though, since the scan stage
105   runs in an undefined order.)
107 * The plugin doesn't do anything special to handle photos with similar names.
108   If you have `p100.jpg` and `p100.png`, one will get a viewer page called
109   `p100` and the other will be ignored. (I'm not sure what we could do better,
110   though.)
112 * If there's no `albumimage` in a viewer page, one should probably be appended
113   automatically.
115 ## TODO
117 * The generated viewer page should extract as much metadata as possible from
118   the photo's EXIF tags (creation/modification dates, author, title, caption,
119   copyright). [[smcv]] has a half-written implementation which runs
120   `scanimage` hooks, and has an `exiftool` plugin using [[!cpan Image::ExifTool]]
121   as a reference implementation of that hook.
123 * There should be an option to reduce the size of photos and write them into
124   an underlay (perhaps just the transient underlay), for this workflow:
126   * your laptop's local ikiwiki has two underlays, `photos` and `webphotos`
127   * `photos` contains full resolution photos with EXIF tags
128   * for each photo that exists in `photos` but not in `webphotos`, the album
129     plugin automatically resamples it down to a web-compatible resolution
130     ([[smcv]] uses up to 640x640), optimizes it with `jpegoptim`, strips out
131     all EXIF tags, and and writes it into the corresponding location
132     in `webphotos`
133   * `webphotos` is what you rsync to the web server
134   * the web server's ikiwiki only has `webphotos` as an underlay
136 * Eventually, there could be a specialized CGI user interface to batch-edit
137   all the photos of an album (so for each photo, you get an edit box each for
138   title, author, copyright etc.) - this would work by making programmatic
139   edits to all the `albumimage` directives.