Gzav's Wiki | PmWiki / Page Lists

authors, admins (intermediate)

PmWiki comes with two directives for generating lists of pages -- (:pagelist:) and (:searchresults:). Both directives are basically the same and each accepts the parameters documented below. The primary difference between the two is that searchresults generates the "Results of search for ..." and "### pages found out of ### searched" messages around the results.

The (:searchbox:) directive generates a search form (input text box) to submit search queries. The markup generally accepts the same parameters as (:pagelist:), which makes it possible to restrict, order and format searchresults in the same ways that are described below for a (:pagelist:). For more information about the (:searchbox:) directive, and the ways in which it differs from a (:pagelist:), skip to the section below.

Basic syntax

(:pagelist:) without any arguments shows a bulleted list of all pages, as links, ordered alphabetically and in groups.
(:pagelist group=abc fmt=def list=ghi order=jkl argument1 argument2 etc:) shows a pagelist according to the parameters supplied. Parameters are optional.

Parameters

Any argument supplied within (:pagelist:) that isn't in the form 'key=value' is treated as text that either must (or must not) exist in the page text. The minus sign (-) or exclamation mark (!) can be used to indicate the logical not. Thus

    (:pagelist trail=PmWiki.DocumentationIndex list=normal apple -pie:)

lists all "normal" pages listed in the DocumentationIndex trail that contain the word "apple" but not "pie".

group= and name=

The "group=" and "name=" parameters limit results to pages in a specific group or with a specific name:

    # All pages in the Pmwiki group:
    (:pagelist group=PmWiki :)
    # All pages except those in the PmWiki or Site groups:
    (:pagelist group=-PmWiki,-Site :)
    # All RecentChanges pages
    (:pagelist name=RecentChanges :)
    # All pages except RecentChanges
    (:pagelist name=-RecentChanges :)

Wildcards

Name and group parameters can contain wildcard characters that display only pages matching a given pattern:

An asterisk (*) represents zero or more characters
A question mark (?) represents exactly one character

Examples:

    # All pages in any group beginning with "PmWiki"
    (:pagelist group=PmWiki* :)
    # All pages in any group beginning with "PmWiki", except for Chinese
    (:pagelist group=PmWiki*,-PmWikiZh :)
    # All pages in the PmCal group with names starting with "2005":
    (:pagelist name=PmCal.2005* :)

trail=

The "trail=" option obtains the list of pages to be displayed from a WikiTrail:

    # Display pages in the documentation by modification time
    (:pagelist trail=PmWiki.DocumentationIndex order=-time:)
    # Display five most recently changed pages
    (:pagelist trail=RecentChanges count=5:)

list=

The "list=" option allows a search to include or exclude pages according to predefined patterns set by the administrator.

"list=normal" is predefined, and which excludes things like AllRecentChanges, RecentChanges, GroupHeader, GroupFooter, GroupAttributes, and the like from being displayed in the list results.
"list=all" over-rides a "default" list that may be set by the wiki's administrator to exclude groups such as PmWiki or Site from regular search results.
Wiki administrators can define custom lists via the $SearchPatterns array (see Cookbook:SearchResults).

fmt=

The "fmt=" option determines how the resulting list should be displayed. PmWiki predefines several formats:

fmt=#bygroup - Display pages within groups (default format)
fmt=#simple - Display a simple ordered list of pages in the form Group.Name
fmt=#title - Display a list of pages by page title. Use "order=title" to have them sorted by title (default is to order by page name).
fmt=#group - Display a list of wikigroups (without listing the pages in the groups)
fmt=#include - Display the contents of each page in the list (note, this could take a very long time for long lists!)

These formats are defined in pagelist templates, which can be customized, as shown below.

link=

The "link=" option implements "backlinks" -- i.e., it returns a list of pages with a link to the target. It's especially useful for category pages and finding related pages.

    # all pages with a link to PmWiki.DocumentationIndex
    (:pagelist link=PmWiki.DocumentationIndex:)
    # all pages with links to the current page
    (:pagelist link={$FullName}:)
    # all pages in the "Skins" category
    (:pagelist link=Category.Skins:)

count=

