version=pmwiki-2.2.71 ordered=1 urlencoded=1
author=Daniel Julivert
charset=UTF-8
csum=Documented the titlespaced format
ctime=1138643894
name=PmWiki.PageLists
rev=242
targets=PmWiki.PageListTemplates,PmWiki.DocumentationIndex,PmWiki.PageTextVariables,PmWiki.MarkupExpressions,PmWiki.WikiTrails,Cookbook.SearchResults,Site.PageListTemplates,PmWiki.Categories,Cookbook.PageListMultiTargets,PmWiki.ConditionalMarkup,PmWiki.CustomPagelistSortOrder,PmWiki.PageVariables,PmWiki.PagelistVariables,PmWiki.Internationalizations,Cookbook.PagelistTemplateSamples,Cookbook.Forms,Cookbook.CustomPagelistSortOrderFunctions,PmWiki.PageLists,PmWiki.PageDirectives,PmWiki.Search
text=(:Audience: authors, admins (intermediate) :)%0a(:Summary:Listing pages by multiple criteria with templated output:)%0aPmWiki 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.%0a%0aThe [@(: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 [[#searchbox|below]].%0a%0a!! Basic syntax%0a%0a* [@(:pagelist:)@] %0a->without any arguments shows a bulleted list of all pages, as links, ordered alphabetically and in groups.%0a* @@[=(:=]pagelist [[#pagelistgroup|group]]=''ab'' \%0a  [[#pagelistname|name]]=''cd'' \%0a  [[#pagelistfmt|fmt]]=''[[page list templates|template]]''  \%0a  [[#pagelistlist|list]]=''ef'' \%0a  [[#pagelistorder|order]]=''gh'' \%0a  [[#pagelistcount|count]]=''123'' \%0a  [[#pagelistlink|link]]=''ij'' \%0a  [[#pagelisttrail|trail]]=''kl''  \%0a  [[#pagelistwrap|wrap]]=''mn''  \%0a  [[#pagelistpasswd|passwd]]=''op''  \%0a  [[#pagelistif|if]]=''qr''  \%0a  [[#pagetextvariables|$:''ptv'']]=''st'' \%0a  [[#pagevariables|$''pv'']]=''uv'' \%0a  [[#pagelistcache|cache]]=0 \%0a  ''[[#pagelistarg|argument]]1''&nbsp;-''[[#pagelistarg|argument]]2'' ''etc'' \%0a  [[#includevariable|variable]]=''value'' \%0a  [[#pagelistclass|class]]=''class'' \%0a  [[#pagelistrequest|''request=1'']] \%0a  [[#pagelistreq|''req=1'']] \%0a  :)@@ %0a->shows a pagelist according to the  parameters supplied. Parameters are optional.%0a* @@[=(:=][[#searchbox|searchbox]] value=''abc'' size=''99'' target=''def'' label="label":)@@%0a* @@[=(:=][[#searchresults|searchresults]]:)@@%0a%0a!! Parameters%0a[[#pagelistarg]]%0aAny 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.%0a%0aThe minus sign (-) can be used to indicate things that should be excluded. Thus%0a->[@(:pagelist trail=PmWiki.DocumentationIndex list=normal apple -pie:)@]%0alists all "normal" pages listed in the [[Documentation Index ]] trail that contain the word "apple" but not "pie".%0a%0a!!![[#pagetextvariables]]With page text variables%0aYou can also use [[page text variables]] as a ''key'' to list pages according to the existence of a page text variable. Eg : %0a->[@(:pagelist $:pagetextvar=avalue:)@]%0alists pages having ''$:pagetextvar'' set to ''avalue''.%0a[[%3c%3c]]%0aMinus sign (-), wildcards (?*) and a comma separated list of values also works when specifying a selection based on pagetextvariables. Eg :%0a->[@(:pagelist $:apagetextvar=t*,-test:)@]%0alists pages having $:apagetextvar like 't*' but not 'test'.%0a[[%3c%3c]]%0aExamples:%0a||width=* class="tabtable" rules=rows%0a||PTV is set (is not empty): ||[@(:pagelist $:MyPageTextVariable=- :)@]||%0a||PTV is empty or not set:[[%3c%3c]]&nbsp;(ie, is not set to one char followed by 0 or more chars) ||[@(:pagelist $:MyPageTextVariable=-?* :)@]||%0a||PTV is not VALUE:          ||[@(:pagelist $:MyPageTextVariable=-VALUE :)@]||%0a||PTV is set and not YES:    ||[@(:pagelist $:MyPageTextVariable=?*,-YES :)@]||%0aBe 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.%0a%0aNOTE: Pagelist does not evaluate [[PmWiki/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. ([[http://thread.gmane.org/gmane.comp.web.wiki.pmwiki.user/60968/focus=60970|source]])%0a%0a!!![[#pagevariables]]With page variables (PV)%0a%0aPage variables can be used within pagelists in the same way as page text variables.  See [[#pagetextvariables|Page Text Variables]] above for more details.  Simply use $var instead of $:var.%0a%0a!!![[#pagelistgroup]] group= and [[#pagelistname]]name= %0a%0aThe "[@group=@]" and "[@name=@]" parameters limit results to pages in a specific group or with a specific name:%0a(:table class='tabtable' rules=rows:)%0a(:cellnr:)All pages in the Pmwiki group:%0a(:cell:)[@(:pagelist group=PmWiki :)@]%0a(:cellnr:)All pages except those in the PmWiki or Site groups:%0a(:cell:)[@(:pagelist group=-PmWiki,-Site :)@]%0a(:cellnr:)All RecentChanges pages%0a(:cell:)[@(:pagelist name=RecentChanges :)@]%0a(:cellnr:)All pages except RecentChanges%0a(:cell:)[@(:pagelist name=-RecentChanges :)@]%0a(:tableend:)%0a%0a!!! Wildcards%0aName and group parameters can contain ''wildcard'' characters that display only pages matching a given pattern:%0a* An asterisk (*) represents zero or more characters%0a* A question mark (?) represents exactly one character%0a%0aExamples:%0a(:table class='tabtable' rules=rows:)%0a(:cell:)All pages in any group beginning with "PmWiki"%0a(:cell:)[@(:pagelist group=PmWiki* :)@]%0a(:cellnr:)All pages in any group beginning with "PmWiki", except for Chinese%0a(:cell:)[@(:pagelist group=PmWiki*,-PmWikiZh :)@]%0a(:cellnr:)All pages in the PmCal group with names starting with "2005":%0a(:cell:)[@(:pagelist name=PmCal.2005* :)@]%0a(:cellnr:)All Cookbooks with names beginning with a A and a B letter%0a->note the different separators used for the same result%0a(:cell:)[@%0a(:pagelist group=Cookbook name=A*,B*   :)%0a(:pagelist group=Cookbook name="A* B*" :)%0a(:pagelist group=Cookbook name=[AB]*   :)%0a(:pagelist group=Cookbook, name=[AB]*   :)@]%0a(:tableend:)%0a%0aIf you want to use multiples conditions in name you need to use quotes or commas to delimit the string. For example%0a-> [@key="one value,another value"@]%0a%0a!!![[#pagelisttrail]] trail= %0aThe "[@trail=@]" option obtains the list of pages to be displayed from a [[WikiTrail(s)]]:%0a* Display pages in the documentation by modification time%0a->[@(:pagelist trail=PmWiki.DocumentationIndex order=-time:)@]%0a* Display five most recently changed pages%0a->[@(:pagelist trail=RecentChanges count=5:)@]%0a%0a!!![[#pagelistlist]] list= %0a%0aThe "[@list=@]" option allows a search to include or exclude pages according to predefined patterns set by the administrator.  %0a* "[@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.%0a* "[@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.%0a* Wiki administrators can define custom lists via the $SearchPatterns array (see [[Cookbook:SearchResults]]).%0a%0a!!![[#pagelistfmt]] fmt= %0a%0aThe "[@fmt=@]" option determines how the resulting list should be displayed.  %0aPmWiki [[Site/PageListTemplates|predefines]] several formats:%0a* @@fmt=#bygroup@@ - Display pages within groups (default format)%0a* @@fmt=#simple@@  - Display a simple ordered list of pages in the form Group.Name%0a* @@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).%0a* @@fmt=#titlespaced@@   - Display a list of pages by page title, like above, but with spaces between the words in the title.%0a* @@fmt=#group@@   - Display a list of wikigroups (without listing the pages in the groups)%0a* @@fmt=#include@@ - Display the contents of each page in the list (note, this could take a very long time for long lists!)%0aThese formats are defined by [[page list templates]], which can be customized.%0a%0aThis format is not predefined by a page list template:%0a* @@fmt=count@@ - Display the number of pages in the list (note the absence of the "#"). In a trail, @@fmt=count@@ counts existing and non-existing pages ; to limit count to existing pages, use : @@if="exists {=$FullName}" fmt=count@@ [-([[http://thread.gmane.org/gmane.comp.web.wiki.pmwiki.user/58621|mailing list]])-].%0a%0a%0a!!![[#pagelistlink]] link= %0a%0aThe "[@link=@]" option implements "backlinks" -- i.e., it returns a list of pages with a link to the target.  It's especially useful for [[categor(ies)]]y pages and finding related pages.%0a%0a* all pages with a link to PmWiki.DocumentationIndex%0a->[@(:pagelist link=PmWiki.DocumentationIndex:)@]%0a* all pages with links to the current page%0a->[@(:pagelist link={$FullName}:)@]%0a* all pages in the "Skins" category%0a->[@(:pagelist link=Category.Skins:)@]%0a%0aNote that the @@link=@@ parameter doesn't accept multiple or negative targets and wildcard lists. For these see Cookbook:PageListMultiTargets.%0a%0aAlso, @@link=@@ 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.%0a%0a!!![[#pagelistcount]] count= %0a%0aThe "[@count=@]" option provides the ability to%0a* limit the pagelist to a specific number of pages%0a* subsets of a list%0a* return items from the end of a list, subsets of a list%0a* display pages in reverse sequence%0a%0a(:table class=tabtable rules=rows:)%0a(:cellnr:)A simple bullet list of ten most recently modified pages%0a(:cell:)%0a[@(:pagelist trail=Site.AllRecentChanges count=10 fmt=#simple:)@]%0a(:cellnr:)Display the first ten pages of a list%0a(:cell:)%0a[@count=10          # display the first ten pages of list@]%0a(:cellnr:)Negative numbers specify pages to be displayed from the end of the list:%0a(:cell:)%0a[@count=-10         # display last ten pages of list@]%0a(:cellnr:)Ranges may be specified using '..', thus:%0a(:cell:)%0a[@count=1..10       # first ten pages of list%0acount=5..10       # 5th through 10th pages of list@]%0a(:cellnr:)Negative numbers in ranges count from the end of the list:%0a(:cell:)%0a[@count=-10..-5     # 10th from end, 9th from end, ..., 5th from end@]%0a(:cellnr:)Omitting the start or end of the range uses the start or end of the list:%0a(:cell:)%0a[@count=10..        # skip first ten pages%0acount=..10        # 1st through 10th page of list%0acount=-10..       # last ten pages of list%0acount=..-10       # all but the last nine pages@]%0a(:cellnr:)Ranges can be reversed, indicating that the order of pages in the output should likewise be reversed:%0a(:cell:)%0a[@count=5..10       # 5th through 10th pages of list%0acount=10..5       # same as 5..10 but in reverse sequence%0acount=-1..1       # all pages in reverse sequence@]%0a(:cellnr:)"Reverse sequence" here refers to the sequence ''after'' any sorting has taken place.  Therefore the three directives to the right are equivalent:%0a(:cell:)%0a[@(:pagelist order=-name count=10:)%0a(:pagelist order=-name count=1..10:)%0a(:pagelist order=name count=-1..-10:) @]%0a(:tableend:)%0a%0a!!![[#pagelistwrap]] wrap=%0aThe "[@wrap@]" option has the values, ''none'' and ''inline''.%0a%0aWith "wrap=inline" and "wrap=none", the output from pagelist (markup or HTML) is directly embedded in a page's markup without any surrounding %3cdiv> class=...%3c/div> tags.%0a%0aWith "wrap=inline", any surrounding %3cul> is continued. Without "wrap=inline", the HTML output starts a new %3cul>. This is important if you want to get a second level %3cul> produced by the page list since starting a new %3cul> with "**" doesn't yield a second level %3cul> but %3cdl>%3cdd>%3cul>...%0a%0a"wrap=inline" likely has other effects since it suppresses the call to $FPLTemplateMarkupFunction (being MarkupToHTML by default).%0a%0a!!![[#pagelistclass]] class=%0aBy 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.%0a%0a!!![[#pagelistrequest]] request=1%0aWith [@(:pagelist [other parameters] request=1:) @] you can override most pagelist parameters, by providing request parameters in the URL. %0aFor 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 "%2523". 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.%0a%0aSince version 2.2.71, it is possible to explicitely 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.%0a%0aAllow all parameters to be overridden: [@%0a(:pagelist request=1:)%0a@]%0a%0aAllow only 'order' and 'count' parameters to be overridden: [@%0a(:pagelist request=order,count:)%0a@]%0a%0aAllow all parameters to be overridden, except 'fmt' and 'trail', note the "minus" sign before each forbidden parameter: [@%0a(:pagelist request=-fmt,-trail:)%0a@]%0a%0a!!![[#pagelistreq]] req=1%0aThe @@req=1@@ parameter requires that search terms be posted (that is, that the user presses "search" on a search form) 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.%0a%0a!!![[#pagelistpasswd]] passwd=%0aThe "[@passwd@]" option returns only those pages that have some sort of password attribute on them.%0a%0a!!![[#pagelistif]] if=%0aThe "[@if@]" option allows a condition to be specified as part of the pagelist processing, rather than from within the [[page list template(s)]]. Only those pages for which the condition is true are retrieved. Anything that could [[ConditionalMarkup | go within an [@(:if ...:)@]]] can be used as a condition. For example%0a%0a  [@(:pagelist if="date {(ftime %25GW%25V {*$Name})} {=$Name}" :)@]%0a%0areturns all of the pages where the name is in the same week as that of the current page.%0a%0aIf any arguments within the quotes could contain a space they must be quoted:%0a%0a  [@(:pagelist if="date 2009-01-01..2009-12-31 '{=$:Mydate}'" :)@]%0a%0a!!![[#pagelistorder]] order=%0a%0aThe "[@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 [[(PmWiki:)custom pagelist sort order]]:%0a* [@order=name@] - alphabetically by name (default order)%0a* [@order=$Name@] - alphabetically by name across groups%0a* [@order=title@] - alphabetically by title rather than names%0a* [@order=time@] - most recently changed pages '''last'''%0a* [@order=ctime@] - time of page creation (see note)%0a* [@order=group,title@] - by multiple criteria, in this instance sort by title within groups%0a* [@order=random@] - shuffle the pages into random sequence%0a* [@order=$:pagetextvarname@] - alphabetically by [[PageTextVariables|page text variable]] value%0a* [@order=$pagevarname@] - alphabetically by [[PageVariables|page variable]] value%0a%0aAlso, the [@order=@] option allows custom ordering functions to be written.%0a%0a* Note: trail= preserves the order of the pages as they appear on the trail (unless you've specified order= explicitly or there is a default order in the page list template). So PmWiki's alphabetical default order does not apply when trail= is specified.%0a* 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.%0a%0a[[#pagelistcache]]%0a!!! cache=0%0aPagelist has the capability to cache lists which greatly speeds up processing (when [[PmWiki/PagelistVariables#PageListCacheDir|$PageListCacheDir]] is set).  Every once in a while this caching can result in undesired results.  Specifying @@cache=0@@ disables caching.%0a%0a%0a[[#includevariable]]%0a!!!! Specifying variables as parameters%0aYou can also specify variable values inline with the pagelist statement, and refer to the variables in the template using the [@{$$variable1}@] format:%0a-> [@(:pagelist fmt=#pagelist variable1="value" variable2="value2":)@]%0a%0aThis assumes that a site has $EnableRelativePageVars enabled, which is recommended in PmWiki 2.2.0 -- but disabled by default to help people upgrading from 2.1.x.%0a%0aFor example, in the template:%0a%0a(:markup:)%0a>>comment%3c%3c%0a[[#tvars]]%0a(:template default count=1 ParamName=Simon:)%0aHi, {$$ParamName}, how are you today?%0a[[#tvarsend]]%0a>>%3c%3c%0a(:markupend:)%0a%0aThis gives:%0a%0a(:markup class=horiz:)%0a(:pagelist fmt=#tvars ParamName="Sam":)%0a%0a(:pagelist fmt=#tvars ParamName="Sally":)%0a%0a(:pagelist fmt=#tvars:)%0a(:markupend:)%0a%0a''See also $EnableUndefinedTemplateVars.'' %0a%0a!! Examples%0a%0aInclude the contents of a random page from the Banners group:%0a->[@(:pagelist group=Banners order=random count=1 fmt=#include list=normal:)@]%0a%0aDisplay a simple list of the last ten recently changed pages:%0a->[@(:pagelist trail=Site.AllRecentChanges count=10 fmt=#simple:)@]%0a%0aDisplay the "top twenty" biggest cookbook pages:%0a->[@(:pagelist group=Cookbook order=-size count=20 :)@]%0a%0a!![[#searchbox]] The Searchbox Directive%0a%0aThe [@(:searchbox:)@] directive generally accepts the same parameters as [@(:pagelist:)@] and [@(:input text:)@] directives:%0a* Pagelist parameters can be added to the input text of a searchbox (or to the markup, or both)%0a* Input text box parameters can be added to the searchbox markup%0a** An initial search string can be specified in the searchbox markup, but it must be in the form @@value='search string'@@.  That search string is displayed in the input text and can be modified by when the search is run.%0a** The size of the text input field can be specified with the size parameter, where "size=40" would specify the current default value.%0a*** Tip:  If more than one searchbox appears on a page, adding a blank initial value like this @@value=''@@, to the markup for each searchbox will prevent a search string for one box from populating all of the other boxes.%0a* The target page for displaying searchbox results can be set with the parameter @@target=''GroupName.PageName''@@.  The default is the current page. %0a* The entire searchbox form can be overridden by defining the $SearchBoxFmt variable in one's configuration file.  If $SearchBoxFmt is defined, then the parameters to [@(:searchbox:)@] are ignored, and the content of the $SearchBoxFmt variable are used instead.%0a%0aThe additional parameter @@label="Label"@@ can be used to change the label of the associated submit button:%0a%0a [@(:searchbox label="Search this wiki":)@]%0a%0a[[#searchresults]]%0a!! The Searchresults directive%0aThe [@(:searchresults:)@] directive generally accepts the same parameters as [@(:pagelist:)@] and [@(:input text:)@] directives.%0a%0a%0a!!! Customizing "Results of search for..." and "3 pages found out of..."%0a%0aTo 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.%0a%0a->[@XLSDV('en', array(%0a        'SearchFor' => 'Results of search for %3cem>$Needle%3c/em>:',%0a        'SearchFound' => %0a                '$MatchCount pages found out of $MatchSearched pages searched.'%0a));@]%0a%0aAlternatively, adjust the 'SearchFor' and 'SearchFound' phrases in your [[Internationalizations|translation pages]].%0a%0aThe $SearchResultsFmt variable can also be set in ''local/config.php'' or ''$FarmD/local/farmconfig.php''.%0a%0a->[@SDV($SearchResultsFmt, "%3cdiv class='wikisearch'>\$[SearchFor]%0a  %3cdiv class='vspace'>%3c/div>\$MatchList%0a  %3cdiv class='vspace'>%3c/div>\$[SearchFound]%3c/div>");@]%0a%0a!! See Also%0a* [[Site.PageListTemplates]] - default pmwiki pagelist templates%0a* [[Cookbook:PagelistTemplateSamples]] - contributed pagelist template samples%0a* [[PmWiki/PageListTemplates]] - how to create custom pagelist templates for the fmt= option%0a* [[(PmWiki/)PagelistVariables]] - ''local/config.php'' customizations%0a* [[Cookbook:Forms]] - documentation for [@(:input text:)@] markup, which applies to [@(:searchbox:)@]%0a* [[(PmWiki:)CustomPagelistSortOrder]] - creating custom order sort functions%0a* [[Cookbook:CustomPagelistSortOrderFunctions]] - {Cookbook.CustomPagelistSortOrderFunctions$:Summary}%0a* [[Cookbook:PageListMultiTargets]] - {Cookbook.PageListMultiTargets$:Summary}%0a* [[Cookbook:SearchResults]] - {Cookbook.SearchResults$:Summary}%0a* [[PageDirectives#attachlist]] - display a list of attachments%0a* [[PmWiki.Search]] - {Search$:Summary}
time=1421408157
