[[!tag type/chrome patch]]
[[!template id=gitbranch branch=smcv/trail author="[[smcv]]"]]

Available from [[smcv]]'s git repository, in the `trail` branch. This
plugin aims to solve [[todo/wikitrails]] in a simpler way.

Updated, June 2011:

* removed `inline` integration for now

* added `<link>` tags

* switched from a custom data structure to using typed links

----

[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]

It's sometimes useful to have "trails" of pages in a wiki, as a guided
tour, sequence of chapters etc. In this plugin, a trail is represented
by a page, and the pages in the trail are indicated by specially marked
links within that page.

If using the default `page.tmpl`, each page automatically displays the
trails that it's a member of (if any), with links to the trail and to
the next and previous members. HTML `<link>` tags with the `prev`,
`next` and `up` relations are also generated.

The `traillink` [[ikiwiki/directive]] is used to record which pages
are in a trail, and simultaneously link to them. Alternatively, the
[[ikiwiki/directive/trailitem]] directive can be used to make an
invisible `traillink`.

## Directives

(These will go to the appropriate pages in [[ikiwiki/directive]] if this
plugin is included in ikiwiki.)

### trailitem

The `trailitem` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
plugin. It is used like this:

    \[[!trailitem some_other_page]]

to add `some_other_page` to the trail represented by this page, without
generating a visible hyperlink.

### traillink

The `traillink` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the linked page to
the trail represented by the page containing the directive.

In its simplest form, the first parameter is like the content of a WikiLink:

    \[[!traillink some_other_page]]

The displayed text can also be overridden, either with a `|` symbol or with
a `text` parameter:

    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
    \[[!traillink some_other_page text="Click here to start the trail"]]

### trailoptions

The `trailoptions` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
plugin. It sets options for the trail represented by this page. Example usage:

    \[[!trailoptions sort="meta(title)" circular="no"]]

The available options are:

* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
  items of the trail are ordered according to the first link to each item
  found on the trail page

* `circular`: if set to `yes` or `1`, the trail is made into a loop by
  making the last page's "next" link point to the first page, and the first
  page's "previous" link point to the last page

----

## Future directions

The current version of this plugin doesn't implement inline-based or
otherwise [[ikiwiki/PageSpec]]-based trails. This is difficult because
there's a circular dependency:

* adding typed links should happen *before* scanning has finished, to
  guarantee that they're available before the first page is rendered

* evaluating pagespecs should only happen *after* scanning has finished,
  to guarantee that everything you might want to base a pagespec on
  (`meta`, etc.) has been gathered by scanning