Documentation

Edited 28. Nov 2010, 14:54
Published 04. Nov 2010, 02:28
Based on Organizing articles into pages
Files PageLister/PageLister..
Pages
  1. The PageLister
  2. Documentation
  3. Changelog

Here's the documentation for the PageLister class.

__construct()

array $allItems All of the items which you want to generate a pagelist from
array $page Current page
array $opts Array with options given as key-value pair.
Returns an instance of PageLister

You can override default options by passing an associative array with the constructor. The possible options are listed here:

Type Option Default Description
string itemsPerPage 5 Number of items shown per page
string urlFormat %d You can use this format to format each page url. Normally the format takes one format argument in the sprintf syntax (ie. %d), which will be replaced with the pagenumber (this way a different url is created for each page). If the option 'customFormatting' is set to true then the urlFormat replaces on the value of the 'varPage' option.
boolean customFormatting false With custom formatting enabled you can define your own syntax for the pagenumber format. This is handy in case your url format accidently includes format arguments (like url characters encoded in utf-8) and which collides with the pagenumber argument.
callback urlCallback null If a callback is given then the pageurl will be formatted based on the result of this callback.
array urlCallbackArgs array() If the urlCallback option is set then you can specify additional callback arguments with this option.
At least one of the callback arguments should contain the 'varPage' value so the corresponding pagenumber can be injected into the callback.
string varPage {pagenum} The value of this option will be replaced by the pagenumber in numerous settings.
It will be used when the option 'customFormatting' is set, as well as when a 'urlCallback' is set. In the latter case then one of the callback arguments should contain this value.
array pageLabels array() Each individual page can be given a specific page label with this option. Each key in the array is the pagenumber and the value is the page label.
boolean prevAndNext true Whether or not to include the "previous" and "next" items in the page list
string prev « The text shown as "previous page"
string next » The text shown as "next page"

Note that you can use either normal url formatting, custom formatting or callback formatting. If several options are specified the presedence order is: callback, custom formatting, normal formatting.

Example of instantiating the class with options: 

$pl = new PageLister($allItems, $currentPage, array(
	'pageLabels'   => array(1 => 'Intro', 2 => 'Contents', 3 => 'Summary'),
	'itemsPerPage' => 1,
	'prevAndNext'  => true,
	'prev'				 => 'Prev',
	'next'				 => 'Next',
	'urlFormat'		 => '/articles/?page=%d'
));

Example using the 'customFormatting' option. Notice how the url format includes a percentage sign; this could interfer with the normal urlformat argument syntax. By replacing the pagenumber on a customized value we can gracefully avoid this issue. 

$pl = new PageLister($allItems, $currentPage, array(
	'urlFormat'				 => '/articles/programming-in-c%2B%2B/page/{pagenum}/',
	'customFormatting' => true
));

Example using a callback function for generating each pageurl: 

// callback function
function makePageUrl($page) {
	return "/articles/programming-in-c%2B%2B/page/$page/";
}

// assign the callback to the pagelister
$pl = new PageLister($allItems, $currentPage, array(
	'urlCallback'			=> 'makePageUrl',
	'urlCallbackArgs' => array('{pagenum}')
));

makePageList()

void Takes no arguments
Returns an associative array with information about each pagelink.

The keys and values of the pagelist is shown below:

Type Key Value
string url The formatted url for the page. Note that when using the 'prevAndNext' option and there is no valid previous or next page, then the url will be null. This is also the case if a pagelink points to the current page. You can use this info to remove links that the user should not click on.
int page The pagenumber
string label The page label

Example using the urlFormat option: 

$pl = new PageLister($allItems, $currentPage, array(
	'urlFormat' => '/articles/?page=%d'
));
$pageList = $pl->makePageList();

// output pagelist
foreach ($pageList as $page)
{
    echo "<a href='{$page['url']}'>$page['label']</a> ";
}

Example of removing anchors we don't want the user to click on (for example no valid previous page): 

$pl = new PageLister($allItems, $currentPage, array(
	'urlFormat'   => '/articles/?page=%d',
	'prevAndNext' => true
));
$pageList = $pl->makePageList();

// output pagelist
foreach ($pageList as $page)
{
		if ($page['url']) {
			echo "<a href='{$page['url']}'>$page['label']</a> ";
		}
    else {
			echo $page['label'];
		}
}

getCurrentItems()

void Takes no arguments
Returns an array with the visible items on the current page.

Example of outputting the current items:

$pl = new PageLister($allItems, $currentPage);
$currentItems = $pl->getCurrentItems();

// outputting current page items
echo "Current page items:<br />\n";

foreach ($currentItems as $item)
{
	echo "$item <br />\n";
}

Back to the top