PageLister - Simple pagination for array collections

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

The PageLister is a simple to use and highly configurable PHP class for pagination based on array collections. In this article you can download the class, read documentation and change logs and look at examples.

You have probably seen those lists at the bottom of pages saying "Prev 1 2 3 Next" etc. and if you click on one of them you go to a different page. This is what I refer to as a "pagelist". This class generates such lists and at the same time give you plenty of freedom and configurability.

Let's jump into an example right away! Here we keep it simple and use all of the default options. First of all we must prepare some data so we can generate the pagelist. Then we generate the pagelist and lastly we output the result.


/**
 * Preparation only requires the current page number and
 * an array containing all the items.
 *
 * We assign some dummy items for testing.
 */

$currentPage = !empty($_GET['page']) ? (int) $_GET['page'] : 1;

$allItems = array();
for ($i=0; $i<25; $i++) $allItems[] = $i;

/**
 * Making the pagelist is a breeze. Feed in the data and extract it.
 */

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

/**
 * Finally output the current page items and the pagelist
 */

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

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

echo "Pages: \n";

foreach ($pageList as $page)
{
		// make sure only valid urls are clickable (prev page at page 1 won't yield a valid previous next page)
    if ($page['url']) {
      echo "<a href='?page={$page['page']}'>{$page['label']}</a> ";
    }
    else {
      echo $page['label'].' ';
    }
}

The code above will output something like this:

Current page items:
0
1
2
3
4
Pages: « 1 2 3 4 5 »

You can also specify your own labels for each page making it easy to generate a pagelist for for example an article. We just need to override some default options at instantiation of the PageLister to get the desired result. Let me demonstrate with basis on the example above:


/**
 * Example using page labels.
 *
 * First define the page labels and assign dummy articles.
 */

$pageLabels = array(
  1 => 'Introduction',
  2 => 'Contents',
  3 => 'Analysis',
  4 => 'Summary',
  5 => 'Litterature'
);

$allItems = array();
for ($i=0; $i<5; $i++) $allItems[] = $i;

/**
 * Instantiate the pagelister.
 */

$pl = new PageLister($allItems, $currentPage, array(
  'pageLabels'   => $pageLabels,
  'itemsPerPage' => 1,
  'prevAndNext'  => false
));
$pageList = $pl->makePageList();

/**
 * Output the pages.
 */

foreach ($pageList as $page)
{
    echo "<a href='?page={$page['page']}'>{$page['label']}</a> <br />\n";
}

Now the pagelist will output this instead:

<a href='?page=1'>Introduction</a> <br />
<a href='?page=2'>Contents</a> <br />
<a href='?page=3'>Analysis</a> <br />
<a href='?page=4'>Summary</a> <br />
<a href='?page=5'>Litterature</a> <br />

Now you should get the idea of how the pagelister works. If you're interested in obtaining the PageLister class then it's available for download in the files section of the article.

More features and details about the class can be found on the documentation page.

Back to the top