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
<< Categories | Documentation Index | Deleting pages >>