^Status|Draft| ^Todo|content needs to be reorganized, more explanation for config and class properties| ====== 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: [[http://www.ninjapenguin.co.uk/blog/2008/06/21/kohana-pagination-tutorial/|Pagination Tutorial]] ===== Loading the Pagination library ===== 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'' ===== Pagination configuration properties ===== 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 ===== Pagination class properties ===== 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 ===== Methods ===== ==== initialize() ==== ''$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'));

==== render() ==== ''$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');

===== Example One =====


$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 'Digg style:     '.$this->pagination->render('digg');

echo 'Extended style: '.$this->pagination->render('extended');

echo 'PunBB style:    '.$this->pagination->render('punbb');

echo 'done in {execution_time} seconds';

This will output: Classic style:

1 2 3 4 5 6 7 8 9 10 11 13 14 15 16 17 18 19 20 21 22 23 24 25 26 > last ›

Digg style:

« previous 1 2 3 4 5 6 7 8 9 10 … 25 26 next »

Extended style:

« previous | page 1 of 26 | items 1–10 of 254 | next »

PunBB style:

pages: 1 2 3 … 26

If you are seeing "pagination.next", this is because Pagination uses [[core:kohana|Kohana::lang]] to look up the text from your [[core:config|locale]]. Pagination locale text is stored in "system/i18n/[your_locale]/pagination.php" ===== Example Two ===== 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.


Items
pagination->render() ?>

===== Creating Customized Pagination Styles ===== 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: - Create a new directory called ''application/views/pagination'' - Copy one of the existing pagination styles from ''system/views/pagination'' (e.g classic.php) to ''application/views/pagination'' - 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')'')