From Asterias

PmWiki: PageLists

authors, admins (intermediate) PmWiki comes with two directives for generating lists of pages -- (:pagelist:) and (:searchresults:). 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 -- otherwise they're basically the same.

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


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


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


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


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


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


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

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


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


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


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:

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.


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:

Customizing Pagelist Templates

PmWiki's default templates are in Site.PageListTemplates. Custom pagelist formats can be defined using pagelist templates and referenced by the fmt= option. There are several ways to indicate which template to use:

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

See Also

<< Categories | Documentation Index | Deleting pages >>

How can I configure my site to always exclude wiki-related pages from searches?

Try the following in your local/config.php file. See also Cookbook:SearchPatterns.

## Exclude Certain pages / groups from search results.
$SearchPatterns['default'][] = '!\\.(All)?Recent(Changes|Uploads|Comments)$!';
$SearchPatterns['default'][] = '!\\.Group(Print)?(Header|Footer|Attributes)$!';
$SearchPatterns['default'][] = '!\\.(Left|Right|Side)(Bar|Menu|Note)$!';
$SearchPatterns['default'][] = '!^Site\\.!';
$SearchPatterns['default'][] = '!^PmWiki\\.!';

If you add $SearchPatterns['default']... to exclude groups and pages from pagelist and search output, you can include the omitted pages by using "list=all" in the pagelist or search parameters.

Retrieved from
Page last modified on June 09, 2006, at 04:20 PM