version=pmwiki-2.2.4 ordered=1 urlencoded=1
agent=Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.8.1.19) Gecko/20081216 Ubuntu/8.04 (hardy) Firefox/2.0.0.19
author=Petko
charset=ISO-8859-1
csum=template none
ctime=1176759249
host=86.69.109.9
name=PmWiki.PageListTemplates
rev=27
targets=PmWiki.PageLists,Site.PageListTemplates,Site.LocalTemplates,PmWiki.PageVariables,PmWiki.PageTextVariables
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 %0aIf the page name is not specified as part of the template name, PmWiki's default configuration looks for templates in the following locations in the following order%0a# the current page%0a# [[Site.LocalTemplates]], %0a# [[Site.PageListTemplates]]%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(:tableend:)%0a[[#specialreferencesend]]%0a''Note'': the markup in column 2 is deprecated%0a%0a!! Page list template special markup%0aPagelist templates may have special %0a* [@(:template first ...:)@]%0a* [@(:template last ...:)@] sections to specify output for the first or last page in the list or a group. %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 each:)       # markup to display for each page in list%0a(:template last:)       # markup to display only on last page in list%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}]]%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!!! 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 default 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!! 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{$$option}          The argument option values from (:pagelist:)@]%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=1251031058