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. The sql_offset property automatically contains the proper row offset for you, based upon the current page and the items_per_page configuration property. These values should be used in your query for LIMIT and OFFSET.

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.

Additional information: Pagination Tutorial

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

The following configuration properties can be passed to the pagination constructor:

• base_url
• directory
• style
• uri_segment
• query_string
• items_per_page
• total_items
• auto_hide

The following pagination class properties are auto-generated and 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→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');

$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'))