Pagination Library

The Pagination library automatically generates styled links like, « First   <  1  2  3  4  5  >   Last » for navigating through pages in a website.

The links refer to the Page number and Not the offset of the data.

The library is easily configurable. Default Pagination Settings are located in system/config/pagination.php. You can override the system settings by creating a pagination config file in your application/config or by passing configuration settings to the library at run time.

Please note that the library does not interact with your data in any way, it generates links. The developer must write the code that fetches the data referred to by the links. A method is provided to help calculate SQL offsets.

The page links are generated using a View file located in system/views/pagination. Four styles are provided. You may edit these to suit your needs, or you can create a new, custom pagination view. You may also override the system styles by copying the views to your application/views/pagination directory.

Load the Pagination class in your controller using the new keyword

Configuration settings are obtained from config/pagination.php Settings may also be passed dynamically to the class as an array.

$this->pagination = new Pagination($config);

Access to the library is available through $this→pagination

$this→pagination→initialize() is used to dynamically set pagination configuration. It is automatically called by the library constructor, so there is no need to call this method explicitly, unless you wish to overwrite a config setting dynamically.

// Will overwrite only the existing setting for this config item
$this->pagination->initialize(array('uri_segment' => 'pages'));

$this→pagination→render() is used to generate the link output for display. Allows you to select the pagination style dynamically. Please note: The links may also be output by simply echoing $this→pagination

// Will overwrite the default 'classic' style with 'digg' style
$this->pagination->render('digg'));

Note: this method is deprecated in version 2.1 – use $this→pagination→sql_offset property instead.

$this→pagination→sql_offset() is used to calculate the offset of the row to fetch, for the selected link page number. The generated pagination links refer to a logical page number, not an SQL row number. This method will automatically calculate the required row offset for you, from the current page number and the configured items-per-page setting.

$this->pagination->sql_offset(); // returns sql row offset as an integer

Note: this method is deprecated in version 2.1 – use $this→pagination→sql_limit property instead.

$this→pagination→sql_limit() is used to automatically generate SQL code, with the correct LIMIT and OFFSET clause for the selected page number.

echo $this->pagination->sql_limit(); // outputs the SQL below

LIMIT 3 OFFSET 6

The following pagination class properties are available for use in your controller:

• url
• current_page
• total_pages
• current_first_item
• current_last_item
• first_page
• last_page
• previous_page
• next_page
• sql_offset
• sql_limit

$this->pagination = new Pagination(array(
    // 'base_url'    => 'welcome/pagination_example/page/', // base_url will default to current uri
    'uri_segment'    => 'page', // pass a string as uri_segment to trigger former 'label' functionality
    'total_items'    => 254, // use db count query here of course
    'items_per_page' => 10, // it may be handy to set defaults for stuff like this in config/pagination.php
    'style'          => 'classic' // pick one from: classic (default), digg, extended, punbb, or add your own!
));
 
// Just echoing it is enough to display the links (__toString() rocks!)
echo 'Classic style: '.$this->pagination;
 
// You can also use the render() method and pick a style on the fly if you want
echo '<hr />Digg style:     '.$this->pagination->render('digg');
 
echo '<hr />Extended style: '.$this->pagination->render('extended');
 
echo '<hr />PunBB style:    '.$this->pagination->render('punbb');
 
echo 'done in {execution_time} seconds';

This will output:

If you are seeing “pagination.next”, this is because Pagination uses Kohana::lang to look up the text from your locale. Pagination locale text is stored in “system/i18n/[your_locale]/pagination.php”

Excerpt from the controller method

public function page($page_no)
{
    $content = new View('pages/items');
    $items = new Items_Model;
 
    $content->items = $items->get_items($page_no, 10); // page to get starting at offset, number of items to get
 
    $this->pagination = new Pagination(array(
        'base_url'    => 'items/page/', // Set our base URL to controller 'items' and method 'page'
        'uri_segment' => 'page', // Our URI will look something like http://domain/items/page/19
        'total_items' => count($items->get_item_count()) // Total number of items.
 
    // Note that other config items are obtained from the pagination config file.
    ));
 
    $this->template->set(array(
        'title'   => 'Items',
        'content' => $content
    ));
}

Excerpt from the View, showing how to display the links.

<h3>Items</h3>
<?php echo $this->pagination->render() ?>

The default Kohana pagination styles are located in the system/views/pagination directory. To customize an existing style or create a new pagination style, do the following:

1. Create a new directory called application/views/pagination
2. Copy one of the existing pagination styles from system/views/pagination (e.g classic.php) to application/views/pagination
3. You have the option to either rename the existing pagination style to create a completely new style (e.g. custom.php) or keep the same name to override one of the default styles.

Note: If you create a new pagination style (by renaming the file), you must reference the new custom filename when creating your pagination links (e.g. $this→pagination→render('custom'))