doc/plugins/contrib/trail.mdwn

   1 [[!tag 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; it can also be
   6 used for [[navigation through blog posts|todo/Pagination_next_prev_links]].
   7
   8 The branch also includes machinery to run most of the IkiWiki regression
   9 tests under [[!cpan Devel::Cover]].
  10
  11 Demo:
  12
  13 * [a trail based on links](http://demo.hosted.pseudorandom.co.uk/trail/)
  14 * [a hybrid trail/inline](http://demo.hosted.pseudorandom.co.uk/trail2/)
  15
  16 The page `e` in the demo is in both trails, to demonstrate how that looks.
  17
  18 The `smcv/trail2` branch is an older version of `trail` which used typed links
  19 as its data structure, resulting in timing-related limitations (it couldn't
  20 select pages for the trail by using pagespecs, because pagespecs can't be
  21 evaluated correctly until the scan stage has finished).
  22
  23 Updated, November 2011:
  24
  25 * reinstated `inline` integration ([[report]] integration would probably be
  26   pretty easy too, if this gets merged)
  27
  28 * switched from typed links back to a custom data structure to avoid
  29   chicken/egg problems with ordering
  30
  31 * create typed links too, as a side-effect, but not when using an inline
  32
  33 * regression test with nearly full coverage
  34
  35 * CSS for the default anti-theme and all built-in themes (it looks nicest
  36   in the default anti-theme and in actiontabs - the demo uses actiontabs)
  37
  38 Known bugs:
  39
  40 * the blueview and goldtype CSS nearly work, but the alignment is a bit off
  41
  42 ----
  43
  44 [[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
  45 [[!tag type/chrome]]
  46
  47 This plugin provides the [[ikiwiki/directive/trail]],
  48 [[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
  49 and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]].
  50
  51 It's sometimes useful to have "trails" of pages in a wiki where each
  52 page links to the next and/or previous page. For instance, you could use
  53 this for a guided tour, sequence of chapters, or sequence of blog posts.
  54
  55 In this plugin, a trail is represented by a page, and the pages in the
  56 trail are indicated by specially marked links within that page, or by
  57 including groups of pages with a [[ikiwiki/directive]].
  58
  59 If using the default `page.tmpl`, each page automatically displays the
  60 trails that it's a member of (if any), with links to the trail and to
  61 the next and previous members. HTML `<link>` tags with the `prev`,
  62 `next` and `up` relations are also generated.
  63
  64 Pages can be included in a trail in various ways:
  65
  66 * The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]],
  67   and at the same time adds the matching pages (from `pages` or `pagenames`)
  68   to the trail. One use is to navigate through all posts in a blog:
  69
  70         \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
  71           feedshow=10 quick=yes]]
  72
  73   This directive only works if the [[!iki plugins/inline desc=inline]]
  74   plugin is also enabled.
  75
  76 * The [[ikiwiki/directive/trail]] directive has optional `pages` and
  77   `pagenames` options which behave the same as in [[inline]], but don't
  78   produce any output in the page, so you can have trails that don't list
  79   all their pages.
  80
  81 * The [[ikiwiki/directive/traillink]] directive makes a visible link
  82   and also adds the linked page to the trail. This will typically be
  83   used in a bullet list, but could also be in paragraph text:
  84
  85         * [[!traillink Introduction]]
  86         * [[!traillink "Chapter 1"]]
  87         * [[!traillink Chapter_2]]
  88         * [[!traillink Appendix_A]]
  89
  90   or
  91
  92         To use this software you must \[[!traillink install]] it,
  93         \[[!traillink configuration text="configure it"]],
  94         and finally \[[!traillink running|run_it]].
  95
  96   This also counts as a [[ikiwiki/WikiLink]] for things like the `link()`
  97   [[ikiwiki/PageSpec]] item.
  98
  99 * The [[ikiwiki/directive/trailitem]] directive adds a page to the trail
 100   like `traillink`, but produces an invisible link, rather like `\[[!tag]]`:
 101
 102         To use this software you must \[[!traillink install]] it,
 103         \[[!trailitem installing_from_packages]]
 104         \[[!trailitem installing_from_source]]
 105         \[[!traillink configuration text="configure it"]],
 106         and finally \[[!traillink running|run_it]].
 107         \[[!trailitem troubleshooting]]
 108
 109   Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
 110   there's no visible link.
 111
 112 You can mix several of these directives in one page, and the resulting
 113 trail will contain all of the pages matched by any of the directives,
 114 in the same order as the directives (unless you use the `sort` option
 115 on `\[[!trail]]` or `\[[!trailinline]]`, which takes precedence).
 116
 117 The [[ikiwiki/directive/trail]] directive can also be used to set options.