doc/plugins/contrib/trail.mdwn

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