]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/plugins/contrib/album.mdwn
(no commit message)
[git.ikiwiki.info.git] / doc / plugins / contrib / album.mdwn
index 7344a158e99f10abd61f4ad34cfc223eeb2d1389..9fac111647a1ac6b7ef8164c8590ad4a8317dab2 100644 (file)
@@ -11,44 +11,29 @@ This plugin automatically enables the [[filecheck]], [[img]], [[inline]],
 [[trail]] and [[transient]] plugins. The [[meta]] plugin is also
 recommended.
 
 [[trail]] and [[transient]] plugins. The [[meta]] plugin is also
 recommended.
 
-## Changing the templates
-
-When a viewer page is generated or inlined into an album, the template can
-contain these extra variables:
-
-* `<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`
-
-The template for the viewer page can also contain:
+## Demo
 
 
-* `<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
+* [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]]
 
 
-## Including album entries elsewhere
+### Altered Demo
 
 
-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:
+[[!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.
 
 
-       \[[!inline pages="..." sort="-age" template="albumitem"]]
+* [Simple album, rendered using mutiple themes](http://cbaines.net/projects/ikiwiki/album/dest/basic)
+  using the ikiwiki logo.
 
 
-----
+## Installation
 
 
-[[!template id=gitbranch branch=smcv/album4 author="[[Simon_McVittie|smcv]]"]]
+[[!template id=gitbranch branch=smcv/album5 author="[[Simon_McVittie|smcv]]"]]
 
 
-Available from [[smcv]]'s git repository, in the `album4` branch.
+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.
 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.
@@ -59,9 +44,14 @@ 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.)
 
 the best it can do as a fallback for non-Javascript browsers
 is to provide a direct link to the image.)
 
-Updated, April 2012: rebased onto the version of [[trail]] that got merged
+Updated, June 2014: integrated changes from [[KathrynAndersen]],
+Lukas Lipavsky and kjs
 
 
-## Manual installation
+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).
 
 First, you need a version of ikiwiki with the [[trail]] plugin merged in
 (version 3.20120203 or later).
@@ -69,35 +59,51 @@ First, you need a version of ikiwiki with the [[trail]] plugin merged in
 Manual installation requires these files (use the "raw" link in gitweb
 to download):
 
 Manual installation requires these files (use the "raw" link in gitweb
 to download):
 
-* [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/IkiWiki/Plugin/album.pm)
+* [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`
   in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
-* [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumviewer.tmpl),
-  [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumitem.tmpl),
-  [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumnext.tmpl) and
-  [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumprev.tmpl),
+* [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
    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/album4:/doc/style.css)
+  [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album5:/doc/style.css)
   (put them in your local.css)
 
   (put them in your local.css)
 
-## Demo
+## Changing the templates
 
 
-* [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]]
+When a viewer page is generated or inlined into an album, the template can
+contain these extra variables:
 
 
-## Bugs
+* `<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`
+
+The template for the viewer page can also contain:
+
+* `<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
 
 
-* `thumbnailsize` doesn't actually work, they're always 96x96.
-  [[KathrynAndersen]] suggested a fix on the [[discussion]] page;
-  search for her name and look for a context diff.
+## Including album entries elsewhere
 
 
-* The album index is limited to 10 images. kjs suggested a fix on
-  the [[discussion]] page: the plugin should pass `show => 0`
-  to `preprocess_inline`.
+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
 
 * 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
@@ -125,9 +131,9 @@ to download):
 
 * The generated viewer page should extract as much metadata as possible from
   the photo's EXIF tags (creation/modification dates, author, title, caption,
 
 * 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.
+  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:
 
 * 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: