summaryrefslogtreecommitdiff
path: root/doc/plugins/contrib/album.mdwn
blob: daf16fd3c34176f71b6ca846af9434632418f8a7 (plain)

[[!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 formats a collection of images into a photo album, in the same way as many websites: good examples include the PHP application Gallery, 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.

The web UI I'm trying to achieve consists of one HTML page of thumbnails as an entry point to the album, where each thumbnail links to a "viewer" HTML page with a full size image, next/previous thumbnail links, and [[plugins/comments]].

(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 page containing an album directive is treated as a photo album.

Every image attached to an album or its subpages is considered to be part of the album. A "viewer" page, with the wiki's default page extension, will be generated in the [[transient underlay|todo/transient_pages]] to display the image, if there isn't already a page of the same name as the image: for instance, if debconf is an album and debconf/tuesday/p100.jpg exists, then debconf/tuesday/p100.mdwn might be created.

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 album directive also produces an [[ikiwiki/directive/inline]] which automatically includes all the viewers for this album, except those that will appear in an albumsection (if every image is in a section, then the album directive won't have any visible effect).

The inline is in archive and quick mode, but can include some extra information about the images, including file size and a thumbnail made using [[ikiwiki/directive/img]]). The default template is albumitem.tmpl, which takes advantage of these things.

The albumsection directive is used to split an album into sections. It can only appear on a page that also has the album directive.

The filter parameter is a [[ikiwiki/PageSpec]] against which viewer pages are matched. The albumsection directive displays all the images that match the filter, and the album directive displays any leftover images, like this:

# Holiday photos

\[[!album]]
<!-- replaced with a list of any uncategorized photos, which might be
     empty -->

## People

\[[!albumsection filter="tagged(people)"]]
<!-- replaced with a list of photos tagged 'people', including
     any that are also tagged 'landscapes' -->

## Landscapes

\[[!albumsection filter="tagged(landscapes)"]]
<!-- replaced with a list of photos tagged 'landscapes', including
     any that are also tagged 'people' -->

Each viewer page produced by the album directive contains an albumimage directive, which is replaced by an [[ikiwiki/directive/img]], wrapped in some formatting using a template (by default it's albumviewer.tmpl). That template can also include links to the next photo, the previous photo and the album it's in; the default template has all of these.

The next/previous links are themselves implemented by evaluating a template, either albumnext.tmpl or albumprev.tmpl by default.

The directive can also have parameters:

  • title, copyright and date are short-cuts for the corresponding [[ikiwiki/directive/meta]] directives

  • caption sets a caption which is displayed in the album and viewer pages

The viewer page can also have other contents before or after the actual image viewer.

Bugs

  • 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.

  • 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.

  • If there's no albumimage in a viewer page, one should probably be appended automatically.

TODO

  • The documentation should mention how to replicate the appearance of album and albumsection using an inline of viewer pages.

  • The documentation should mention all the template variables and all the parameters.

  • The generated viewer page should include most or all of the possible parameters to the albumimage directive, with empty values, as a template for editing.

  • 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]] has a half-written implementation which runs scanimage hooks, and has an exiftool plugin using [[!cpan Image::ExifTool]] as a reference implementation of that hook.

  • 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.