Jamie Nay

Nothing like writing a tutorial on your code to realize how you could improve it! Just minutes after writing a tutorial on persisting pagination limits in CakePHP – a system I developed weeks ago, I wondered to myself why I just didn’t make it a component and boost its portability by a billion percent. So, I whipped it up and called it AutoPaginate. Usage is much simpler; no more AppController silliness, just setting up the view files and individual controllers for pagination. I’ll paste in those parts of the tutorial from version 1.0. Speaking of which:

If you find yourself paginating a lot of results, you may want to give your users the ability to change the number of results per page they see. Easy enough, I know, but the user’s preference should also persist through the session no matter what data the application is serving up. And, ideally, we don’t want to POST every time we want to change the pagination limit; I like having it right in the URL for easy reading.

So here’s a component that shows how easy it is to put in user-modifiable, session-persisting pagination limits.

The full component (app/controllers/components/auto_paginate.php):

<?php
/**
 * Auto Paginate Component class.
 *
 * A simple extension for paginating that helps with persisting user-defined pagination limits.
 *
 * @filesource
 * @author			Jamie Nay
 * @copyright       Jamie Nay
 * @license			http://www.opensource.org/licenses/mit-license.php The MIT License
 * @link            http://jamienay.com/code/auto-paginate-component
 */
class AutoPaginateComponent extends Object {

 /**
 * Other components needed by this component
 *
 * @access public
 * @var array
 */
 public $components = array('Session');

 /**
 * component settings
 *
 * @access public
 * @var array
 */
 public $settings = array();

 /**
 * Default values for settings.
 * - options: the results-per-page options to present to the user.
 *
 * @access private
 * @var array
 */
 private $__defaults = array(
 'options' => array(1, 5, 10, 25, 50, 100),
 'defaultLimit' => 25
 );

 /**
 * Configuration method.
 *
 * @access public
 * @param object $model
 * @param array $settings
 */
 public function initialize(&$controller, $settings = array()) {
 $this->settings = array_merge($this->__defaults, $settings);
 $this->controller =& $controller;
 }

 /**
 * beforeRender()
 *
 * Set the variables needed by the controller.
 *
 * @access public
 * @param $controller Controller object
 */
 public function beforeRender(&$controller) {
 $controller->set('paginationOptions', $this->settings['options']);
 $controller->set('paginationLimit', $this->paginationLimit());
 }

 /**
 *
 * Set the controller's $paginate variable.
 *
 * @access public
 * @param array $options
 */
 public function setPaginate($options = array()) {
 $defaults = array(
 'limit' => $this->paginationLimit()
 );

 $this->controller->paginate = array_merge($defaults, $options);
 }

 /**
 * Set the pagination limit based on user input and session variables.
 *
 * @access public
 */
 public function paginationLimit() {
 if (isset($this->controller->params['named']['Paginate'])) {
 $this->Session->write('Pagination.limit', $this->controller->params['named']['Paginate']);
 }

 return ($this->Session->check('Pagination.limit') ? $this->Session->read('Pagination.limit') :
 $this->settings['defaultLimit']);
 }

}

?>

Two config options: ‘options’, which determines the available results-per-page options for the user, and ‘defaultLimit’, which, predictably, determines the default pagination results limit.

To use the component, just plug it into your AppController’s $components array (app/app_controller.php):

var $components = array('AutoPaginate');

Now we need to change the way we configure pagination in individual controllers. This is the easy part – just call AutoPaginate::setPaginate() instead of explicitly defining $this->paginate when setting up your pagination. For example, in our PlayersController::admin_index() function we’re used to doing this:

