]> sipb.mit.edu Git - ikiwiki.git/blobdiff - IkiWiki/Plugin/trail.pm
Split trail directive into trailitems, trailoptions
[ikiwiki.git] / IkiWiki / Plugin / trail.pm
index 87d99dd3dbafcd47bdc3e599d79697552ffc9874..5ee152155187d718d314bb70776ff2ecb8503c6b 100644 (file)
@@ -12,9 +12,10 @@ use IkiWiki 3.00;
 sub import {
        hook(type => "getsetup", id => "trail", call => \&getsetup);
        hook(type => "needsbuild", id => "trail", call => \&needsbuild);
-       hook(type => "preprocess", id => "trail", call => \&preprocess_trail, scan => 1);
+       hook(type => "preprocess", id => "trailoptions", call => \&preprocess_trailoptions, scan => 1);
        hook(type => "preprocess", id => "trailinline", call => \&preprocess_trailinline, scan => 1);
        hook(type => "preprocess", id => "trailitem", call => \&preprocess_trailitem, scan => 1);
+       hook(type => "preprocess", id => "trailitems", call => \&preprocess_trailitems, scan => 1);
        hook(type => "preprocess", id => "traillink", call => \&preprocess_traillink, scan => 1);
        hook(type => "pagetemplate", id => "trail", call => \&pagetemplate);
 }
@@ -27,7 +28,20 @@ If a page C<$T> is a trail, then it can have
 
 =item * C<$pagestate{$T}{trail}{contents}>
 
-Reference to an array of pagespecs or links in the trail.
+Reference to an array of lists each containing either:
+
+=over
+
+=item * C<[link, "link"]>
+
+A link specification, pointing to the same page that C<[[link]]> would select
+
+=item * C<[pagespec, "posts/*", "age", 0]>
+
+A match by pagespec; the third array element is the sort order and the fourth
+is whether to reverse sorting
+
+=back
 
 =item * C<$pagestate{$T}{trail}{sort}>
 
