2 # Copyright © 2008-2011 Joey Hess
3 # Copyright © 2009-2012 Simon McVittie <http://smcv.pseudorandom.co.uk/>
4 # Licensed under the GNU GPL, version 2, or any later version published by the
5 # Free Software Foundation
6 package IkiWiki::Plugin::trail;
13 hook(type => "getsetup", id => "trail", call => \&getsetup);
14 hook(type => "needsbuild", id => "trail", call => \&needsbuild);
15 hook(type => "preprocess", id => "trailoptions", call => \&preprocess_trailoptions, scan => 1);
16 hook(type => "preprocess", id => "trailitem", call => \&preprocess_trailitem, scan => 1);
17 hook(type => "preprocess", id => "trailitems", call => \&preprocess_trailitems, scan => 1);
18 hook(type => "preprocess", id => "traillink", call => \&preprocess_traillink, scan => 1);
19 hook(type => "pagetemplate", id => "trail", call => \&pagetemplate);
20 hook(type => "build_affected", id => "trail", call => \&build_affected);
25 # If a page $T is a trail, then it can have
27 # * $pagestate{$T}{trail}{contents}
28 # Reference to an array of lists each containing either:
29 # - [pagenames => "page1", "page2"]
32 # A link specification, pointing to the same page that [[link]]
34 # - [pagespec => "posts/*", "age", 0]
35 # A match by pagespec; the third array element is the sort order
36 # and the fourth is whether to reverse sorting
38 # * $pagestate{$T}{trail}{sort}
39 # A sorting order; if absent or undef, the trail is in the order given
40 # by the links that form it
42 # * $pagestate{$T}{trail}{circular}
43 # True if this trail is circular (i.e. going "next" from the last item is
44 # allowed, and takes you back to the first)
46 # * $pagestate{$T}{trail}{reverse}
47 # True if C<sort> is to be reversed.
49 # If a page $M is a member of a trail $T, then it has
51 # * $pagestate{$M}{trail}{item}{$T}[0]
52 # The page before this one in C<$T> at the last rebuild, or undef.
54 # * $pagestate{$M}{trail}{item}{$T}[1]
55 # The page after this one in C<$T> at the last refresh, or undef.
65 # Cache of pages' old titles, so we can tell whether they changed
71 foreach my $page (keys %pagestate) {
72 if (exists $pagestate{$page}{trail}) {
73 if (exists $pagesources{$page} &&
74 grep { $_ eq $pagesources{$page} } @$needsbuild) {
75 # Remember its title, so we can know whether
77 $old_trail_titles{$page} = title_of($page);
79 # Remove state, it will be re-added
80 # if the preprocessor directive is still
81 # there during the rebuild. {item} is the
82 # only thing that's added for items, not
83 # trails, and it's harmless to delete that -
84 # the item is being rebuilt anyway.
85 delete $pagestate{$page}{trail};
95 sub preprocess_trailoptions (@) {
98 if (exists $params{circular}) {
99 $pagestate{$params{page}}{trail}{circular} =
100 IkiWiki::yesno($params{circular});
103 if (exists $params{sort}) {
104 $pagestate{$params{page}}{trail}{sort} = $params{sort};
107 if (exists $params{reverse}) {
108 $pagestate{$params{page}}{trail}{reverse} = $params{reverse};
114 sub preprocess_trailitem (@) {
118 # avoid collecting everything in the preprocess stage if we already
119 # did in the scan stage
120 if (defined wantarray) {
121 return "" if $scanned;
128 my $trail = $params{page};
130 $link = linkpage($link);
132 add_link($params{page}, $link, 'trail');
133 push @{$pagestate{$params{page}}{trail}{contents}}, [link => $link];
138 sub preprocess_trailitems (@) {
141 # avoid collecting everything in the preprocess stage if we already
142 # did in the scan stage
143 if (defined wantarray) {
144 return "" if $scanned;
150 # trail members from a pagespec ought to be in some sort of order,
151 # and path is a nice obvious default
152 $params{sort} = 'path' unless exists $params{sort};
153 $params{reverse} = 'no' unless exists $params{reverse};
155 if (exists $params{pages}) {
156 push @{$pagestate{$params{page}}{trail}{contents}},
157 ["pagespec" => $params{pages}, $params{sort},
158 IkiWiki::yesno($params{reverse})];
161 if (exists $params{pagenames}) {
162 push @{$pagestate{$params{page}}{trail}{contents}},
163 [pagenames => (split ' ', $params{pagenames})];
169 sub preprocess_traillink (@) {
174 my $trail = $params{page};
178 ([^\|]+) # 1: link text
182 (.+) # 2: page to link to
186 $link = linkpage($2);
188 add_link($params{page}, $link, 'trail');
190 # avoid collecting everything in the preprocess stage if we already
191 # did in the scan stage
193 if (defined wantarray) {
200 push @{$pagestate{$params{page}}{trail}{contents}}, [link => $link] unless $already;
202 if (defined $linktext) {
203 $linktext = pagetitle($linktext);
206 if (exists $params{text}) {
207 $linktext = $params{text};
210 if (defined $linktext) {
211 return htmllink($trail, $params{destpage},
212 $link, linktext => $linktext);
215 return htmllink($trail, $params{destpage}, $link);
218 # trail => [member1, member2]
219 my %trail_to_members;
220 # member => { trail => [prev, next] }
221 # e.g. if %trail_to_members = (
222 # trail1 => ["member1", "member2"],
223 # trail2 => ["member0", "member1"],
226 # then $member_to_trails{member1} = {
227 # trail1 => [undef, "member2"],
228 # trail2 => ["member0", undef],
230 my %member_to_trails;
234 my %rebuild_trail_members;
237 my ($old, $new) = @_;
239 foreach my $trail (keys %$old) {
240 if (! exists $new->{$trail}) {
244 if (exists $old_trail_titles{$trail} &&
245 title_of($trail) ne $old_trail_titles{$trail}) {
249 my ($old_p, $old_n) = @{$old->{$trail}};
250 my ($new_p, $new_n) = @{$new->{$trail}};
251 $old_p = "" unless defined $old_p;
252 $old_n = "" unless defined $old_n;
253 $new_p = "" unless defined $new_p;
254 $new_n = "" unless defined $new_n;
255 if ($old_p ne $new_p) {
259 if (exists $old_trail_titles{$old_p} &&
260 title_of($old_p) ne $old_trail_titles{$old_p}) {
264 if ($old_n ne $new_n) {
268 if (exists $old_trail_titles{$old_n} &&
269 title_of($old_n) ne $old_trail_titles{$old_n}) {
274 foreach my $trail (keys %$new) {
275 if (! exists $old->{$trail}) {
283 my $done_prerender = 0;
286 return if $done_prerender;
288 %trail_to_members = ();
289 %member_to_trails = ();
291 foreach my $trail (keys %pagestate) {
292 next unless exists $pagestate{$trail}{trail}{contents};
296 my @contents = @{$pagestate{$trail}{trail}{contents}};
298 foreach my $c (@contents) {
299 if ($c->[0] eq 'pagespec') {
300 push @$members, pagespec_match_list($trail,
301 $c->[1], sort => $c->[2],
304 elsif ($c->[0] eq 'pagenames') {
307 foreach my $page (@pagenames) {
308 if (exists $pagesources{$page}) {
309 push @$members, $page;
312 # rebuild trail if it turns up
313 add_depends($trail, $page, deptype("presence"));
317 elsif ($c->[0] eq 'link') {
318 my $best = bestlink($trail, $c->[1]);
319 push @$members, $best if length $best;
323 if (defined $pagestate{$trail}{trail}{sort}) {
325 @$members = pagespec_match_list($trail, 'internal(*)',
327 sort => $pagestate{$trail}{trail}{sort});
330 if (IkiWiki::yesno $pagestate{$trail}{trail}{reverse}) {
331 @$members = reverse @$members;
339 foreach my $member (@$members) {
340 push @tmp, $member unless $seen{$member};
341 $up_in_trail = 1 if $member eq $trail;
346 for (my $i = 0; $i <= $#$members; $i++) {
347 my $member = $members->[$i];
349 $prev = $members->[$i - 1] if $i > 0;
350 my $next = $members->[$i + 1];
352 $member_to_trails{$member}{$trail} = [$prev, $next];
355 if ((scalar @$members) > 1 && $pagestate{$trail}{trail}{circular}) {
356 $member_to_trails{$members->[0]}{$trail}[0] = $members->[$#$members];
357 $member_to_trails{$members->[$#$members]}{$trail}[1] = $members->[0];
360 $trail_to_members{$trail} = $members;
361 $up_in_trail{$trail} = $up_in_trail;
364 foreach my $member (keys %pagestate) {
365 if (exists $pagestate{$member}{trail}{item} &&
366 ! exists $member_to_trails{$member}) {
367 $rebuild_trail_members{$member} = 1;
368 delete $pagestate{$member}{trail}{item};
372 foreach my $member (keys %member_to_trails) {
373 if (! exists $pagestate{$member}{trail}{item}) {
374 $rebuild_trail_members{$member} = 1;
377 if (trails_differ($pagestate{$member}{trail}{item},
378 $member_to_trails{$member})) {
379 $rebuild_trail_members{$member} = 1;
383 $pagestate{$member}{trail}{item} = $member_to_trails{$member};
392 # In principle we might not have done this yet, although in practice
393 # at least the trail itself has probably changed, and its template
394 # almost certainly contains TRAILS or TRAILLOOP, triggering our
395 # prerender as a side-effect.
398 foreach my $member (keys %rebuild_trail_members) {
399 $affected{$member} = sprintf(gettext("building %s, its previous or next page has changed"), $member);
407 if (defined ($pagestate{$page}{meta}{title})) {
408 return $pagestate{$page}{meta}{title};
410 return pagetitle(IkiWiki::basename($page));
415 sub pagetemplate (@) {
417 my $page = $params{page};
418 my $template = $params{template};
420 return unless length $page;
422 if ($template->query(name => 'trails') && ! $recursive) {
426 my $inner = template("trails.tmpl", blind_cache => 1);
427 IkiWiki::run_hooks(pagetemplate => sub {
428 shift->(%params, template => $inner)
430 $template->param(trails => $inner->output);
434 if ($template->query(name => 'trailloop')) {
439 # sort backlinks by page name to have a consistent order
440 foreach my $trail (sort keys %{$member_to_trails{$page}}) {
442 my $members = $trail_to_members{$trail};
443 my ($prev, $next) = @{$member_to_trails{$page}{$trail}};
444 my ($prevurl, $nexturl, $prevtitle, $nexttitle);
447 $prevurl = urlto($prev, $page);
448 $prevtitle = title_of($prev);
452 $nexturl = urlto($next, $page);
453 $nexttitle = title_of($next);
458 prevtitle => $prevtitle,
461 nexttitle => $nexttitle,
465 # the trail index is added as 'up' page, but only if it's
466 # not a page in the trail itself. This allows the definition of
467 # up-less trails by using e.g. the trailitems directive in one of the
469 unless ($up_in_trail{$trail}) {
470 $trail_info{trailpage} = $trail;
471 $trail_info{trailtitle} = title_of($trail);
472 $trail_info{trailurl} = urlto($trail, $page);
475 push @trails, \%trail_info;
478 $template->param(trailloop => \@trails);