Many Matters : PmWiki/Page Lists

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

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

fmt=

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

fmt=#bygroup - Display pages alphabetically within groups
fmt=#simple - Display a simple ordered list of pages
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 the groups of the pages in the list
fmt=#include - Display the contents of each page in the list (note, this could take a very long time for long lists!)

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:

fmt=#custom uses the #custom section from Site.PageListTemplates (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.

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

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
order=-name - reverse alphabetical listing
order=title - sorted by title
order=-time - most recently changed pages first
order=ctime - time of page creation
order=size - sort by page size
order=group,title - sort by title within groups
order=random - shuffle the pages into random sequence

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

Many Matters