diff options
| -rw-r--r-- | IkiWiki.pm | 3 | ||||
| -rw-r--r-- | IkiWiki/Plugin/parentlinks.pm | 55 | ||||
| -rw-r--r-- | IkiWiki/Render.pm | 18 | ||||
| -rw-r--r-- | doc/plugins/parentlinks.mdwn | 124 | ||||
| -rwxr-xr-x | t/parentlinks.t | 82 | ||||
| -rw-r--r-- | t/parentlinks/templates/parentlinks.tmpl | 4 |
6 files changed, 267 insertions, 19 deletions
diff --git a/IkiWiki.pm b/IkiWiki.pm index 80e317110..6a1823c5a 100644 --- a/IkiWiki.pm +++ b/IkiWiki.pm @@ -77,7 +77,8 @@ sub defaultconfig () { #{{{ adminuser => undef, adminemail => undef, plugin => [qw{mdwn link inline htmlscrubber passwordauth openid - signinedit lockedit conditional recentchanges}], + signinedit lockedit conditional recentchanges + parentlinks}], libdir => undef, timeformat => '%c', locale => undef, diff --git a/IkiWiki/Plugin/parentlinks.pm b/IkiWiki/Plugin/parentlinks.pm new file mode 100644 index 000000000..a94cd469c --- /dev/null +++ b/IkiWiki/Plugin/parentlinks.pm @@ -0,0 +1,55 @@ +#!/usr/bin/perl +# -*- cperl-indent-level: 8; -*- +# Ikiwiki parentlinks plugin. +package IkiWiki::Plugin::parentlinks; + +use warnings; +use strict; +use IkiWiki 2.00; + +sub import { #{{{ + hook(type => "pagetemplate", id => "parentlinks", call => \&pagetemplate); +} # }}} + +sub parentlinks ($) { #{{{ + my $page=shift; + + my @ret; + my $path=""; + my $title=$config{wikiname}; + my $i=0; + my $depth=0; + my $height=0; + + my @pagepath=(split("/", $page)); + my $pagedepth=@pagepath; + foreach my $dir (@pagepath) { + next if $dir eq 'index'; + $depth=$i; + $height=($pagedepth - $depth); + push @ret, { + url => urlto($path, $page), + page => $title, + depth => $depth, + height => $height, + "depth_$depth" => 1, + "height_$height" => 1, + }; + $path.="/".$dir; + $title=IkiWiki::pagetitle($dir); + $i++; + } + return @ret; +} #}}} + +sub pagetemplate (@) { #{{{ + my %params=@_; + my $page=$params{page}; + my $template=$params{template}; + + if ($template->query(name => "parentlinks")) { + $template->param(parentlinks => [parentlinks($page)]); + } +} # }}} + +1 diff --git a/IkiWiki/Render.pm b/IkiWiki/Render.pm index 990fcaaa1..8a79119cd 100644 --- a/IkiWiki/Render.pm +++ b/IkiWiki/Render.pm @@ -47,23 +47,6 @@ sub backlinks ($) { #{{{ return @links; } #}}} -sub parentlinks ($) { #{{{ - my $page=shift; - - my @ret; - my $pagelink=""; - my $path=""; - my $title=$config{wikiname}; - - foreach my $dir (split("/", $page)) { - next if $dir eq 'index'; - push @ret, { url => urlto($path, $page), page => $title }; - $path.="/".$dir; - $title=pagetitle($dir); - } - return @ret; -} #}}} - sub genpage ($$) { #{{{ my $page=shift; my $content=shift; @@ -121,7 +104,6 @@ sub genpage ($$) { #{{{ ? $config{wikiname} : pagetitle(basename($page)), wikiname => $config{wikiname}, - parentlinks => [parentlinks($page)], content => $content, backlinks => $backlinks, more_backlinks => $more_backlinks, diff --git a/doc/plugins/parentlinks.mdwn b/doc/plugins/parentlinks.mdwn new file mode 100644 index 000000000..ff4139390 --- /dev/null +++ b/doc/plugins/parentlinks.mdwn @@ -0,0 +1,124 @@ +[[!template id=plugin name=parentlinks core=1 author="[[intrigeri]]"]] +[[!tag type/link]] + +This plugin offers a `HTML::Template` loop that iterates over all or +a subset of a page's parents. It also provides a few bonus +possibilities, such as styling the parent links depending on their +place in the path. + +[[!toc ]] + +Content +======= + +This plugin provides one template loop, called `PARENTLINKS`, that +returns the list of parent pages for the current page. Every returned +path element has the following variables set: + +* `URL` (string): url to the current path element +* `PAGE` (string): title of the current path element +* `DEPTH` (positive integer): depth of the path leading to the + current path element, counting from the wiki's root, which has + `DEPTH=0` +* `HEIGHT` (positive integer): distance, expressed in path elements, + from the current page to the current path element; e.g. this is + 1 for the current page's mother, 2 for its grand-mother, etc. +* `DEPTH_n` (boolean): true if, and only if, `DEPTH==n` +* `HEIGHT_n` (boolean): true if, and only if, `HEIGHT==n` + +Usage +===== + +The `DEPTH_n` and `HEIGHT_n` variables allow the template writer to +skip arbitrary elements in the parents list: they are arbitrary +page-range selectors. + +The `DEPTH` and `HEIGHT` variables allow the template writer to apply +general treatment, depending on one of these variables, to *every* +parent: they are counters. + +Basic usage +----------- + +As in the default `page.tmpl`, one can simply display the list of +parent pages: + + <TMPL_LOOP NAME="PARENTLINKS"> + <a href="<TMPL_VAR NAME=URL>"><TMPL_VAR NAME=PAGE></a>/ + </TMPL_LOOP> + <TMPL_VAR TITLE> + + +Styling parents depending on their depth +---------------------------------------- + +Say you want the parent links to be styled depending on their depth in +the path going from the wiki root to the current page; just add the +following lines in `page.tmpl`: + + <TMPL_LOOP NAME="PARENTLINKS"> + <a href="<TMPL_VAR NAME="URL">" class="depth<TMPL_VAR NAME="DEPTH">"> + <TMPL_VAR NAME="PAGE"> + </a> / + </TMPL_LOOP> + +Then write the appropriate CSS bits for `a.depth1`, etc. + +Skip some parents, style the others depending on their distance to the current page +----------------------------------------------------------------------------------- + +Say you want to display all the parents links but the wiki homepage, +styled depending on their distance to the current page; just add the +following lines in `page.tmpl`: + + <TMPL_LOOP NAME="PARENTLINKS"> + <TMPL_IF NAME="DEPTH_0"> + <TMPL_ELSE> + <a href="<TMPL_VAR NAME="URL">" class="height<TMPL_VAR NAME="HEIGHT">"> + <TMPL_VAR NAME="PAGE"> + </a> / + </TMPL_LOOP> + +Then write the appropriate CSS bits for `a.height1`, etc. + +Full-blown example +------------------ + +Let's have a look at a more complicated example; combining the boolean +loop variables provided by this plugin (`IS_ROOT` and friends) and +`HTML::Template` flow control structures, you can have custom HTML +and/or CSS generated for some special path components; e.g.: + + <!-- all parents, skipping mother and grand'ma, inside a common div+ul --> + <div id="oldestparents"> + <ul> + <TMPL_LOOP NAME="PARENTLINKS"> + <TMPL_IF NAME="HEIGHT_2"> + <TMPL_ELSE> + <TMPL_IF NAME="HEIGHT_1"> + <TMPL_ELSE> + <li><a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a></li> + </TMPL_IF> + </TMPL_IF> + </TMPL_LOOP> + </ul> + </div> + + <!-- dedicated div's for mother and grand'ma --> + <TMPL_LOOP NAME="PARENTLINKS"> + <TMPL_IF NAME="HEIGHT_2"> + <div id="grandma"> + <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a> + </div> + <TMPL_ELSE> + <TMPL_IF NAME="HEIGHT_1"> + <div id="mother"> + <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a> + </div> + </TMPL_IF> + </TMPL_IF> + </TMPL_LOOP> + + <!-- eventually, the current page title --> + <TMPL_VAR NAME="TITLE"> + </div> diff --git a/t/parentlinks.t b/t/parentlinks.t new file mode 100755 index 000000000..593937a97 --- /dev/null +++ b/t/parentlinks.t @@ -0,0 +1,82 @@ +#!/usr/bin/perl +# -*- cperl-indent-level: 8; -*- +# Testcases for the Ikiwiki parentlinks plugin. + +use warnings; +use strict; +use Test::More 'no_plan'; + +my %expected; + +BEGIN { use_ok("IkiWiki"); } + +# Init +%config=IkiWiki::defaultconfig(); +$config{srcdir}=$config{destdir}="/dev/null"; +$config{underlaydir}="underlays/basewiki"; +$config{templatedir}="t/parentlinks/templates"; +IkiWiki::loadplugins(); +IkiWiki::checkconfig(); + +# Test data +$expected{'parentlinks'} = + { + "" => [], + "ikiwiki" => [], + "ikiwiki/pagespec" => + [ {depth => 0, height => 2, }, + {depth => 1, height => 1, }, + ], + "ikiwiki/pagespec/attachment" => + [ {depth => 0, height => 3, depth_0 => 1, height_3 => 1}, + {depth => 1, height => 2, }, + {depth => 2, height => 1, }, + ], + }; + +# Test function +sub test_loop($$) { + my $loop=shift; + my $expected=shift; + my $template; + my %params; + + ok($template=template('parentlinks.tmpl'), "template created"); + ok($params{template}=$template, "params populated"); + + while ((my $page, my $exp) = each %{$expected}) { + my @path=(split("/", $page)); + my $pagedepth=@path; + my $msgprefix="$page $loop"; + + # manually run the plugin hook + $params{page}=$page; + $template->clear_params(); + IkiWiki::Plugin::parentlinks::pagetemplate(%params); + my $res=$template->param($loop); + + is(scalar(@$res), $pagedepth, "$msgprefix: path length"); + # logic & arithmetic validation tests + for (my $i=0; $i<$pagedepth; $i++) { + my $r=$res->[$i]; + is($r->{height}, $pagedepth - $r->{depth}, + "$msgprefix\[$i\]: height = pagedepth - depth"); + ok($r->{depth} ge 0, "$msgprefix\[$i\]: depth>=0"); + ok($r->{height} ge 0, "$msgprefix\[$i\]: height>=0"); + } + # comparison tests, iff the test-suite has been written + if (scalar(@$exp) eq $pagedepth) { + for (my $i=0; $i<$pagedepth; $i++) { + my $e=$exp->[$i]; + my $r=$res->[$i]; + map { is($r->{$_}, $e->{$_}, "$msgprefix\[$i\]: $_"); } keys %$e; + } + } + # else { + # diag("Testsuite is incomplete for ($page,$loop); cannot run comparison tests."); + # } + } +} + +# Main +test_loop('parentlinks', $expected{'parentlinks'}); diff --git a/t/parentlinks/templates/parentlinks.tmpl b/t/parentlinks/templates/parentlinks.tmpl new file mode 100644 index 000000000..3ca3b0030 --- /dev/null +++ b/t/parentlinks/templates/parentlinks.tmpl @@ -0,0 +1,4 @@ +<!-- This template file only has to "use" the loops tested by parentlinks.t --> + +<TMPL_LOOP NAME="PARENTLINKS"> +</TMPL_LOOP> |