From [UE ENSAM] Robotique

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.

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:

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:

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.

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