PmWiki | Cookbook / PageListExtensions

Summary: Many Pagelist Enhancements

Version: 1.1

Prerequisites:

Status:

Maintainer: MartinFick

Categories: WikiTrails

Questions answered by this recipe

How can I alter values other than the values of the pages being iterated over in a pagelist template?
How can I specify a warning message when a pagelist directive does not return any pages?
How can I accurately limit the # of pages returned with the fmt=group option?
How can I, as an author, alter trail markups, can they use titles?
How can I get a pagelist of targets from a page?

Description

Put pagelistextensions.php Δ in your cookbook/directory.

Add the following line to local/config.php

    @include_once("$FarmD/cookbook/pagelistextensions.php");

This recipe defines these new pagelist options:

  groupcount     to specify how many groups to iterate through
  pergroupcount  to specify how many pages per group to iterate through
  blank          to specify a page to include if the pagelist is blank
  targets        to specify a page to get targets from (similar to trail=)

Note: the new {$$option} (see below) markup is available inside the blank page.

This recipe also defines these new pagelist variables:

 {$PageTotal} the number of pages that would have been returned 
                  without a count, groupcount, or pergroupcount
 {$GroupTotal} the number of groups that would have been returned
                  without a count, groupcount, or pergroupcount

Finally, this recipe defines a special markup {$$option}. This new markup makes the (names and values of) options used in the pagelist directive available inside of pagelist templates. The special case {$$} returns the entire option string. Some examples:

 {$$count} displays the value of the count option

 A custom option: (:pagelist lyric='Hello My Darling' ...:)
 {$$lyric} displays Hello My Darling

Notes

You can see and edit a live example of this recipe here

You can use the {$$trail} variable to get the trail index page if you want to create trail markup with a pagelist. Here are two trail pagelist templates to use with this recipe:

fmt=#trail

[[#trail]]
(:if equal {=$FullName} {$FullName} :)\
<<[[{<$FullName}]] | [[{$$trail}]] | [[{>$FullName}]] >>\
(:if:)
[[#end]]

fmt=#trailtitled

[[#trailtitled]]
(:if equal {=$FullName} {$FullName} :)\
<<[[{<$FullName}|+]] | [[{$$trail}|+]] | [[{>$FullName}|+]] >>\
(:if:)
[[#end]]

You can follow the trail samples here

Release Notes

This recipe was last tested with pmwiki v. 2.1.10.

2006-07-15 : PageListExtensions - version 1.1 - Martin Fick

Added targets= option

2006-06-15 : PageListExtensions - version 1 - Martin Fick

Comments

The beauty of this is that one can use this to make a pagelist which will then list ALL the trails that the current page is on (as distinct from DynamicWikiTrails which only lists the wiki-trail currently being traversed).

First, one makes a pagelist format to reference (recursively) one of the above trail formats, and setting the above 'trail' variable to the currently matching page.

[[#trailtrail]]
(:pagelist trail={=$FullName} fmt={$$trailfmtpage}#{$$trailfmt}:)
[[#trailtrailend]]

When using the #trailtrail format, you give it the 'trailfmt' argument (which selects which 'trail' format to use). (If you don't then you end up with an endless recursion, so beware!)

Then you make a pagelist which lists the pages which link to the current page.

(:pagelist link={$FullName} trailfmt=trail fmt=#trailtrail:)

You would add stuff to this pagelist definition to make sure that the list is limited to pages which are likely to have wikitrails on them, from what you know about the contents of your own wiki. For example, suppose you have three wikitrail pages you're interested in, GroupA/GroupA, GroupA/FooPage and GroupB/BarPage. You don't know if the current page is on any of them, but if it is you want the trail markup to be there. In that case, you would put

(:pagelist group=GroupA,GroupB name=GroupA,FooPage,BarPage link={$FullName} trailfmt=trail fmt=#trailtrail:)

(probably put it in the GroupHeader or GroupFooter to make it easier)

One option might be to "register" dynamic trails. Two simple ways to do this. The first would to add a simple markup to each registered trail index page, i.e DynamicTrail. The second option would be to have a central registry page which is itself a trail index, i.e. Site.DynamicTrails. Both of these solutions could help define the list of trails to search for the current page on. One reason to register trails is to avoid random links to a page to be interpreted as trail indexes pointing to the current page. The second solution would have a major performance enhancement over the first since it would not have to scan all the pages looking for registered trails. Martin Fick October 02, 2006, at 01:30 PM

What comes out is all the trails which the current page is on, automatically, without having to add them by hand. Isn't that nifty?

-- Kathryn Andersen July 28, 2006, at 06:12 PM

Yes, very nifty, I love it! I will have to go back to PITS.00398 and note that you did this! Martin Fick

Er, what exactly does the 'targets' option do? Kathryn Andersen July 28, 2006, at 06:26 PM

Hmm, sorry that the description wasn't clear, I'll see if I can improve it and still keep it simple, maybe you can help? The targets= option takes a page as an argument and the pagelist created is the list of all target pages on that page. So instead of getting only targets that are appropriately formatted for a trail, it gets all page targets! Martin Fick July 28, 2006, at 10:04 PM

Sounds great, but should this still work in 2.2.0-beta65? I don't want to spend hours trying to figure out where in config.php or farmconfig.php I should place it to make it work if it doesn't work at all... Anke January 10, 2008, at 02:16 AM

Contributors

MartinFick

PageListExtensions