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.
+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](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/)
the best it can do as a fallback for non-Javascript browsers
is to provide a direct link to the image.)
-## Writing the viewers
+<h2 id="album"><code>album</code> directive</h2>
+
+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 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 <a href="#albumsection">albumsection</a> (if every image
+is in a section, then the `album` directive won't have any visible effect).
- \[[!albumimage image=foo.jpg album=myalbum
- title=...
- caption=...
- copyright=...
- size=...
- viewertemplate=...
- ]]
+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.
-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.
+<h2 id="albumsection"><code>albumsection</code> directive</h2>
-It can also have `title`, `copyright` and `date` parameters, which
-are short-cuts for [[ikiwiki/directive/meta]] directives.
+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 -->
-The viewer can also have any other content, but typically the
-directive will be the only thing there.
+ ## People
-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).
+ \[[!albumsection filter="tagged(people)"]]
+ <!-- replaced with a list of photos tagged 'people', including
+ any that are also tagged 'landscapes' -->
-The `\[[!albumimage]]` directive is replaced by an
+ ## Landscapes
+
+ \[[!albumsection filter="tagged(landscapes)"]]
+ <!-- replaced with a list of photos tagged 'landscapes', including
+ any that are also tagged 'people' -->
+
+<h2 id="albumimage"><code>albumimage</code> directive</h2>
+
+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 `albumviewer.tmpl`). The template can (and
-should) also include "next photo", "previous photo" and
-"up to gallery" links.
+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
-[[inlining|ikiwiki/directive/inline]] the next or previous
-photo, using a special template (by default `albumnext.tmpl`
-or `albumprev.tmpl`), in `archive`/`quick` mode.
+The next/previous links are themselves implemented by evaluating a template,
+either `albumnext.tmpl` or `albumprev.tmpl` by default.
-> 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]]
+The directive can also have parameters:
-## Writing the album
+* `title`, `copyright` and `date` are short-cuts for the corresponding
+ [[ikiwiki/directive/meta]] directives
-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:
+* `caption` sets a caption which is displayed in the album and viewer
+ pages
- \[[!album]]
- <!-- replaced with one uncategorized photo -->
+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.
- ## Gamarra
+## TODO
- \[[!albumsection filter="link(gamarra)"]]
- <!-- all the Gamarra photos -->
+* The documentation should mention how to replicate the appearance of
+ `album` and `albumsection` using an `inline` of viewer pages.
- ## Smokescreen
+* The documentation should mention all the template variables and
+ all the parameters.
- \[[!albumsection filter="link(smokescreen)"]]
- <!-- all the Smokescreen photos -->
+* 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.
-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]]`.
+* There should be an option to reduce the size of photos and write them into
+ an underlay, for this workflow:
-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.
+ * 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
-Each `\[[!albumsection]]` is replaced by a similar inline, which
-selects a subset of the photos in the album.
+* 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.
>
> --[[smcv]]
+>> In the current version of the branch, the viewer pages are
+>> generated automatically if you didn't generate them yourself,
+>> so `ikiwiki-album` is no longer needed. --[[smcv]]
+
i'm new to ikiwiki, apologies if this is dealt with elsewhere. -brush
> This plugin is pretty ambitious, and is unfinished, so I'd recommend
>> an image with a strange extension to a differing target filename
>> with the normal extension, respectively). -s
+>>> Now that we have `add_autofile` I can just create viewer pages
+>>> whenever there's an image to view. The current version of the
+>>> branch does that. -s
+
* With each viewer page having next/prev links, I can see how you
were having the scalability issues with ikiwiki's data structures
earlier! -J
>> (Unless you use img to make the thumbnails for those links, then it
>> would rebuild the thumbnails anyway. Have not looked at the code.) --[[Joey]]
+>>> I do use img. -s
+
* And doesn't each viewer page really depend on every other page in the
same albumsection? If a new page is added, the next/prev links
may need to be updated, for example. If so, there will be much
> one album: if they're subpages of 2+ nested albums then they're only
> considered to be in the deepest-nested one (i.e. longest URL), and if
> they're not in any album then that's a usage error. This would
-> also make prev/next links sane.
->
+> also make prev/next links sane. -s
+
+>> The current version constrains images to be in at most one album,
+>> choosing one arbitrarily (dependent on scan order) if albums are
+>> nested. -s
+
> If you want to reference images from elsewhere in the wiki and display
> them as if in an album, then you can use an ordinary inline with
> the same template that the album would use, and I'll make sure the
-> templates are set up so this works.
->
+> templates are set up so this works. -s
+
+>> Still needs documenting, I've put it on the TODO list on the main
+>> page. -s
+
> (Implementation detail: this means that an image X/Y/Z/W/V, where X and
> Y are albums, Z does not exist and W exists but is not an album,
> would have a content dependency on Y, a presence dependency on Z
> subpages of the album, although that would mean breaking some URLs
> on the existing website I'm doing all this work for... -s
+>> The current version of the branch doesn't have this restriction;
+>> perhaps it's a worthwhile simplification, or perhaps it's too
+>> restrictive? I fairly often use directory hierarchies like
+>> `a_festival/saturday/foo.jpg` within an album, which makes
+>> it very easy to write `albumsection` filters. -s
+
* Putting a few of the above thoughts together, my ideal album system
seems to be one where I can just drop the images into a directory and
have them appear in the album index, as well as each generate their own wiki
>> upload-and-rename.
>> -s
+>>> I believe the current branch meets your requirements, by having
+>>> first-class wiki pages spring into existence using `add_autofile`
+>>> to be viewer pages for photos. -s
+
> In a way, what you really want for metadata is to have it in the album
> page, so you can batch-edit the whole lot by editing one file (this
> does mean that editing the album necessarily causes each of its viewers
>> (That's apparently good enough for Bugzilla, but not really
>> for ikiwiki). -s
+>>> This is now in the main page's TODO list; if/when I implement this,
+>>> I intend to make it a specialized CGI interface. -s
+
>> Yes, [all metadata in one file] would make some sense.. It also allows putting one image in
>> two albums, with different caption etc. (Maybe for different audiences.)
>> --[[Joey]]
----
-Trying to use the "special extension" design:
+'''I think the "special extension" design is a dead-end, but here's what
+happened when I tried to work out how it would work. --[[smcv]]'''
Suppose that each viewer is a JPEG-or-GIF-or-something, with extension
".albumimage". We have a gallery "memes" with three images, badger,
projects / ikiwiki.git / commitdiff