X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/9def21fcf7a837ae9289c63c362657eb9b1c4892..6b4351acbaf91b5420e9e5aba985b3f1378bb966:/doc/plugins/contrib/trail.mdwn diff --git a/doc/plugins/contrib/trail.mdwn b/doc/plugins/contrib/trail.mdwn index 337e5d427..5adff4c78 100644 --- a/doc/plugins/contrib/trail.mdwn +++ b/doc/plugins/contrib/trail.mdwn @@ -1,66 +1,116 @@ -[[!tag type/chrome patch]] +[[!tag 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. +plugin aims to solve [[todo/wikitrails]] in a simpler way; it can also be +used for [[navigation through blog posts|todo/Pagination_next_prev_links]]. -Joey: what do you think of this plugin? If you like the general approach -and are likely to include it in ikiwiki, I'll try to modify -[[plugins/contrib/album]] to be based on it, rather than partially -reinventing it. +The branch also includes [[todo/test_coverage]] machinery. -Bugs: +Demo: -* \[[!inline pages="..." trail=yes]] currently tries to work out - what pages are in the trail, and their order, at scan time. That - won't work, because matching a pagespec at scan time is - unreliable - pages we want might not have been scanned yet! I - haven't worked out a solution for this. I think - \[[!inline pagenames="..." trail=yes]] would be safe, though. +* [a trail based on links](http://demo.hosted.pseudorandom.co.uk/trail/) +* [a hybrid trail/inline](http://demo.hosted.pseudorandom.co.uk/trail2/) + +The page `e` in the demo is in both trails, to demonstrate how that looks. + +The `smcv/trail2` branch is an older version of `trail` which used typed links +as its data structure, resulting in timing-related limitations (it couldn't +select pages for the trail by using pagespecs, because pagespecs can't be +evaluated correctly until the scan stage has finished). + +Updated, November 2011: + +* reinstated `inline` integration ([[report]] integration would probably be + pretty easy too, if this gets merged) + +* switched from typed links back to a custom data structure to avoid + chicken/egg problems with ordering + +* create typed links too, as a side-effect, but not when using an inline + +* regression test with nearly full coverage + +* CSS for the default anti-theme and all built-in themes (it looks nicest + in the default anti-theme and in actiontabs - the demo uses actiontabs) + +Known bugs: + +* the blueview and goldtype CSS nearly work, but the alignment is a bit off ---- [[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]] +[[!tag type/chrome]] + +This plugin provides the [[ikiwiki/directive/trail]], +[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]], +and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]]. -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. +It's sometimes useful to have "trails" of pages in a wiki where each +page links to the next and/or previous page. For instance, you could use +this for a guided tour, sequence of chapters, or sequence of blog posts. + +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, or by +including groups of pages with a [[ikiwiki/directive]]. 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. +the next and previous members. HTML `` tags with the `prev`, +`next` and `up` relations are also generated. + +Pages can be included in a trail in various ways: + +* The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]], + and at the same time adds the matching pages (from `pages` or `pagenames`) + to the trail. One use is to navigate through all posts in a blog: + + \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes + feedshow=10 quick=yes]] + + This directive only works if the [[!iki plugins/inline desc=inline]] + plugin is also enabled. + +* The [[ikiwiki/directive/trail]] directive has optional `pages` and + `pagenames` options which behave the same as in [[inline]], but don't + produce any output in the page, so you can have trails that don't list + all their pages. -The `traillink` [[ikiwiki/directive]] is used to record which pages -are in a trail, and simultaneously link to them. Alternatively, the -[[ikiwiki/directive/inline]] directive can be used with `trail=yes` -to record the inlined pages as part of the trail, in the order in -which they are inlined. +* The [[ikiwiki/directive/traillink]] directive makes a visible link + and also adds the linked page to the trail. This will typically be + used in a bullet list, but could also be in paragraph text: -## Directives + * [[!traillink Introduction]] + * [[!traillink "Chapter 1"]] + * [[!traillink Chapter_2]] + * [[!traillink Appendix_A]] -(These will go to the appropriate pages in [[ikiwiki/directive]] if this -plugin is included in ikiwiki.) + or -### traillink + To use this software you must \[[!traillink install]] it, + \[[!traillink configuration text="configure it"]], + and finally \[[!traillink running|run_it]]. -The `traillink` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]] -plugin. This directive appears on the page representing a trail. It acts -as a visible [[ikiwiki/WikiLink]], but also records the linked page as -a member of the trail. + This also counts as a [[ikiwiki/WikiLink]] for things like the `link()` + [[ikiwiki/PageSpec]] item. -Various syntaxes can be used: +* The [[ikiwiki/directive/trailitem]] directive adds a page to the trail + like `traillink`, but produces an invisible link, rather like `\[[!tag]]`: - \[[!traillink Badgers]] - \[[!traillink How_to_find_mushrooms_using_badgers|badgers]] - \[[!traillink badgers text="How to find mushrooms using badgers"]] + To use this software you must \[[!traillink install]] it, + \[[!trailitem installing_from_packages]] + \[[!trailitem installing_from_source]] + \[[!traillink configuration text="configure it"]], + and finally \[[!traillink running|run_it]]. + \[[!trailitem troubleshooting]] -### trailoptions + Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though + there's no visible link. -The `trailoptions` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]] -plugin. This directive appears on the page representing a trail, and -produces no output. +You can mix several of these directives in one page, and the resulting +trail will contain all of the pages matched by any of the directives, +in the same order as the directives (unless you use the `sort` option +on `\[[!trail]]` or `\[[!trailinline]]`, which takes precedence). -Currently, the only option supported is `[[!trailoptions circular=yes]]`, -which adds links between the first and last pages, turning the trail into -a circle. +The [[ikiwiki/directive/trail]] directive can also be used to set options.