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

Patrick R. Michaud pmichaud at pobox.com
Fri Mar 16 00:59:21 CDT 2007

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


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!



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}
    * {=$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:

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

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:)

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:)

More information about the pmwiki-announce mailing list