$this->paginate = array(
 'limit' => 20,
 'contain' => array('Player, 'Position')
);
$this->set('players', $this->paginate());

But now we’ll just do this (app/controllers/players_controller.php):

function admin_index() {
 $this->AugoPaginate->setPaginate(array(
 'contain' => array('Team', 'Position')
 ));

 $this->set('players', $this->paginate());
}

Finally, since our pagination will be standardized through the entire site, we’ll set up a couple of common view elements.

The top element will present the choices for the number of results per page, as well as the usual “display X out of X results” line. It looks like this (app/views/elements/pagination/top.ctp):

 Results per page:
 <?php
 $results = array();
 foreach ((array)$paginationOptions as $option) {
 if ($paginationLimit == $option) {
 $results[] = $option;
 } else {
 $args = $this->passedArgs;
 $args['Paginate'] = $option;
 $results[] = $html->link($option, $args);
 }
 }
 echo implode(" | ", $results);
 ?>

<?php
echo $paginator->counter(array(
'format' => __('Page %page% of %pages%, showing %current% records out of %count% total, starting on record %start%, ending on %end%.', true)
));
?>

That’ll produce a string of plain text links – not a form – that the user can use to change pagination limits. The output looks like this:

Results per page: 1 | 5 | 10 | 25 | 50 | 100

Page 1 of 105, showing 10 records out of 1042 total... (etc)

$paginationOptions and $paginationLimit are set in AutoPaginateComponent.

We’ll also make a new element for the bottom of paginated results too (app/views/elements/pagination/bottom.ctp):

<div class="paging">
 <?php echo $paginator->prev('<< '.__('previous', true), array('url' => $this->passedArgs), null, array('class'=>'disabled'));?>
 | 	<?php echo $paginator->numbers(array('url' => $this->passedArgs));?>
 <?php echo $paginator->next(__('next', true).' >>', array('url' => $this->passedArgs), null, array('class'=>'disabled'));?></div>

Now to insert the elements into a typical view with typical paginated results. I like to insert top.ctp as a table caption, but you can do anything you’d like. If we’re paginating in, say, PlayersController::admin_index, it might look something like this (app/views/players/admin_index.ctp):

<h2><?php __('Players');?></h2>
<table cellpadding="0" cellspacing="0" class="table_list">
 <caption>
 <?php echo $this->element('pagination/top'); ?>
 </caption>
 .... (data in table) ...</table>
<?php echo $this->element('pagination/bottom'); ?>

Pretty simple, eh? I prefer using helper functions to set variables anyway, so this kills two birds in one stone by automatically setting the pagination limit and getting rid of the “$this->paginate =” business in controllers.

As always, comments, suggestions, improvements and helpful criticisms welcome!

If you find yourself paginating a lot of results, you may want to give your users the ability to change the number of results per page they see. Easy enough, I know, but the user’s preference should also persist through the session no matter what data the application is serving up. And, ideally, we don’t want to POST every time we want to change the pagination limit: I like having it right in the URL for easy reading.

So, I’m just going to do a little quickie here to show you how easy it is to put in user-modifiable pagination limits. We’ll write a common view element for pagination, then we’ll turn to AppController and write a couple of functions to handle setting the pagination limit and interpreting changes to that limit. Finally, we’ll slightly modify the way we set up pagination in individual controllers to handle the new code. It’ll go something like this:

• Setting up Common View Elements
• New Functions in AppController
• Modifying Individual Controller Pagination Calls

Setting up a Common View Element

OK, so if all of our paginated results are going to look the same then we might as well have a common view element. This element will present the choices for the number of results per page, as well as the usual “display X out of X results” line. It looks like this (app/views/elements/pagination/top.ctp):

 Results per page:
 <?php
 $results = array();
 foreach ((array)$paginationOptions as $option) {
 if ($paginationLimit == $option) {
 $results[] = $option;
 } else {
 $args = $this->passedArgs;
 $args['Paginate'] = $option;
 $results[] = $htmla->link($option, $args);
 }
 }
 echo implode(" | ", $results);
 ?>

<?php
echo $paginator->counter(array(
'format' => __('Page %page% of %pages%, showing %current% records out of %count% total, starting on record %start%, ending on %end%.', true)
));
?>

That’ll produce a string of plain text links – not a form – that the user can use to change pagination limits. The output looks like this:

Results per page: 1 | 5 | 10 | 25 | 50 | 100

Page 1 of 105, showing 10 records out of 1042 total... (etc)

There are two variables in the pagination/top.ctp that we need to define, as well – $paginationOptions and $paginationLimit. You just need to set these somewhere in your AppController before the view is rendered, so in, say, beforeFilter() – I actually set mine in conjunction with my quick and dirty widget component (/end shameless plug ):

// Pagination options
$this->set('paginationOptions', array(1, 5, 10, 25, 50, 100));
$this->set('paginationLimit', $this->_paginationLimit());

We’ll write the _paginationLimit() function in the next section.

We’ll also make a new element for the bottom of paginated results too (app/views/elements/pagination/bottom.ctp):

<div class="paging">
 <?php echo $paginator->prev('<< '.__('previous', true), array('url' => $this->passedArgs), null, array('class'=>'disabled'));?>
 | 	<?php echo $paginator->numbers(array('url' => $this->passedArgs));?>
 <?php echo $paginator->next(__('next', true).' >>', array('url' => $this->passedArgs), null, array('class'=>'disabled'));?></div>

Now to insert the elements into a typical view with typical paginated results. I like to insert top.ctp as a table caption, but you can do anything you’d like. If we’re paginating in, say, PlayersController::admin_index, it might look something like this (app/views/players/admin_index.ctp):

<h2><?php __('Players');?></h2>
<table cellpadding="0" cellspacing="0" class="table_list">
 <caption>
 <?php echo $this->element('pagination/top'); ?>
 </caption>
 .... (data in table) ...</table>
<?php echo $this->element('pagination/bottom'); ?>

The views are finished – now we just need the methods to make it all work.

New Functions in AppController

Two new functions here, one that we’ll use in the individual controllers in place of defining $this->paginate, and another one called by that function to set the pagination limit depending on possible user input and the existing session-written value.

The first method, _setPaginate(), is just a shortcut for setting $this->paginate in controllers, so we don’t need to set the limit every time. It’s short and sweet (app/app_controller.php):

protected function _setPaginate($options = array()) {
 $defaults = array(
 'limit' => $this->_paginationLimit()
 );

 $this->paginate = array_merge($defaults, $options);
}

Notice that _setPaginate() calls _paginationLimit(), which is the function that sets and gets the limit in the user’s session:

protected function _paginationLimit() {
 if (isset($this->params['named']['Paginate'])) {
 $this->Session->write('Pagination.limit', $this->params['named']['Paginate']);
 }

 // On two lines for blog readability.
 return ($this->Session->check('Pagination.limit') ? $this->Session->read('Pagination.limit') :
 Configure::read('SiteSettings.default_pagination_limit'));
}

The system is done – now we just have to use it!

Modifying Individual Controller Pagination Calls

This is the easy part – just call _setPaginate() instead of explicitly defining $this->paginate when setting up your pagination. For example, in our PlayersController::admin_index() function we’re used to doing this:

$this->paginate = array(
 'limit' => 20,
 'contain' => array('Player, 'Position')
);
$this->set('players', $this->paginate());

But now we’ll just do this (app/controllers/players_controller.php):

function admin_index() {
 $this->_setPaginate(array(
 'contain' => array('Team', 'Position')
 ));

 $this->set('players', $this->paginate());
}

Pretty simple, eh? I prefer using helper functions to set variables anyway, so this kills two birds in one stone by automatically setting the pagination limit and getting rid of the “$this->paginate =” business in controllers.

As always, comments, suggestions, improvements and helpful criticisms welcome!