doc/plugins/contrib/trail.mdwn

   1 [[!tag type/chrome patch]]
   2 [[!template id=gitbranch branch=smcv/trail author="[[smcv]]"]]
   3
   4 Available from [[smcv]]'s git repository, in the `trail` branch. This
   5 plugin aims to solve [[todo/wikitrails]] in a simpler way.
   6
   7 Updated, June 2011:
   8
   9 * removed `inline` integration for now
  10
  11 * added `<link>` tags
  12
  13 * switched from a custom data structure to using typed links
  14
  15 ----
  16
  17 [[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
  18
  19 It's sometimes useful to have "trails" of pages in a wiki, as a guided
  20 tour, sequence of chapters etc. In this plugin, a trail is represented
  21 by a page, and the pages in the trail are indicated by specially marked
  22 links within that page.
  23
  24 If using the default `page.tmpl`, each page automatically displays the
  25 trails that it's a member of (if any), with links to the trail and to
  26 the next and previous members. HTML `<link>` tags with the `prev`,
  27 `next` and `up` relations are also generated.
  28
  29 The `traillink` [[ikiwiki/directive]] is used to record which pages
  30 are in a trail, and simultaneously link to them. Alternatively, the
  31 [[ikiwiki/directive/trailitem]] directive can be used to make an
  32 invisible `traillink`.
  33
  34 ## Directives
  35
  36 (These will go to the appropriate pages in [[ikiwiki/directive]] if this
  37 plugin is included in ikiwiki.)
  38
  39 ### trailitem
  40
  41 The `trailitem` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
  42 plugin. It is used like this:
  43
  44     \[[!trailitem some_other_page]]
  45
  46 to add `some_other_page` to the trail represented by this page, without
  47 generating a visible hyperlink.
  48
  49 ### traillink
  50
  51 The `traillink` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
  52 plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the linked page to
  53 the trail represented by the page containing the directive.
  54
  55 In its simplest form, the first parameter is like the content of a WikiLink:
  56
  57     \[[!traillink some_other_page]]
  58
  59 The displayed text can also be overridden, either with a `|` symbol or with
  60 a `text` parameter:
  61
  62     \[[!traillink Click_here_to_start_the_trail|some_other_page]]
  63     \[[!traillink some_other_page text="Click here to start the trail"]]
  64
  65 ### trailoptions
  66
  67 The `trailoptions` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
  68 plugin. It sets options for the trail represented by this page. Example usage:
  69
  70     \[[!trailoptions sort="meta(title)" circular="no"]]
  71
  72 The available options are:
  73
  74 * `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
  75   items of the trail are ordered according to the first link to each item
  76   found on the trail page
  77
  78 * `circular`: if set to `yes` or `1`, the trail is made into a loop by
  79   making the last page's "next" link point to the first page, and the first
  80   page's "previous" link point to the last page
  81
  82 ----
  83
  84 ## Future directions
  85
  86 The current version of this plugin doesn't implement inline-based or
  87 otherwise [[ikiwiki/PageSpec]]-based trails. This is difficult because
  88 there's a circular dependency:
  89
  90 * adding typed links should happen *before* scanning has finished, to
  91   guarantee that they're available before the first page is rendered
  92
  93 * evaluating pagespecs should only happen *after* scanning has finished,
  94   to guarantee that everything you might want to base a pagespec on
  95   (`meta`, etc.) has been gathered by scanning