document album v3, based on trail v3

[ikiwiki.git] / doc / plugins / contrib / album.mdwn

diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn
index f550ca64cbc54309c7439368950f7af3e2204ec2..836a98f33b9d5225b810bd40360ed2ad392c819a 100644 (file)
--- a/doc/plugins/contrib/album.mdwn
+++ b/doc/plugins/contrib/album.mdwn
@@ -1,101 +1,138 @@
 [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]
 [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]

-[[!template id=gitbranch branch=smcv/album author="[[Simon_McVittie|smcv]]"]]

 [[!tag type/chrome]]
 
 [[!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]].
+## Changing the templates

 
 

-(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.
+When a viewer page is generated or inlined into an album, the template can
+contain these extra variables:

 
 

-The viewer can also have any other content, but typically the
-directive will be the only thing there.
+* `<TMPL_VAR ALBUM>` - page name of the album
+* `<TMPL_VAR ALBUMURL>` - relative URL to the album
+* `<TMPL_VAR ALBUMTITLE>` - title of the album, usually taken from
+  a [[ikiwiki/directive/meta]] directive
+* `<TMPL_VAR CAPTION>` - caption for the image
+* `<TMPL_VAR THUMBNAIL>` - a small [[ikiwiki/directive/img]] for the image
+* `<TMPL_VAR IMAGEWIDTH>` - width of the full-size image in pixels
+* `<TMPL_VAR IMAGEHEIGHT>` - height of the full-size image in pixels
+* `<TMPL_VAR IMAGEFILESIZE>` - size of the image, e.g. `1.2 MiB`
+* `<TMPL_VAR IMAGEFORMAT>` - format of the image, typically `JPEG`

 
 

-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).
+The template for the viewer page can also contain:

 
 

-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.
+* `<TMPL_VAR IMG>` - a large [[ikiwiki/directive/img]] to display the image
+* `<TMPL_VAR PREV>` - a link to the previous viewer, typically with a
+  thumbnail
+* `<TMPL_VAR NEXT>` - a link to the next viewer, typically with a
+  thumbnail

 
 

-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.
+## Including album entries elsewhere

 
 

-## Writing the album
+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:

 
 

-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:
+       \[[!inline pages="..." sort="-age" template="albumitem"]]

 
 

-    \[[!album]]
-    <!-- replaced with one uncategorized photo -->
+----

 
 

-    ## Gamarra
+[[!template id=gitbranch branch=smcv/album3 author="[[Simon_McVittie|smcv]]"]]

 
 

-    \[[!albumsection filter="link(gamarra)"]]
-    <!-- all the Gamarra photos -->
+Available from [[smcv]]'s git repository, in the `album3` 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.

 
 

-    ## Smokescreen
-
-    \[[!albumsection filter="link(smokescreen)"]]
-    <!-- all the Smokescreen photos -->
-
-    ...
-
-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, November 2011: rebased onto [[trail]] v3, CSS adjusted.
+
+## Manual installation
+
+If you don't want to use a branch of ikiwiki, manual installation requires
+these files (use the "raw" link in gitweb to download), in addition to the
+ones needed by [[trail]]:
+
+* [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/IkiWiki/Plugin/album.pm)
+  in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
+* [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumviewer.tmpl),
+  [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumitem.tmpl),
+  [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumnext.tmpl) and
+  [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/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/album3:/doc/style.css)
+  (put them in your local.css)
+
+## Demo
+
+* [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]]
+
+## 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]] 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.