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
without any arguments shows a bulleted list of all pages, as links, ordered alphabetically and in groups.
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 Documentation Index trail that contain the word "apple" but not "pie".
With page text variables
You can also use page text variables as a key to list pages according to the existence of a page text variable. Eg :
(:pagelist $:pagetextvar=avalue:)
lists pages having $:pagetextvar set to avalue.
Minus sign (-), wildcards (?*) and a comma separated list of values also works when specifying a selection based on pagetextvariables. Eg :
(:pagelist $:apagetextvar=t*,-test:)
lists pages having $:apagetextvar like 't*' but not 'test'.
Examples:
| PTV is set (is not empty): | (:pagelist $:MyPageTextVariable=- :) |
PTV is empty or not set:
(ie, is not set to one char followed by 0 or more chars) | (:pagelist $:MyPageTextVariable=-?* :) |
| PTV is not VALUE: | (:pagelist $:MyPageTextVariable=-VALUE :) |
| PTV is set and not YES: | (:pagelist $:MyPageTextVariable=?*,-YES :) |
Be aware that if using (:pagelist $:MyPTV=$:YourPTV :) PTVs include PmWiki formatting, so you may not get the matches you expect. Currently the only way around this is to use wild cards, so if the formatting is embedded you may be out of luck.
With page variables (PV)
Page variables can be used within pagelists in the same way as page text variables. See Page Text Variables above for more details. Simply use $var instead of $:var.
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* :)
|
| All Cookbooks with names beginning with a A and a B letter
note the different separators used for the same result
|
(:pagelist group=Cookbook name=A*,B* :)
(:pagelist group=Cookbook name="A* B*" :)
(:pagelist group=Cookbook name=[AB]* :)
(:pagelist group=Cookbook, name=[AB]* :)
|
If you want to use multiples conditions in name you need to use quotes or commas to delimit the string.
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. Note that list=normal also excludes the current page.
- "
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 by page list templates, which can be customized.
This format is not predefined by a page list template:
fmt=count - Display the number of pages in the list (note the absence of the "#").
link=
The "link=" option implements "backlinks" -- i.e., it returns a li