%audience% 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.
(: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.
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".
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 :)
Name and group parameters can contain wildcard characters that display only pages matching a given pattern:
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* :)
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:)
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.
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.
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.
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:)
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:)
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 (default order)
order=title - sorted alphabetically by title rather than names
order=time - most recently changed pages last
order=ctime - time of page creation (see note)
order=size - sort by page size (not file size), smallest pages first.
order=group,title - sort by title within groups
order=random - shuffle the pages into random sequence
->Note: fmt=trail results in an unordered pagelist, i.e. the trail order is preserved in the pagelist. So PmWiki's alphabetical default order does not apply in this case.
->Note: ctime was added to pages only from pmwiki 2.1.beta15 onwards, pages created by earlier versions don't carry a ctime attribute and can't be sorted that way.
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:)
Display the "top twenty" biggest cookbook pages:
(:pagelist group=Cookbook order=-size count=20 :)
The (:searchbox:) directive generally accepts the same parameters as (:pagelist:), with the following differences:
value='search string'. That search string is displayed in the input text and can be modified by when the search is run.
value='', to the markup for each searchbox will prevent a search string for one box from populating all of the other boxes.
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=#custom uses the #custom section from Site.PageListTemplates, Site.LocalTemplates, or current page (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.
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.
In addition, the Cookbook:Cookbook has other recipes for special fmt= options, including fmt=dictindex (alphabetical index) and fmt=forum (forum postings).
%trail% <<|Documentation Index|>>
Q: How can I configure my site to always exclude wiki-related pages from searches?
A: Try the following in your local/config.php file. See also Cookbook:SearchPatterns.
->
## Exclude Certain pages / groups from search results. $SearchPatterns['default'][] = '!\\.(All)?Recent(Changes|Uploads|Comments)$!'; $SearchPatterns['default'][] = '!\\.Group(Print)?(Header|Footer|Attributes)$!'; $SearchPatterns['default'][] = '!\\.(Left|Right|Side)(Bar|Menu|Note)$!'; $SearchPatterns['default'][] = '!^Site\\.!'; $SearchPatterns['default'][] = '!^PmWiki\\.!';
If you add $SearchPatterns['default']... to exclude groups and pages from pagelist and search output, you can include the omitted pages by using "list=all" in the pagelist or search parameters.