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:)
See Also
<< Conditional markup | Documentation Index | Page variables >>
