]> sipb.mit.edu Git - ikiwiki.git/commitdiff
Merge commit 'intrigeri/pedigree'
authorJoey Hess <joey@kodama.kitenet.net>
Wed, 16 Jul 2008 21:31:15 +0000 (17:31 -0400)
committerJoey Hess <joey@kodama.kitenet.net>
Wed, 16 Jul 2008 21:31:15 +0000 (17:31 -0400)
IkiWiki.pm
IkiWiki/Plugin/parentlinks.pm [new file with mode: 0644]
IkiWiki/Render.pm
doc/plugins/parentlinks.mdwn [new file with mode: 0644]
t/parentlinks.t [new file with mode: 0755]
t/parentlinks/templates/parentlinks.tmpl [new file with mode: 0644]

index 80e31711062694fb9494306e5900df4ca54f8b2f..6a1823c5a940461ab8cf8ad5952a889323713bbf 100644 (file)
@@ -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 (file)
index 0000000..a94cd46
--- /dev/null
@@ -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
index 990fcaaa111d3d48985eff126fbdd30bd0d17003..8a79119cd1173beb6a259ee4a3338e7dbbf6045b 100644 (file)
@@ -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 (file)
index 0000000..ff41393
--- /dev/null
@@ -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 (executable)
index 0000000..593937a
--- /dev/null
@@ -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 (file)
index 0000000..3ca3b00
--- /dev/null
@@ -0,0 +1,4 @@
+<!-- This template file only has to "use" the loops tested by parentlinks.t -->
+
+<TMPL_LOOP NAME="PARENTLINKS">
+</TMPL_LOOP>