Exploring Zend_Paginator

One area of displaying lists on web pages that I’ve generally disliked doing is pagination as it’s a bit of a faff. Recently, I needed to do just this though as I couldn’t delegate it as my colleague was too busy on other work. As a result, I thought that I should look into Zend_Paginator this time. Turns out that it’s really easy to use and the documentation is great too.

The really useful thing about Zend_Paginator is that it uses adapters to collect its data. There are a variety of adapters, including array, dbSelect, dbTableSelect and iterator. The interesting ones for me being dbSelect and dbTableSelect as I use Zend_Db based data access layers.

This is how I used it with a Zend_Db based data mapper within TodoIt.

Setting up the paginator

My current method looks like this:
class Application_Model_TaskMapper
{
public function fetchOutstanding()
{
$db = $this->getDbAdapter();
$select = $db->select();
$select->from($this->_tableName);
$select->where('date_completed IS NULL');
$select->order(array('due_date ASC', 'id DESC'));
$rows = $db->fetchAll($select);
foreach ($rows as $row) {
$task = new Application_Model_Task($row);
$tasks[] = $task;
}
return $tasks;
}

// etc

This is pretty standard code for a data mapper. We select the data from the database and convert it to an array of entities. For the paginator to do its stuff though, we have to pass it the select object so that it can set the limit() on the select object.

The code therefore becomes:
public function fetchOutstanding()
{
$db = $this->getDbAdapter();
$select = $db->select();
$select->from($this->_tableName);
$select->where('date_completed IS NULL');
$select->order(array('date_completed DESC', 'id DESC'));

$adapter = new Zend_Paginator_Adapter_DbSelect($select);
$paginator = new Zend_Paginator($adapter);
return $paginator;
}

As you can see, we create an instance of Zend_Paginator_Adapter_DbSelect which takes the $select object and the instantiate a Zend_Paginator and return it. The Zend_Paginator object implements Interator, so you can use it exactly like an array in a foreach loop and hence, in theory, your view script doesn’t need to change.

However, the code that consumes TaskMapper expects an array of Task objects, not an array of arrays. To tell the paginator to create our objects, we extend Zend_Paginator_Adapter_DbSelect and override getItems() like this:

class Application_Model_Paginator_TaskAdapter extends Zend_Paginator_Adapter_DbSelect
{
/**
* Returns an array of items for a page.
*
* @param integer $offset Page offset
* @param integer $itemCountPerPage Number of items per page
* @return array
*/
public function getItems($offset, $itemCountPerPage)
{
$rows = parent::getItems($offset, $itemCountPerPage);

$tasks = array();
foreach ($rows as $row) {
$task = new Application_Model_Task($row);
$tasks[] = $task;
}
return $tasks;
}
}

Here, we’ve used the entity-creation code that was in our original implementation of fetchOutstanding() and placed it in getItems().

Obviously we have to update fetchOutstanding() to use our new adapter, so we replace
$adapter = new Zend_Paginator_Adapter_DbSelect($select); with $adapter = new Application_Model_Paginator_TaskAdapter($select);

Now, when we iterate over the pagination object, we get instances of Task and all is well with the world.

Using the paginator

Now that we have a paginator in place, we need to use it. Specifically we need to tell the paginator which page number we want to view and how many items are on a page. Within TodoIt, this is done in the ServiceLayer object and looks something like this:

class Application_Service_TaskService
{
// ...

public function fetchOutstanding($page, $numberPerPage = 25)
{
$mapper = new Application_Model_TaskMapper();
$tasks = $mapper->fetchOutstanding();
$tasks->setCurrentPageNumber($page);
$tasks->setItemCountPerPage($numberPerPage);
return $tasks;
}

// ...

Clearly the $page parameter comes via the URL at some point, so the controller looks something like this:

class IndexController extends Zend_Controller_Action
{
public function indexAction()
{
$page = $this->_getParam('page', 1);

$taskService = new Application_Service_TaskService();
$this->view->outstandingTasks = $taskService->fetchOutstanding($page);

$messenger = $this->_helper->flashMessenger;
$this->view->messages = $messenger->getMessages();
}

//...

and then the view uses a foreach as you’d expect.

Adding the paging controls

Finally, to complete a paged list, we have to provide the user a mechanism to select the next and previous pages along with maybe jumping to a specific page. This is done using a separate view script that you pass to the paginator. In your view script, you put something like:


<?php echo $this->paginationControl($this-> outstandingTasks,
'Sliding',
'pagination_control.phtml'); ?>

The first parameter is your paginator object. The second is the ‘scrolling style’ to use. There are four choices documented in the manual: All, Elastic, Jumping and Sliding. Personally, I have chosen to not display the page numbers themselves, so it doesn’t matter which one I pick. The last parameter is the partial view script that you want to be rendered. This allows you to have complete customisation of the HTML.

Here’s what I’m using which is based heavily on and example in the documentation:
<?php if ($this->pageCount): ?>
<div class="pagination-control">
<!-- Previous page link -->
<?php if (isset($this->previous)): ?>
<a href="<?php echo $this->url(array('page' => $this->previous)); ?>">
Previous
</a> |
<?php else: ?>
<span class="disabled">&lt; Previous</span> |
<?php endif; ?>

<!-- Next page link -->
<?php if (isset($this->next)): ?>
<a href="<?php echo $this->url(array('page' => $this->next)); ?>">
Next &gt;
</a>
<?php else: ?>
<span class="disabled">Next &gt;</span>
<?php endif; ?>
<span class="pagecount">
Page <?php echo $this->current; ?> of <?php echo $this->pageCount; ?>
</span>
</div>
<?php endif; ?>

And that’s it; I now have paginated tasks in TodoIt and as you can see, Zend_Paginator is very easy to use and, more importantly, simple to customise to your own needs.