From AardWiki

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.

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. 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. PmWiki predefines "list=normal", which excludes things like AllRecentChanges, RecentChanges, GroupHeader, GroupFooter, and the like from being displayed in the list results. Wiki administrators can define custom lists via the $SearchPatterns array (see Cookbook:SearchResults).


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

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

Cookbook:PagelistTemplateSamples has many examples of custom pagelist formats. In addition, the Cookbook:Cookbook has other recipes for special fmt= options, in cluding fmt=dictindex (alphabetical index) and fmt=forum (forum postings).


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:


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

See Also

<< Conditional markup | Documentation Index | Page variables >>

Retrieved from
Page last modified on March 10, 2006, at 06:50 PM EST