The "count=" option limits the pagelist to a specific number of pages.

    # A simple bullet list of ten most recently modified pages
    (:pagelist trail=Site.AllRecentChanges count=10 fmt=#simple:)

order=

The "order=" option allows the pages in the list to be sorted according to different criteria. Use a minus sign to indicate a reverse sort. Multiple sorting criteria can be specified using a comma:

order=name - alphabetically by name (default order)
order=title - sorted alphabetically by title rather than names
order=time - most recently changed pages last
order=ctime - time of page creation (see note)
order=size - sort by page size (not file size), smallest pages first.
order=group,title - sort by title within groups
order=random - shuffle the pages into random sequence

Note: fmt=trail results in an unordered pagelist, i.e. the trail order is preserved in the pagelist. So PmWiki's alphabetical default order does not apply in this case.

Note: ctime was added to pages only from pmwiki 2.1.beta15 onwards, pages created by earlier versions don't carry a ctime attribute and can't be sorted that way.

Examples

Include the contents of a random page from the Banners group:

    (:pagelist group=Banners order=random count=1 fmt=#include list=normal:)

Display a simple list of the last ten recently changed pages:

    (:pagelist trail=Site.AllRecentChanges count=10 fmt=#simple:)

Display the "top twenty" biggest cookbook pages:

    (:pagelist group=Cookbook order=-size count=20 :)

The Searchbox Directive

The (:searchbox:) directive generally accepts the same parameters as (:pagelist:), with the following differences:

Parameters can be added to the input text of a searchbox (or to the markup, or both)
The target page for displaying searchbox results can be set with the parameter target=GroupName.PageName. The default is the current page.
An initial search string can be specified in the searchbox markup, but it must be in the form value='search string'. That search string is displayed in the input text and can be modified by when the search is run.
- Tip: If more than one searchbox appears on a page, adding a blank initial value like this value='', to the markup for each searchbox will prevent a search string for one box from populating all of the other boxes.

Customizing Pagelist Templates

PmWiki's default templates are in Site.PageListTemplates, which is replaced during upgrades. These default templates can be supplemented with custom templates stored in other locations. As of version 2.1.10, PmWiki's default configuration looks for templates in Site.PageListTemplates, Site.LocalTemplates ?, and the current page. Administrators can change those locations by using the $FPLTemplatePageFmt variable. Custom templates are used in the same way as default templates: by referencing the desired format with the fmt= option. There are several ways to indicate which template to use:

fmt=#custom uses the #custom section from Site.PageListTemplates, Site.LocalTemplates?, or current page (sections are denoted by [[#custom]] anchors.
fmt=MyTemplatePage#custom uses a custom format from page MyTemplatePage from its #custom section.
fmt=custom uses custom format which is defined in a cookbook script as custom.

A pagelist template contains standard pmwiki markup. When creating pagelist output, pmwiki iterates over each page returned from the pagelist and will include the pagelist template markup once for every page in the list. During the page list iteration pmwiki sets 3 special page references: =,< and >. These special page references are updated on each pagelist iteration and can be used with the PageVariable syntax, such as {=$variable}, to define a pagelist template which will format the pagelist output. The meaning of the special references are:

   =   current page    so {=$Title} displays the title of the current page in the iteration
   <   previous page   so {<$Group} displays the group of the previous page in the iteration
   >   next page       so {>$Name}  displays the name of the next page in the iteration

The > and < references are most useful to help structure pagelist output before and after the actual pagelist. Some common tests used to structure pagelist output are:

    (:if equal {<$Group}:)              # Iteration is at the beginning of list
    (:if equal {>$Group}:)              # Iteration is at the end of list
    (:if ! equal {=$Group} {<$Group}:)  # Iteration is at the first item in a group
    (:if ! equal {=$Group} {>$Group}:)  # Iteration is at the last item in a group

Three additional PageVariables are available during pagelist iterations which are not normally available, they are:

    {$PageCount}       The current page count of this iteration
    {$GroupCount}      The current group count of this iteration
    {$GroupPageCount}  The current page count within the current group of this iteration

It is advisable to not modify the Site.PageListTemplates file directly so that you will still benefit from upgrades. Instead, modify the Site.LocalTemplates page (which is not part of the PmWiki distribution). Cookbook:PagelistTemplateSamples has many examples of custom pagelist formats.

In addition, the Cookbook:Cookbook has other recipes for special fmt= options, including fmt=dictindex (alphabetical index) and fmt=forum (forum postings).

Mon pense bête...

Page Lists