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

Patrick R. Michaud pmichaud at pobox.com
Tue Sep 26 19:00:17 CDT 2006


On Tue, Sep 26, 2006 at 05:42:28PM -0500, Ben Wilson wrote:
> 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.

You're correct, page variables cannot (yet?) contain spaces.

> 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.

Also correct.

Pm

> 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