diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/plugins/contrib/album.mdwn | 181 | ||||
| -rw-r--r-- | doc/plugins/contrib/ikiwiki/directive/album.mdwn | 56 | ||||
| -rw-r--r-- | doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn | 26 | ||||
| -rw-r--r-- | doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn | 29 |
4 files changed, 187 insertions, 105 deletions
diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn index dde533e76..836a98f33 100644 --- a/doc/plugins/contrib/album.mdwn +++ b/doc/plugins/contrib/album.mdwn @@ -1,147 +1,118 @@ [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]] -[[!template id=gitbranch branch=smcv/album2 author="[[Simon_McVittie|smcv]]"]] [[!tag type/chrome]] -Available from [[smcv]]'s git repository, in the `album2` branch. -Older (pre-rebase) versions in `album`, `album-live` (the latter -was used on an actual website and didn't explode too much). +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. -[The version currently available hasn't been modified to work with the -November 2011 version of [[trail]]. -[[smcv]]] +This plugin automatically enables the [[filecheck]], [[img]], [[inline]], +[[trail]] and [[transient]] plugins. The [[meta]] plugin is also +recommended. -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". +## Changing the templates -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. +When a viewer page is generated or inlined into an album, the template can +contain these extra variables: -The web UI I'm trying to achieve consists of one -[HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/) -as an entry point to the album, where each thumbnail links to -[a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/) -with a full size image, next/previous thumbnail links, and -[[plugins/comments]]. +* `<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 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.) +The template for the viewer page can also contain: -<h2 id="album"><code>album</code> directive</h2> +* `<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 -Each page containing an `album` directive is treated as a photo album. +## Including album entries elsewhere -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. +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: -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. + \[[!inline pages="..." sort="-age" template="albumitem"]] -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 <a href="#albumsection">albumsection</a> (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. +[[!template id=gitbranch branch=smcv/album3 author="[[Simon_McVittie|smcv]]"]] -<h2 id="albumsection"><code>albumsection</code> directive</h2> - -The `albumsection` directive is used to split an album into sections. It can -only appear on a page that also has the <a href="#album">album</a> 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' --> +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. - ## Landscapes +(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.) - \[[!albumsection filter="tagged(landscapes)"]] - <!-- replaced with a list of photos tagged 'landscapes', including - any that are also tagged 'people' --> +Updated, November 2011: rebased onto [[trail]] v3, CSS adjusted. -<h2 id="albumimage"><code>albumimage</code> directive</h2> +## Manual installation -Each viewer page produced by the <a href="#album">album</a> 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. +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]]: -The next/previous links are themselves implemented by evaluating a template, -either `albumnext.tmpl` or `albumprev.tmpl` by default. +* [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) -The directive can also have parameters: +## Demo -* `title`, `copyright` and `date` are short-cuts for the corresponding - [[ikiwiki/directive/meta]] directives +* [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]] -* `caption` sets a caption which is displayed in the album and viewer - pages +## Bugs -The viewer page can also have other contents before or after the actual -image viewer. +* 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. -## Bugs +* 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. + `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. -* When editing a viewer page, rebuilding it seems to fail at the moment. - Probably related to: - -* Integration with [[plugins/contrib/trail]] is new, untested and not - very well implemented. In particular, the prev/up/next links are - redundant with the ones from `trail`. - ## TODO -* The documentation should mention how to replicate the appearance of - `album` and `albumsection` using an `inline` of viewer pages, - elsewhere on the site. - -* 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 diff --git a/doc/plugins/contrib/ikiwiki/directive/album.mdwn b/doc/plugins/contrib/ikiwiki/directive/album.mdwn new file mode 100644 index 000000000..433eec8bd --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/album.mdwn @@ -0,0 +1,56 @@ +The `album` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +Each page containing an `album` directive is treated as a photo album +or image gallery. Example usage is as simple as: + + \[[!album]] + +Every image attached to an album or its [[subpages|ikiwiki/subpage]] 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|plugins/transient]] 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. + +The album is treated as a [[!iki plugins/contrib/trail desc=trail]], which +gives each viewer page a link back to the album, and a link to the previous +and next viewer in the album. + +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 in the album is in a +section, then the `album` directive is still required, but won't produce +any output in the page. + +The `inline` 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. + +## Options + +The directive can have some options for the entire album. The defaults are: + + \[[!album + sort="-age" + size="full" + thumbnailsize="96x96" + viewertemplate="albumviewer" + prevtemplate="albumprev" + nexttemplate="albumnext" + +* `sort` - sets the order in which images appear, defaulting to earliest + creation date first +* `size` - if not `full`, the [[ikiwiki/directive/img]] in the viewer page + will be resized to be no larger than this +* `thumbnailsize` - the [[ikiwiki/directive/img]] in the album page, + which can also be used in the previous/next links, will be no larger than + this +* `viewertemplate` - the template used for the [[albumimage]] in each + viewer page +* `prevtemplate` - the template used to replace `<TMPL_VAR PREV>` if used in + the viewer page +* `nexttemplate` - the template used to replace `<TMPL_VAR NEXT>` if used in + the viewer page + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn b/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn new file mode 100644 index 000000000..2385bb535 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn @@ -0,0 +1,26 @@ +The `albumimage` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +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 and previous photos, in addition to those provided by the +[[!iki plugins/contrib/trail desc=trail]] plugin. + +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`, `date`, `updated`, `author`, `authorurl`, `copyright`, `license` + and `description` are short-cuts for the corresponding + [[ikiwiki/directive/meta]] directives + +* `caption` sets a caption which is displayed near this image in the album + and viewer pages + +The viewer page can also contain any text and markup before or after the +`albumimage` directive, which will appear before or after the image in the +viewer page. + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn b/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn new file mode 100644 index 000000000..7e5749e05 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn @@ -0,0 +1,29 @@ +The `albumsection` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +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; it will be + empty if they're all tagged as 'people' and/or 'landscapes' --> + + ## 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' --> + +[[!meta robots="noindex, follow"]] |