version=pmwiki-2.2.120 ordered=1 urlencoded=1 author=Petko charset=UTF-8 csum=$$EachCount ctime=1176759249 name=PmWiki.PageListTemplates rev=43 targets=PmWiki.PageLists,Site.PageListTemplates,Site.LocalTemplates,PmWiki.PagelistVariables,Cookbook.PagelistTemplateSamples,PmWiki.PageVariables,PmWiki.PageTextVariables,Cookbook.DictIndex,Cookbook.SimpleForum,Cookbook.Cookbook text=(:Summary: Creating [[PmWiki/page list(s)]] format templates:)%0a!! Default [[page list(s)]] templates%0a%0aPmWiki's default templates for [[page lists]] are in [[Site.PageListTemplates]], which is replaced during upgrades. %0aThese default templates can be supplemented or overridden with custom templates stored in other locations. %0a %0aPmWiki's default configuration looks for templates in the following locations in the following order:%0a# the page name specified as part of the template name%0a# the current page body%0a# [[Site.LocalTemplates]], %0a# [[Site.PageListTemplates]]%0aIf the pagelist is defined in a sidebar, group header or footer, etc, the page name must be specified as part of the template name.%0aAdministrators can change those locations by using the $FPLTemplatePageFmt variable. %0a%0aIf the template is on the current page, the current page must be saved for changes involving the template to show up ''(preview alone will not work)''.%0a%0a!! Custom page list templates%0aCustom templates are used in the same way as default templates: by referencing the desired format with the @@fmt=#''anchor''@@ option. %0aThere are several ways to indicate which template to use:%0a* [@fmt=#custom@] uses the #custom section from the current page, [[Site.LocalTemplates]], or [[Site.PageListTemplates]], (sections are denoted by [@[[#custom]]@] anchors.%0a* [@fmt=MyTemplatePage#custom@] uses a custom format from page @@MyTemplatePage@@ from its @@#custom@@ section.%0a* [@fmt=MyTemplatePage@] uses a custom format from the entire page @@MyTemplatePage@@.%0a* [@fmt=custom@] uses custom format which is defined in a cookbook script as ''custom''.%0a%0aSee Cookbook:PagelistTemplateSamples for examples of custom pagelist formats.%0a%0a!! Creating page list templates%0aA pagelist template contains standard pmwiki markup. %0aWhen 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. %0a%0a[[#specialreferences]]%0a!!! Special references %0aDuring the page list iteration pmwiki sets 3 special page references: '''=''', '''%3c''' and '''>'''. %0aThese special page references are updated on each pagelist iteration and can be used with the [[page variables]] syntax, such as ''{=$variable}'', to define a pagelist template which will format the pagelist output. The meaning of the special references are:%0a||width=*%0a|| = ||current page ||so ''[@{=$Title}@]'' ||displays the title of the current page in the iteration%0a|| %3c ||previous page ||so ''[@{%3c$Group}@]'' ||displays the group of the previous page in the iteration%0a|| > ||next page ||so ''[@{>$Name}@]'' ||displays the name of the next page in the iteration%0a%0a%0aThe > and %3c references are most useful to help structure pagelist output before and after the actual pagelist. Some common tests used to structure pagelist output are:%0a(:table class=frame:)%0a(:cellnr:)[@(:template first:)@]%0a(:cell:)[- {- [@(:if equal {%3c$Group}:)@] -} -]%0a(:cell:)Iteration is at the beginning of list%0a(:cellnr:)[@(:template last:)@]%0a(:Cell:)[- {- [@(:if equal {>$Group}:)@] -} -]%0a(:cell:)Iteration is at the end of list%0a(:cellnr:)[@(:template first {=$Group}:)@]%0a(:cell:)[- {- [@(:if ! equal {=$Group} {%3c$Group}:)@] -} -]%0a(:cell:)Iteration is at the first item in a group%0a(:cellnr:)[@(:template last {=$Group}:)@]%0a(:cell:)[- {- [@(:if ! equal {=$Group} {>$Group}:)@] -} -]%0a(:cell:)Iteration is at the last item in a group %0a(:cellnr:)[@(:template defaults:)@]%0a(:cell:)%0a(:cell:)Default options to be used in the pagelist command%0a(:cellnr:)[@(:template each:)@]%0a(:cell:)%0a(:cell:)Signifies the repeated part%0a(:cellnr:)[@(:template none:)@]%0a(:cell:)%0a(:cell:)Used if no match found%0a(:tableend:)%0a[[#specialreferencesend]]%0a''Note'': the markup in column 2 is deprecated.%0a-%3c See also [[PageVariables#specialreferences|page variable special references]].%0a%0a!! Page list template special markup%0aPagelist templates may have special sections%0a* [@(:template first ...:)@] and [@(:template ! first ...:)@]%0a* [@(:template last ...:)@] and [@(:template ! last ...:)@]%0ato specify output for the first or last page in the list or a group (use @@ !first @@ and @@ !last @@ for output ''except'' for the first/last page).%0a%0aThere's also a %0a* [@(:template defaults ...:)@] %0a to allow a template to specify default options,%0a* [@(:template each ...:)@]%0a to signify the repeated part, and%0a* [@(:template none:)@]%0a whose content will appear if no page was found (from version 2.2.5).%0a%0aThese allow Pagelist templates to be easily separated into "sections"%0athat are included or not included in the output based on a variety of%0aconditions. These are intended to be improved versions of the%0a[=(:if ...:)=] conditions that have traditionally been used to control%0apagelist output (however, the [=(:if:)=] conditions still work as before).%0a%0a!!! First, Each, Last, None%0aThe simplest versions of the directives are:%0a-> [@%0a(:template first:) # markup to display only for first page in list%0a(:template ! first:) # markup to display for every page in list but the first%0a(:template each:) # markup to display for each page in list%0a(:template last:) # markup to display only on last page in list%0a(:template ! last:) # markup to display for every page in list but the last%0a(:template none:) # markup to display only if no pages were found@]%0a%0aSo, a pagelist template can specify:%0a%0a->[@(:template first:)%0aPages in the list:%0a(:template each:)%0a* [[{=$FullName}]] [-{=$:Summary}-]%0a(:template last:)%0aDisplayed {$$PageCount} pages.@]%0a%0aIn addition, the "first" and "last" options can have control break%0aarguments that identify markup to be displayed on the first or last%0apage within a particular control section. For example, to specify%0amarkup to be displayed upon reaching the first or last page of%0aa group, one can use%0a%0a->[@(:template first {=$Group}:)%0a(:template last {=$Group}:)@]%0a%0aThus, instead of writing control breaks using (:if:) directives, as in%0a%0a->[@(:if ! equal {%3c$Group} {=$Group}:)%0aGroup: {=$Group}%0a(:ifend:)%0a* [[{=$FullName}]]@]%0a%0aone can now write%0a%0a->[@(:template first {=$Group}:)%0aGroup: {=$Group}%0a(:template each:)%0a* [[{=$FullName}]]@]%0a%0a[[Page text variables]] and [[page variables]] can also be used, for example%0a->[@(:template default $:Maintainer=- order=$:Maintainer,name:)%0a(:template first {=$:Maintainer}:)%0a@]%0a%0a!!! Default options%0aIn addition, a template may specify default options to be used%0ain the pagelist command. For example, a pagelist template to%0adisplay a list of pages by their titles (and sorted by title)%0amight use:%0a%0a->[@[[#bytitle]]%0a(:template defaults order=title:)%0a* [[{=$FullName}|+]]%0a[[#bytitleend]]@]%0a%0aThen an author could write [=(:pagelist fmt=#bytitle:)=] and the%0apages would automatically be sorted by title without having to%0aspecify an additional "order=title" option to the [=(:pagelist:)=]%0adirective.%0a%0aTo specify multiple parameters to an option enclose the parameters in double quotes, eg to sort by a [[page text variable(s)]] and then the page name%0a-> [@ (:template defaults order="$:Database,name" :) @]%0a%0a!!! Examples%0a:[=(:template defaults ... :)=] : default options for pagelists using this template%0a:[=(:template each:)=] : markup for each page in the pagelist%0a:[=(:template first:)=] : markup output only for the first page in the pagelist%0a:[=(:template last:)=] : markup output only for the last page in the pagelist%0a:[=(:template first {=$Group}:)=] : markup output only for a page where the value of {=$Group} has just changed%0a:[=(:template last {=$Group}:)=] : markup output only for a page where the value of {=$Group} will change with the next page%0a%0aSo, we have:%0a%0a->[@[[#template]]%0a(:template defaults order=name:)%0a(:template first:)%0aPages ordered by group%0a(:template first {=$Group}:)%0a%0aPages in group [[{=$Group}/]]%0a(:template each:)%0a* [[{=$FullName}]]%0a(:template last {=$Group}:)%0a {=$Group} contains {$$GroupPageCount} pages.%0a(:template last:)%0a {$$PageCount} pages total.%0a[[#templateend]] @]%0a%0a[[#additionalpagevariables]]%0a!! Page list template additional page variables%0aAdditional [[Page Variables]] that are only available during pagelist are: %0a->[@%0a{$$PageCount} The current page count of this iteration%0a{$$GroupCount} The current group count of this iteration%0a{$$GroupPageCount} The current page count within the current group of this iteration%0a{$$EachCount} The current page count within the current loop@]%0a->@@[={$$=]''option''} The argument option values from @@[@(:pagelist:)@]%0a%0a[@{$$EachCount}@] increases with each page from the pagelist, and resets when a [@(:template first {=$Property}:)@] or [@(:template last {=$Property}:)@] section is output. It can be useful when a pagelist is ordered by a page (text) variable or other property, and the pages with the same property need to be grouped together. If the order is [@$Group@] and the property is "[@{=$Group}@]", then [@{$$EachCount}@] and [@{$$GroupPageCount}@] are the same.%0a%0aUse of {$$''option''}: For example {$$trail} returns the page name entered in the trail= option of the pagelist directive. You can make up custom "options" with no other purpose than being displayed in the pagelist.%0a%0a[[#redirect]]%0a!! Redirect %0aTo enable searches that return only one page to automatically redirect to that page add the following to a pagelist template where the "jump to a page" functionality is desired:%0a%0a-> [@(:template last:)%0a(:if equal {$$PageCount} 1:)(:redirect {=$FullName}:)(:ifend:)%0a@]%0a%0a[[#closure]]%0a!! Closure of markup%0aAny open tables, divs, or other%0astructures inside of [=(:pagelist:)=] are, by default, automatically closed at the%0aend of the pagelist command. In other words, [=(:pagelist:)=] acts like%0aits own complete page, as opposed to generating markup that is then%0ainserted into the enclosing page.%0a%0aFor example a table generated by the [=(:cell:)=]%0adirective in the first [=(:pagelist:)=] command is automatically closed%0aat the end of the pagelist. The [=(:cell:)=] in the second [=(:pagelist:)=]%0acommand then starts a new table.%0a%0aNote that the [=(:table:)=] directive doesn't actually start a new table,%0ait's the [=(:cell:)=] or [=(:cellnr:)=] directive that does it. All that the%0a[=(:table:)=] directive does is set attributes for any tables that follow.%0a%0a!! Usage%0aIt is advisable to not modify the page [[Site.PageListTemplates]] directly so that you will still benefit from upgrades. %0aInstead, modify your [[Site.LocalTemplates]] page (which is not part of the PmWiki distribution). Cookbook:PagelistTemplateSamples has many examples of custom pagelist formats.%0a%0a!! Other recipes%0aIn addition, the [[(Cookbook:)Cookbook]] has other recipes for special [@fmt=@] options, including [[Cookbook:DictIndex | [@fmt=dictindex@] ]] (alphabetical index) and [[Cookbook:SimpleForum | [@fmt=forum@] ]] (forum postings).%0a time=1574162643