[pmwiki-users] PageListVariables

[Patrick R. Michaud]

On Tue, May 30, 2006 at 08:43:32PM -0500, Tegan Dowling wrote:
> On 5/30/06, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> > On Tue, May 30, 2006 at 02:23:34PM -0700, Martin Fick wrote:!
> > >
> > > ...where does <<the use of the {>$var}, {<$var} or {=$var}
> > > syntax>> belong? If we
> > > put it on the PageVariables page, it might seem a
> > > little weird, but the page is closest to a description
> > > of these types of things.
> >
> > It's currently described on Site.PageListTemplates, which
> > is in the "See Also" section of PmWiki.PageLists.  I'm
> > guessing the information could be added to PmWiki.PageLists,
> > or perhaps made into a FAQ at the bottom of PmWiki.PageLists
> > with a link to Site.PageListTemplates.
> 
> If someone would also please **expand on** the description of its use
> I'd be very grateful.  This code is far from intuitive, even with the
> examples right there on the Site.PageListTemplates page.  

FWIW, pagelist templates were never intended to be "intuitive" -- they're
definitely an "advanced feature".  And many will tell you that they're 
much easier than the alternative, which is to create a custom PHP 
function for formatting.  (But note that the custom PHP function 
capability is still available, for anyone who prefers it.)

Which part of the syntax is giving you grief?  Let's start with a
simple template for displaying a list of pages:

    * [[{=$FullName}]]

This says that for each entry in the list of pages, we want to generate
a markup line consisting of an asterisk and the full name of the page
inside of [[...]].  

Now then, why {=$FullName} and not {$FullName}?  The answer is that
{$FullName} already has a meaning:  it's the name of the page
that is generating the pagelist -- i.e., the page that has the (:pagelist:)
markup itself.  So, if we had used {$FullName} here, we'd see the name
of the currently browsed page repeated a bunch of times (once for 
each entry in the pagelist).

So, we use the '=' to mean "current entry in the pagelist."  Another
simple list could look like:

    * [[{=$Group}/{=$Name}]]

which displays every page in the list by name (but doesn't display the
group).


Let's look at a slightly bigger example.  The pages are already ordered
by group, so we'd like to put a group name at the start of each new
group of pages.  The template for that is:

    (:if ! equal {=$Group} {<$Group}:)

    :{=$Group} /:
    (:if:)
    : :[[{=$Group}/{=$Name}]]

The last line is just displaying each page in the pagelist by name
and no group -- same as our simple list above.  

The (:if:) conditional is checking the group of the current pagelist 
entry {=$Group} against the group of the previous entry {<$Group}.  
If they're different, then we know we're starting a new group, so 
we output a blank line and a heading for the new group before the 
first entry in the group.

Those are the basics -- everything proceeds from there.
Essentially, {=$var} is a page variable of the current entry in
the pagelist, {<$var} is a page variable of the previous entry in
the pagelist, and {>$var} is a page variable of the next entry in
the pagelist.

Hope this helps -- if there are still questions, feel free to
ask.  If any of this points to ideas about how to improve the
documentation, feel free to add it.

Pm