[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