PmWiki / PageLists

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 search 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 (-) can be used to indicate things that should be excluded. 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.

NOTE: Pagelist does not evaluate MarkupExpressions when working with PTVs. So if your page text variables is defined using a markup expression to set the value, pagelist will see the literal values of the text of your markup expression rather than the result of your expression. (e.g., the PTV definition (:foo:{(substr abcdef 2 4)}:) will be seen by pagelist as an open-curly-brace followed by an open-paren followed by s-u-b-s-t-r, etc. rather than being seen as b-c-d-e) Any processing of the markup expression in the output of your pagelist occurs in subsequent rules (after pagelist) within the context of the current page and thus these values cannot be used for sorting or selecting pages. (source)

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, group, link, and category 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* :)
All Cookbooks with names beginning with a A and a B letter
note the different specifiers used for the same result
(:pagelist group=Cookbook name=A*,B*   :)
(:pagelist name=Cookbook.A*,Cookbook.B*   :)
(:pagelist group=Cookbook name=[AB]*   :)
(:pagelist name=Cookbook.[AB]*   :)
Pages in the categories Media or Images (at least one)
(:pagelist category=Media,Images  :)
Pages in the categories Media and Images (both)
(:pagelist category=+Media,+Images  :)

If you want to use multiples conditions you need to use commas to delimit the string. For example

key="one value,another value"

trail=

The "trail=" option obtains the list of pages to be displayed from a trail index.

