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

Ben Wilson dausha at gmail.com
Tue Sep 26 17:42:28 CDT 2006

That's about the cleanest explanation. So, anytime you have the
beginning of text as a word and colon, followed by text, we have a
page text variable? I assume the following three examples analogize
what a page text variable is.

Variable: This is a variable
AnotherVariable: This is another variable.
But is this a variable: What about this? I think it's not a variable
because of spacing.

I would also assume that surrounding markup is ignored, which would
allow for variable concealment. I mean, a person reading the page may
not see the variable, but the variable would still be displayable for
$:Variable purposes elsewhere.

(:if false:)
Variable: Can't read me, but I'm here.
(:if end:)

On 9/26/06, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> 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.

Ben Wilson
"All this worldly wisdom was once the unamiable heresy of some wise man." HDT

More information about the pmwiki-users mailing list