@@ -90,44 +104,9 @@ sub needsbuild (@) {
 
 my $scanned = 0;
 
-=for wiki
-
-The `trail` directive is supplied by the [[plugins/contrib/trail]]
-plugin. It sets options for the trail represented by this page. Example usage:
-
-    \[[!trail sort="meta(date)" circular="no" pages="blog/posts/*"]]
-
-The available options are:
-
-* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
-  items of the trail are ordered according to the first link to each item
-  found on the trail page
-
-* `circular`: if set to `yes` or `1`, the trail is made into a loop by
-  making the last page's "next" link point to the first page, and the first
-  page's "previous" link point to the last page
-
-* `pages`: add the given pages to the trail
-
-=cut
-
-sub preprocess_trail (@) {
+sub preprocess_trailoptions (@) {
        my %params = @_;
 
-       # avoid collecting everything in the preprocess stage if we already
-       # did in the scan stage
-       if (defined wantarray) {
-               return "" if $scanned;
-       }
-       else {
-               $scanned = 1;
-       }
-
-       # trail members from a pagespec ought to be in some sort of order,
-       # and path is a nice obvious default
-       $params{sortthese} = 'path' unless exists $params{sortthese};
-       $params{reversethese} = 'no' unless exists $params{reversethese};
-
        if (exists $params{circular}) {
                $pagestate{$params{page}}{trail}{circular} =
                        IkiWiki::yesno($params{circular});
@@ -141,75 +120,19 @@ sub preprocess_trail (@) {
                $pagestate{$params{page}}{trail}{reverse} = $params{reverse};
        }
 
-       if (exists $params{pages}) {
-               push @{$pagestate{$params{page}}{trail}{contents}},
-                       ["pagespec" => $params{pages}, $params{sortthese},
-                               IkiWiki::yesno($params{reversethese})];
-       }
-
-       if (exists $params{pagenames}) {
-               my @list = map { [link =>  $_] } split ' ', $params{pagenames};
-               push @{$pagestate{$params{page}}{trail}{contents}}, @list;
-       }
-
        return "";
 }
 
-=for wiki
-
-The `trailinline` directive is supplied by the [[plugins/contrib/trail]]
-plugin. It behaves like the [[trail]] and [[inline]] directives combined.
-Like [[inline]], it includes the selected pages into the page with the
-directive and/or an RSS or Atom feed; like [[trail]], it turns the
-included pages into a "trail" in which each page has a link to the
-previous and next pages.
-
-    \[[!inline sort="meta(date)" circular="no" pages="blog/posts/*"]]
-
-All the options for the [[inline]] and [[trail]] directives are valid.
-
-The `show`, `skip` and `feedshow` options from [[inline]] do not apply
-to the trail.
-
-* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
-  items of the trail are ordered according to the first link to each item
-  found on the trail page
-
-* `circular`: if set to `yes` or `1`, the trail is made into a loop by
-  making the last page's "next" link point to the first page, and the first
-  page's "previous" link point to the last page
-
-* `pages`: add the given pages to the trail
-
-=cut
-
 sub preprocess_trailinline (@) {
        my %params = @_;
 
-       if (exists $params{sort}) {
-               $params{sortthese} = $params{sort};
-               delete $params{sort};
-       }
-       else {
+       if (! exists $params{sort}) {
                # sort in the same order as [[plugins/inline]]'s default
-               $params{sortthese} = 'age';
-       }
-
-       if (exists $params{reverse}) {
-               $params{reversethese} = $params{reverse};
-               delete $params{reverse};
-       }
-
-       if (exists $params{trailsort}) {
-               $params{sort} = $params{trailsort};
-       }
-
-       if (exists $params{trailreverse}) {
-               $params{reverse} = $params{trailreverse};
+               $params{sort} = 'age';
        }
 
        if (defined wantarray) {
-               scalar preprocess_trail(%params);
+               scalar preprocess_trailitems(%params);
 
                if (IkiWiki->can("preprocess_inline")) {
                        return IkiWiki::preprocess_inline(@_);
@@ -219,22 +142,10 @@ sub preprocess_trailinline (@) {
                }
        }
        else {
-               preprocess_trail(%params);
+               preprocess_trailitems(%params);
        }
 }
 
-=for wiki
-
-The `trailitem` directive is supplied by the [[plugins/contrib/trail]] plugin.
-It is used like this:
-
-    \[[!trailitem some_other_page]]
-
-to add `some_other_page` to the trail represented by this page, without
-generating a visible hyperlink.
-
-=cut
-
 sub preprocess_trailitem (@) {
        my $link = shift;
        shift;
@@ -259,23 +170,36 @@ sub preprocess_trailitem (@) {
        return "";
 }
 
-=for wiki
-
-The `traillink` directive is supplied by the [[plugins/contrib/trail]] plugin.
-It generates a visible [[ikiwiki/WikiLink]], and also adds the linked page to
-the trail represented by the page containing the directive.
+sub preprocess_trailitems (@) {
+       my %params = @_;
 
-In its simplest form, the first parameter is like the content of a WikiLink:
+       # avoid collecting everything in the preprocess stage if we already
+       # did in the scan stage
+       if (defined wantarray) {
+               return "" if $scanned;
+       }
+       else {
+               $scanned = 1;
+       }
 
-    \[[!traillink some_other_page]]
+       # trail members from a pagespec ought to be in some sort of order,
+       # and path is a nice obvious default
+       $params{sort} = 'path' unless exists $params{sort};
+       $params{reverse} = 'no' unless exists $params{reverse};
 
-The displayed text can also be overridden, either with a `|` symbol or with
-a `text` parameter:
+       if (exists $params{pages}) {
+               push @{$pagestate{$params{page}}{trail}{contents}},
+                       ["pagespec" => $params{pages}, $params{sort},
+                               IkiWiki::yesno($params{reverse})];
+       }
 
-    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
-    \[[!traillink some_other_page text="Click here to start the trail"]]
+       if (exists $params{pagenames}) {
+               my @list = map { [link =>  $_] } split ' ', $params{pagenames};
+               push @{$pagestate{$params{page}}{trail}{contents}}, @list;
+       }
 
-=cut
+       return "";
+}
 
 sub preprocess_traillink (@) {
        my $link = shift;