[pmwiki-announce] 2.2.0-beta36 release (pagelist template updates)

[Patrick R. Michaud]

I've just released 2.2.0-beta36, which adds some new features
to pagelist templates.  As always, the latest release is 
available from

    http://www.pmwiki.org/pub/pmwiki/pmwiki-2.2.0-beta36.tgz
    http://www.pmwiki.org/pub/pmwiki/pmwiki-2.2.0-beta36.zip
    svn://pmwiki.org/pmwiki/tags/latest

This release features additions to the pagelist templating syntax,
as recently discussed on the pmwiki-users mailing list [1].  Some of
these features are quite advanced, so if the below doesn't make any
sense to you it's okay to ignore it.  (Or ask questions on the
mailing lists.)

[1]  http://thread.gmane.org/gmane.comp.web.wiki.pmwiki.user/39019

This release also fixes the use of nested page variables in
conditional markups, and adds some additional capabilities to
the count= option in pagelists.  These are described below.

Comments, questions, etc. welcomed as always, and thanks!

Pm

==========

Pagelist templates may now be easily separated into "sections" 
that are included or not included in the output based on a variety of
conditions.  These are intended to be improved versions of the
(:if ...:) conditions that have traditionally been used to control
pagelist output (however, the (:if:) conditions still work as before).

The simplest versions of the directives are:

  (:template first:)      # markup to display only for first page in list
  (:template each:)       # markup to display for each page in list
  (:template last:)       # markup to display only on last page in list

So, a pagelist template can specify:

  (:template first:)
  Pages in the list:
  (:template each:)
  * [[{=$FullName}]]
  (:template last:)
  Displayed {$$PageCount} pages.

In addition, the "first" and "last" options can have control break
arguments that identify markup to be displayed on the first or last
page within a particular control section.  For example, to specify
markup to be displayed upon reaching the first or last page of 
a group, one can use

  (:template first {=$Group}:)
  (:template last {=$Group}:)

Thus, instead of writing control breaks using (:if:) directives, as in

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

one can now write

    (:template first {=$Group}:)
    Group: {=$Group}
    (:template each:)
    * {=$FullName}

In addition, a template may specify default options to be used
in the pagelist command.  For example, a pagelist template to 
display a list of pages by their titles (and sorted by title)
might use:

    [[#bytitle]]
    (:template default order=title:)
    * [[$FullName|+]]
    [[#bytitleend]]

Then an author could write (:pagelist fmt=#bytitle:) and the
pages would automatically be sorted by title without having to
specify an additional "order=title" option to the (:pagelist:)
directive.

The "count=" option for pagelists now provides the ability to
return items from the end of a list, subsets of a list, and
even to display pages in reverse sequence.  As before, providing
a simple number to count= limits the list to the first "n" pages.

    count=10          # display first ten pages of list

Negative numbers specify pages to be displayed from the end
of the list:

    count=-10         # display last ten pages of list

Ranges may be specified using '..', thus:

    count=1..10       # first ten pages of list
    count=5..10       # 5th through 10th pages of list

Negative numbers in ranges count from the end of the list:

    count=-10..-5     # 10th from end, 9th from end, ..., 5th from end

Omitting the start or end of the range uses the start or end of the list:

    count=10..        # skip first ten pages
    count=..10        # 1st through 10th page of list
    count=-10..       # last ten pages of list
    count=..-10       # all but the last nine pages

Ranges can be reversed, indicating that the order of pages 
in the output should likewise be reversed:

    count=5..10       # 5th through 10th pages of list
    count=10..5       # same as 5..10 but in reverse sequence
    count=-1..1       # all pages in reverse sequence

"Reverse sequence" here refers to the sequence ''after'' any sorting
has taken place.  Therefore the three directives below are equivalent:

    (:pagelist order=-name count=10:)
    (:pagelist order=-name count=1..10:)
    (:pagelist order=name count=-1..-10:)