(:pagelist trail=PmWiki.DocumentationIndex order=-time:)
(: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.

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:

These formats are defined by page list templates, which can be customized.

This format is not predefined by a page list template:

link= and category=

The "link=" and "category=" arguments implement "backlinks" -- i.e., it returns a list of pages with a link to the target, or declared in the category. It's especially useful for category pages and finding related pages.

The category=Name argument differs from link=Category.Name as it only lists pages declared in the category with the markup [[!Name]], and does not include pages simply linking to [[Category/Name]] (unless they also contain [[!Name]]).

(:pagelist link=PmWiki.DocumentationIndex:)
(:pagelist link={$FullName}:)
(:pagelist category=Skins:)

Since PmWiki 2.3.0, link= and category= accept multiple and negative targets and wildcard lists, see the section Wildcards.

Note, link= and category= will ignore the directives (:if...:), (:include...:), (:redirect...:), (:pagelist...:), and page text variable directives, while searching for links in a page. That means links in included pages will not be found, and links inside non-displayed conditional markup will be found. See PageTextVariables for ways to hide a link on a page while still allowing link= to find it.

Note: The new category= argument requires all pages containing [[!Category]] links to be reindexed. See the recipe Cookbook:ReindexCategories which can automate this.

count=

The "count=" option provides the ability to

A simple bullet list of ten most recently modified pages

(:pagelist trail=Site.AllRecentChanges count=10 fmt=#simple:)

Display the first ten pages of a list

count=10 # display the first ten pages of list

Negative numbers specify pages to be displayed from the end of the list:

count=-10 # display last ten pages of list

Ranges may be specified using '..', thus:
count=1..10       # first ten pages of list
count=5..10       # 5th through 10th pages of list
Negative numbers in ranges count from the end of the list:

count=-10..-5 # 10th from end, 9th from end, ..., 5th from end

Omitting the start or end of the range uses the start or end of the list:
count=10..        # skip first ten pages
count=..10        # 1st through 10th page of list
count=-10..       # last ten pages of list
count=..-10       # all but the last nine pages
Ranges can be reversed, indicating that the order of pages in the output should likewise be reversed:
count=5..10       # 5th through 10th pages of list
count=10..5       # same as 5..10 but in reverse sequence
count=-1..1       # all pages in reverse sequence
"Reverse sequence" here refers to the sequence after any sorting has taken place. Therefore the three directives to the right are equivalent:
(:pagelist order=-name count=10:)
(:pagelist order=-name count=1..10:)
(:pagelist order=name count=-1..-10:) 

wrap=

The "wrap" option has the values, none and inline.

With "wrap=inline" and "wrap=none", the output from pagelist (markup or HTML) is directly embedded in a page's markup without any surrounding <div> class=...</div> tags.

With "wrap=inline", any surrounding <ul> is continued. Without "wrap=inline", the HTML output starts a new <ul>. This is important if you want to get a second level <ul> produced by the page list since starting a new <ul> with "**" doesn't yield a second level <ul> but <dl><dd><ul>...

"wrap=inline" likely has other effects since it suppresses the call to $FPLTemplateMarkupFunction (being MarkupToHTML by default).

class=

By default, a pagelist has the 'fpltemplate' class. The 'bygroup', 'simple', 'group' and 'title' page list formats have specific class names fplbygroup, fplsimple etc. You can set any class using the class= parameter or by setting the $FPLFormatOpt array.

request=

With (:pagelist [other parameters] request=1:) you can override most pagelist parameters, by providing request parameters in the URL. For example, (:pagelist order=name request=1:) will normally sort the list by name. But if the page's URL contains ?order=time, the list will be sorted by time. If the URL contains ?order=, the list will be unordered. Note: In the URL, encode any "#"s that are in your parameters as "%23". Since this parameter gives users who don't have edit rights the ability to run a pagelist of their choosing, consider its security implications for your website before using it.

Since version 2.2.71, it is possible to explicitly allow only certain parameters that can be overridden, or to disallow some parameters to be overridden. If you need this, instead of 1, enter the parameter names.

Allow all parameters to be overridden:
(:pagelist request=1:)
Allow only 'order' and 'count' parameters to be overridden:
(:pagelist request=order,count:)
Allow all parameters to be overridden, except 'fmt' and 'trail', note the "minus" sign before each forbidden parameter:
(:pagelist request=-fmt,-trail:)

req=1

The req=1 parameter requires that search terms be posted (that is, that the user presses "search" on a search form, or follows a link with additional parameters like [[Page?q=terms&order=-name]]) before the pagelist is executed. Note that (:pagelist request=1 req=1:) works mostly like (:searchresults:) without the lines "Results of search for ..." and "X pages found out of Y pages searched". Both "request=1" and "req=1" are needed.

When a search is performed, either via a searchbox directive, or via the search form of the skin, if the page contains a "searchresults" directive, that page will be used to display the results of the search; if the page doesn't have a "searchresults" directive, the page Site.Search will be used to display the results.

passwd=

The "passwd" option returns only those pages that have some sort of password attribute on them.

if=

The "if" option allows a condition to be specified as part of the pagelist processing, rather than from within the page list template. Only those pages for which the condition is true are retrieved. Anything that could go within an (:if ...:) can be used as a condition. For example

  (:pagelist if="date {(ftime %GW%V {*$Name})} {=$Name}" :)

returns all of the pages where the name is in the same week as that of the current page.

If any arguments within the quotes could contain a space they must be quoted:

  (:pagelist if="date 2009-01-01..2009-12-31 '{=$:Mydate}'" :)

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, and you can create your own custom pagelist sort order:

Also, the order= option allows custom ordering functions to be written.

cache=0

Pagelist has the capability to cache lists which greatly speeds up processing (when $PageListCacheDir is set). Every once in a while this caching can result in undesired results. Specifying cache=0 disables caching.

Specifying variables as parameters

You can also specify variable values inline with the pagelist statement, and refer to the variables in the template using the {$$variable1} format:

(:pagelist fmt=#pagelist variable1="value" variable2="value2":)

This assumes that a site has $EnableRelativePageVars enabled (default since 2.2.9).

For example, in the template:

>>comment<<
[[#tvars]]
(:template default count=1 ParamName=Simon:)
Hi, {$$ParamName}, how are you today?
[[#tvarsend]]
>><<

(:template default count=1 ParamName=Simon:) Hi, {$$ParamName}, how are you today?

This gives:

(:pagelist fmt=#tvars ParamName="Sam":)

(:pagelist fmt=#tvars ParamName="Sally":)

(:pagelist fmt=#tvars:)

Hi, Sam, how are you today?

Hi, Sally, how are you today?

Hi, Simon, how are you today?

See also $EnableUndefinedTemplateVars.

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:)

The Searchbox Directive

The (:searchbox:) directive generally accepts the same parameters as (:pagelist:) and (:input search:) directives:

The additional parameter label="Label" can be used to change the label of the associated submit button:

 (:searchbox label="Search this wiki":)

Use label="" to remove the submit button (users need to press "Enter" to search).

By default, the input field has the "text" type for compatibility with HTML/XHTML. Alternatively, you can set it to the "search" input type for HTML5, see $SearchBoxInputType (some HTML5 skins already set this).

The Searchresults directive

The (:searchresults:) directive generally accepts the same parameters as (:pagelist:) and (:input search:) directives.

Customizing "Results of search for..." and "3 pages found out of..."

To change the text surrounding the search results, customize the following and add it to local/config.php or $FarmD/local/farmconfig.php. Note that 'en' should be changed to the localized language.

XLSDV('en', array(
        'SearchFor' => 'Results of search for <em>$Needle</em>:',
        'SearchFound' => 
                '$MatchCount pages found out of $MatchSearched pages searched.'
));

Alternatively, adjust the 'SearchFor' and 'SearchFound' phrases in your translation pages.

The $SearchResultsFmt variable can also be set in local/config.php or $FarmD/local/farmconfig.php.

SDV($SearchResultsFmt, "<div class='wikisearch'>\$[SearchFor]
  <div class='vspace'></div>\$MatchList
  <div class='vspace'></div>\$[SearchFound]</div>");

You can remove the lines above and below the generated list by adding this in config.php:

$SearchResultsFmt = '$MatchList';

See Also

FAQ

How PmWiki opens pages with PageStore?

When PmWiki needs to open a file for reading, it will ask the PageStore, objects one after another, in the order you have defined them in config.php, if they have MyGroup.MyPage. The first PageStore object that finds this page will return it and if there are more PageStores they will be not bothered.

When you define a PageStore object with paths like wiki.d/{$Group}/{$FullName} and then ask "is there a page MyGroup.MyPage", the PageStore only checks "is there a file wiki.d/MyGroup/MyGroup.MyPage" so it will only look in the wiki.d/MyGroup sub-directory, not in other subdirectories.

When you write a page, only the first PageStore object is used, that is usually $WikiDir. This way we can have documentation in wikilib.d but if you modify a page from the PmWiki or Site groups on your wiki, it will be saved in wiki.d and from now on only the file in wiki.d will be read and written.

What is the behavior of pagelist and searchresults when only name or word is provided?

Both pagelist and searchresults are searching for all groups unless either (there is a group=ThisGroup argument in the markup or in the search field), or (you have (:template default group=SomeGroup,{*$Group}:) in the pagelist template), or (there is a request=1 argument in the markup and there is somehow a $_REQUEST['group'] variable, eg from a search form or from the url), or (you set some $SearchPatterns['xy'] and list=xy), or (set a default $MakePageListOpt['group'] or $SearchBoxOpt['group']).

If one option is not used, then this option should not be predefined. If there is no needle show all pages; if group= is not used show all groups; if name= is not used show all names; if link= is not used show pages linking or not linking to anywhere; if count= is not used show all pages instead of a portion of them. (The only exception is the order= option which defaults to order=name because without it the results may be ordered inconsistently between page reloads, especially bad if you also use count=21..30.)

How can a custom function retrieve the results of a pagelist as an array?

See this thread on the mailing list.


This page may have a more recent version on pmwiki.org: PmWiki:PageLists, and a talk page: PmWiki:PageLists-Talk.