X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/612505d76bb338b243b9cac1f8b1a4291dd7c3e1..HEAD:/doc/plugins/contrib/album.mdwn diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn index 395c99bce..9fac11164 100644 --- a/doc/plugins/contrib/album.mdwn +++ b/doc/plugins/contrib/album.mdwn @@ -1,108 +1,154 @@ [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]] -[[!template id=gitbranch branch=smcv/album author="[[Simon_McVittie|smcv]]"]] [[!tag type/chrome]] -Available from [[smcv]]'s git repository, in the `album` branch -([[users/smcv/gallery|users/smcv/gallery]] contains some older -thoughts about this plugin). +This plugin provides the [[ikiwiki/directive/album]] [[ikiwiki/directive]], +which turns a page into a photo album or image gallery, containing all +images attached to the album or its subpages. It also provides the +[[ikiwiki/directive/albumsection]] and [[ikiwiki/directive/albumimage]] +directives. -This plugin formats a collection of images into a photo album, -in the same way as many websites: good examples include the -PHP application [Gallery](http://gallery.menalto.com/), Flickr, -and Facebook's Photos "application". I've called it `album` -to distinguish it from [[contrib/gallery|plugins/contrib/gallery]], -although `gallery` might well be a better name for this functionality. +This plugin automatically enables the [[filecheck]], [[img]], [[inline]], +[[trail]] and [[transient]] plugins. The [[meta]] plugin is also +recommended. -The web UI I'm trying to achieve consists of one -[HTML page of thumbnails](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/) -as an entry point to the album, where each thumbnail links to -[a "viewer" HTML page](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/img_0068/) -with a full size image, next/previous thumbnail links, and -[[plugins/comments]]. +## Demo -(The Summer of Code [[plugins/contrib/gallery]] plugin does the -next/previous UI in Javascript using Lightbox, which means that -individual photos can't be bookmarked in a meaningful way, and -the best it can do as a fallback for non-Javascript browsers -is to provide a direct link to the image.) - -## Writing the viewers - - \[[!albumimage image=foo.jpg album=myalbum - title=... - caption=... - copyright=... - size=... - viewertemplate=... - ]] - -Each viewer contains one `\[[!albumimage]]` directive. This -sets the `image` filename, the `album` in which this image appears, -and an optional `caption`, and can override the `size` at which to -display the image and the `viewertemplate` to use to display the -image. - -It can also have `title`, `copyright` and `date` parameters, which -are short-cuts for [[ikiwiki/directive/meta]] directives. - -The viewer can also have any other content, but typically the -directive will be the only thing there. - -Eventually, there will be a specialized CGI user interface to -edit all the photos of an album at once, upload a new photo -(which will attach the photo but also write out a viewer page -for it), or mark an already-uploaded photo as a member of an -album (which is done by writing out a viewer page for it). +* [HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/) + as an entry point to the album +* Each thumbnail links to + [a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/) + with a full size image, optional next/previous thumbnail links, and + optional [[plugins/comments]] -The `\[[!albumimage]]` directive is replaced by an -[[ikiwiki/directive/img]], wrapped in some formatting using a -template (by default `albumviewer.tmpl`). The template can (and -should) also include "next photo", "previous photo" and -"up to gallery" links. +### Altered Demo -The next/previous links are themselves implemented by -[[inlining|ikiwiki/directive/inline]] the next or previous -photo, using a special template (by default `albumnext.tmpl` -or `albumprev.tmpl`), in `archive`/`quick` mode. +[[!template id=gitbranch branch=cbaines/album]] +This uses the album plugin, with some altered css, and with the css applied to +all of the themes. -> With hindsight, using an inline here is wrong - I should just -> run hooks and fill in the template within the album plugin. -> inline has some specialized functionality that's overkill -> here, and its delayed HTML substitution breaks the ability -> to have previous/up/next links both above and below the -> photo, for instance. --[[smcv]] +* [Simple album, rendered using mutiple themes](http://cbaines.net/projects/ikiwiki/album/dest/basic) + using the ikiwiki logo. -## Writing the album +## Installation -The album contains one `\[[!album]]` directive. It may also -contain any number of `\[[!albumsection]]` directives, for -example the demo album linked above could look like: +[[!template id=gitbranch branch=smcv/album5 author="[[Simon_McVittie|smcv]]"]] - \[[!album]] - +Available from [[smcv]]'s git repository, in the `album5` branch. +I've called it `album` to distinguish it from +[[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be +a better name for this functionality. - ## Gamarra - - \[[!albumsection filter="link(gamarra)"]] - - - ## Smokescreen - - \[[!albumsection filter="link(smokescreen)"]] - - - ... - -The `\[[!album]]` directive is replaced by an -[[ikiwiki/directive/inline]] which automatically includes every -page that has an `\[[!albumimage]]` directive linking it to this -album, except those that will appear in an `\[[!albumsection]]`. - -The `inline` is in `archive`/`quick` mode, but includes some -extra information about the images, including file size and a -thumbnail (again, made using [[ikiwiki/directive/img]]). The -default template is `albumitem.tmpl`, which takes advantage -of these things. +(The Summer of Code [[plugins/contrib/gallery]] plugin does the +next/previous UI in Javascript using Lightbox, which means that +individual photos can't be bookmarked in a meaningful way, and +the best it can do as a fallback for non-Javascript browsers +is to provide a direct link to the image.) -Each `\[[!albumsection]]` is replaced by a similar inline, which -selects a subset of the photos in the album. +Updated, June 2014: integrated changes from [[KathrynAndersen]], +Lukas Lipavsky and kjs + +An `album6` branch is also available, but is less suitable +for manual installation since it needs core IkiWiki changes +(until [[bugs/trails depend on everything]] is fixed). + +### Manual installation + +First, you need a version of ikiwiki with the [[trail]] plugin merged in +(version 3.20120203 or later). + +Manual installation requires these files (use the "raw" link in gitweb +to download): + +* [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/IkiWiki/Plugin/album.pm) + in an `IkiWiki/Plugin` subdirectory of your configured `plugindir` +* [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/templates/albumviewer.tmpl), + [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/templates/albumitem.tmpl), + [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/templates/albumnext.tmpl) and + [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/templates/albumprev.tmpl), + in your configured `templatedir`, or a `templates` subdirectory of your wiki repository +* the album-related bits from the end of the + [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/doc/style.css) + (put them in your local.css) + +## Changing the templates + +When a viewer page is generated or inlined into an album, the template can +contain these extra variables: + +* `` - page name of the album +* `` - relative URL to the album +* `` - title of the album, usually taken from + a [[ikiwiki/directive/meta]] directive +* `` - caption for the image +* `` - a small [[ikiwiki/directive/img]] for the image +* `` - width of the full-size image in pixels +* `` - height of the full-size image in pixels +* `` - size of the image, e.g. `1.2 MiB` +* `` - format of the image, typically `JPEG` + +The template for the viewer page can also contain: + +* `` - a large [[ikiwiki/directive/img]] to display the image +* `` - a link to the previous viewer, typically with a + thumbnail +* `` - a link to the next viewer, typically with a + thumbnail + +## Including album entries elsewhere + +To display images from elsewhere in the wiki with the same appearance as +an [[ikiwiki/directive/album]] or [[ikiwiki/directive/albumsection]], +you can use an [[ikiwiki/directive/inline]] with the `albumitem` +template: + + \[[!inline pages="..." sort="-age" template="albumitem"]] + +## Bugs + +* There's currently a hard-coded list of extensions that are treated as + images: `png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video + types could be added in future. + +* Videos aren't currently handled very well; ideally, something like + totem-video-thumbnailer would be used. + +* The plugin doesn't do anything special to handle albums that are subpages + of each other. If, say, `debconf` and `debconf/monday` are both albums, + then `debconf/monday/p100.jpg` will currently be assigned to one or the + other, arbitrarily. It should probably pick the closest (longest) album name. + (I'm not sure that it can do this reliably, though, since the scan stage + runs in an undefined order.) + +* The plugin doesn't do anything special to handle photos with similar names. + If you have `p100.jpg` and `p100.png`, one will get a viewer page called + `p100` and the other will be ignored. (I'm not sure what we could do better, + though.) + +* If there's no `albumimage` in a viewer page, one should probably be appended + automatically. + +## TODO + +* The generated viewer page should extract as much metadata as possible from + the photo's EXIF tags (creation/modification dates, author, title, caption, + copyright). [[smcv]] once had a half-written implementation which runs + `scanimage` hooks, and an `exiftool` plugin using [[!cpan Image::ExifTool]] + as a reference implementation of that hook, but has lost that code somewhere :-( + +* There should be an option to reduce the size of photos and write them into + an underlay (perhaps just the transient underlay), for this workflow: + + * your laptop's local ikiwiki has two underlays, `photos` and `webphotos` + * `photos` contains full resolution photos with EXIF tags + * for each photo that exists in `photos` but not in `webphotos`, the album + plugin automatically resamples it down to a web-compatible resolution + ([[smcv]] uses up to 640x640), optimizes it with `jpegoptim`, strips out + all EXIF tags, and and writes it into the corresponding location + in `webphotos` + * `webphotos` is what you rsync to the web server + * the web server's ikiwiki only has `webphotos` as an underlay + +* Eventually, there could be a specialized CGI user interface to batch-edit + all the photos of an album (so for each photo, you get an edit box each for + title, author, copyright etc.) - this would work by making programmatic + edits to all the `albumimage` directives.