PageListTemplates

Summary: Recipe deprecated, see PmWiki.PageLists
Category: Obsolete

Question

How can I customize the layout of a pagelist output in a wiki page?

Answer

This recipe is now deprecated. From version 2.1.beta15, PmWiki has improved builtin Pagelist templates. See PageLists

  • Download the pltemplates.phpΔ recipe and put it in your cookbook directory.
  • Add to your config.php:
        include_once("cookbook/pltemplates.php"); 
  • Create a template for your pagelist layout (see below).
  • Include your template in your pagelist directive. Set fmt=template in your pagelist and set the page option to the name of your template (page=<template>).
Example:
  
        (:pagelist fmt=template page=PageList.Main group=Main:)

Templates:

To define a template, simply create a wiki page with standard wiki markup that will be included once for each page in the pagelist. This template can be used to define the layout of your pagelist output.

Custom variables:

Additional custom page variables are defined in this recipe which will get set appropriately on every page returned. Use these variables to output the fullnames of the current, previous or next page. With these fullnames and the PageVariables recipe you can get values such as the name and group of these pages. You can also test for conditions using the names and groups which may influence your markup, such as at the beginning of a new group.

{$Curr} - FullName of page from current iteration
{$Prev} - FullName of page from previous iteration
{$Next} - FullName of page from next iteration
{$PageCount} - The current page count
{$GroupPageCount} - The current page count within this group
{$GroupCount} - The current group count
Note: these variables have been kept to a minimum, due to the new PageVariables recipe.

Additional Conditions:

This recipe provides two additional conditions which are very valuable when using this recipe:

equal - Test whether a value is equal to another value
divisible - Test whether a number is divisible by another number

Additional Markup:

%omit-quest%

Since it is common for pagelists to reference Group pages (such as Group.HomePage) that might not exist, this new markup has been included to suppress any questions marks for non-existing pages. Simply use the markup before any link specification which may be to a non-existing wiki page.

Blank page variables with {$Prev} and {$Next}:

Since {$Prev} and {$Next} can be blank, there is markup causing page variables with blank {$Prev} and {$Next}s to also be blank. This is particularly usefull in conditional statements. This makes {{$Prev}$Group} blank if {$Prev} is blank. Without this markup, a blank {$Prev} would cause {{$Prev}$Group} to return the current group which is probably not what was desired.

Blank links with [[{$Prev}]], [[{$Next}]] or blank page variables:

There is also some additional markup defined to hide blank links which the {$Prev}, {$Next} or the ensuing blank page variables might create. This means that [[]] will be invisible instead of outputting strange markups on the first iteration.

Simple Examples:

Most of these assume that you have the PageVariables recipe installed.

  • To test for the beginning of a pagelist (is {$Prev} blank?):
    (:if equal {$Prev} :)
  • To test for the beginning of a group:
    (:if ! equal {{$Curr}$Group} {{$Prev}$Group} :) 
  • Sample template markup to create a fmt=byGroup like layout:
    (:if ! equal {{$Curr}$Group} {{$Prev}$Group} :) 
    %omit-quest%[[{{$Curr}$Group}(.HomePage)]] /
    (:if:) 
    ->[[({{$Curr}$Group}.){{$Curr}$Name}]] 

While this sets up layout info, the styling may be different from fmt=byGroup since this does not output any CSS classes. Also, non-existent groups will actually be linked with ?action=edit even though the question mark will be omitted (this might be an improvement).

Notes and Comments

  • It would be nice to allow search results to be defined this way also. Martin Fick
    (:pagelist:) and (:searchresults:) both use the same code, so whatever works for pagelist ought to work for search results. --Pm
  • What if AllRecentChanges used this, and MailPosts used it too? How would people use that? James Carlson
OK, see Forum for an example of a custom RecentChanges. - Martin Fick
I'm not sure what you are suggesting for MailPosts. Are you suggesting formatting the contents of the email by template? - Martin Fick



Versions

2005-12-05 : version 2.0 - Martin Fick

This version will break compatibility with all previous versions! Do not upgrade to this unless you are prepared to redesign your templates.

  • Redesigned with the use of the PageVariables recipe in mind, be sure to use at least version 1.1 of the recipe with this recipe.
  • Eliminated all but the essential variables.
  • Added new %omit-quest% markup and markup to deal with blank page variables and links.
  • Added the equal and divisible conditions.

2005-10-26 : version 1.3 - Martin Fick

  • Read page if page variables such as {$PageList.LastModified} and {$PageList.LastModifiedBy} are not in the cache.

2005-10-23 : version 1.2a - Daniel Scheibler

  • Add new custom variables {$PageList.LastModified}, {$PageList.LastModifiedBy}, ...

2005-10-22 : version 1.2 - Daniel Scheibler

  • Add new custom variables {$PageList.NameSpaced}, {$PageList.GroupSpaced}, ...

2005-09-18 : version 1.1 - Martin Fick

  • Fixed a minor bug where any file with the name Include becomes the template.

2005-09-16 : version 1.0 - Martin Fick

  • This recipe was last tested on PmWiki version: 2.0

See Also

Contributors

Author: Martin Fick
Extended by: Daniel Scheibler

Category: Layout Obsolete