[pmwiki-users] pmwiki-2.2.0-beta3 released (new pagelist code)

[Patrick R. Michaud]

On Tue, Sep 26, 2006 at 04:49:08PM -0500, Ben Wilson wrote:
> On 9/26/06, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> >One feature that the new pagelist code adds immediately is the
> >ability to sort pagelists based on page text variables.  For example,
> >to order pages based on the {$:BookTitle} page text variable, one
> >can use:
> >
> >    (:pagelist order=$:BookTitle ... :)
> 
> Sorry to sound dense. I know there have been several references to
> this feature, but I'm a little too distracted to wrap my mind around
> the references. Is there a page that explains the "page text
> variables" and their new role? I'm sure eventually we'll need this for
> initiates to the Community.

No, there's not yet a page that explains it.  I'm hoping someone
will write one, or at least draft up something that explains them.  
I think they're very powerful, but difficult to explain until you
see how they can be actually used.  In the meantime, here's an
attempt at an explanation...

A "page text variable" is just a variable and value pair that is 
defined within the markup text of a page.  Suppose we have a page 
called Cookbook.RandomQuote that contains the lines (among other markup)

    Summary: Insert random quotes in a page
    Version: 2006-03-06
    Prerequisites: pmwiki-2.1.beta15
    Status: Stable
    Maintainer: Pm

This markup effectively "defines" five page text variables.  I
have to put "defines" in quotes here, because as far as saving
and rendering the page is concerned, nothing special is happening 
here-- there's no special markup rule that processes these lines
or changes their output.[1]  It all happens when we later 
refer to one of the lines using a page text variable markup:

    Variable                   Value
    --------                   -----
    {$:Summary}                Insert random quotes in a page
    {$:Version}                2006-03-06
    {$:Prerequisites}          pmwiki-2.1.beta15
    {$:Status}                 Stable
    {$:Maintainer}             Pm

If you've seen the Cookbook.Properties or Cookbook.PageVariableExtensions
recipes, then page text variables are essentially doing the same
thing as those recipes provide, except we aren't using a special 
(:set:) markup to assign values.  (There is a form of such markup
if we need it -- keep reading.)

A big advantage of this is that it's possible for us to access
the page text variable values of other pages.  If we have
Cookbook.RandomQuote with markup as above, and another page
contains the markup {Cookbook.RandomQuote$:Summary}, then we'll 
get the value of the "Summary:" line from the Cookbook.RandomQuote 
page.

As a result, we can also use page text variables in pagelist 
templates, thus

    [[#template]]
    * {=$FullName}: {=$:Summary}
    [[#templateend]]

will display the names of all of the pages in the list along with
any "Summary:" line of each.

With the latest beta3 release, we can also order pages in a pagelist
based on the values of one or more page text variables.  So, 
if we wanted to order a list of pages based on each page's 
"Maintainer:" value:

    (:pagelist order=$:Maintainer:)

Now then, sometimes we want a page to be able to define a value
but not have that value be displayed when the page is viewed.
This is the "directive" form of page variable markup:

    (:Summary: Insert random quotes in a page:)

Like the "Summary:" lines above, this also provides a $:Summary page 
text variable, except it doesn't display anything when the page 
itself is viewed.  (The parentheses and colons combine nicely here
to mean "don't show this" and "this is a page text variable".)

Lastly, definition lists are normally another way of associating
values with names, so they also count as page text variables that
just have a different markup output:

    :Summary: Insert random quotes in a page
    :Version: 2006-03-06

This capability will be (already is?) very useful for things 
like PITS and the Cookbook.  Currently PITS is able to display 
its index via several special-purpose (:pitslist:) functions.  But
we can now do almost the same thing using just (:pagelist:) and
page text variables in a template:

  ||[[PITS/{=$Name}]] ||{=$:Created} ||{=$:Category} ||{=$:Version} ||{=$:Priority} ||{=$:Status} ||{=$:Summary} ||

We also get sorting capabilities "for free" -- for example, to 
sort the items by status and reverse priority within status:

       (:pagelist order=$:Status,-$:Priority fmt=#pitslist :)

Does that help illustrate what these are all about?

Pm

1.  If you look at the output of Cookbook.RandomQuote on pmwiki.org,
    you'll see that these lines do have a different output
    than normal text, which isn't what I said above.  But the
    difference on pmwiki.org is because I have a special markup
    rule enabled for the Cookbook, and not because the core
    is treating these lines any differently.  Try the same
    lines in a non-Cookbook page and you'll see that they're
    treated as simple markup.