Ninjapenguin

A couple days back Dlib posted over at the learning Kohana Blog asking people for some tutorial topics, one of the mentioned options was that of the Pagination library so I thought I would help out and throw one together for it (as it’s very simple and shouldn’t take to long!

Pagination is (in most of my projects anyway) a frequently used option, it is something users have come to expect, and from an interface point of view can give us more controll over the display of large datasets, in short its probably something you should be providing if you allready arn’t! The pagination library in Kohana takes out the monotinous side to calculating the pagination links, and allows us to rapidly provide the functionality with a minimal of fuss.

Using Pagination Library

First thing to note about Pagination in Kohana is that it is implemented within a library (system/libraries), being a library this means that we always instantiate it (as oposed to helpers which we call statically):

<?php
$pagination = new Pagination;
?>

Another important point is that the pagination library has an associated configuration file (found in system/config/pagination.php), this configuartion file should be copied into your application/config directory so that you can customise it.

The pagination library also provides a number of different default link display styles (the views for which can be found in system/views/pagination), tbhI have never found any need for generating a different display style over any of those provided, but by looking at the view files you can see how easy this is to achiveve if the situation should arise!

Configuring Pagination

The default pagination config sets up a number of params you may want to change, though it is important to note that any of these can be overridden each time you create a Pagination object, for an explanation of these variables then check the config file out!

Implementing Pagination

Scenario: I have a page which displays a number of users in a table, I want to be able to provide pagination of this table

The code below demonstrates an example usage:

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

<?php
 //Get the users
 $users = new Ntuser_Model;
 $tot = ORM::factory('ntuser')->count_all();
 
 //Pagination configuration
 $num_per_page = 10;
 
 //Setup pagination
 $pagination = new Pagination(array(
        'uri_segment' => 2,
	'total_items'=> $tot,
	'style' => "digg",
	'items_per_page' => $num_per_page,
	'auto_hide' => true
 ));
 
 $offset = $pagination->sql_offset;
 
 $users = ORM::factory('ntuser')
         ->orderby('id','desc')
         ->find_all($num_per_page,$offset);
 
$view->pagination = $pagination;
$view->users = $users;
?>

You can see how with very little effort we have created paginated results! I’ll go through and explain whats hapening in a little more detail now

Creating the object

This deals with the creation of the pagination obect (where all the magic happens), i’ll deal with each of those options passed in:

• uri_segment - The library has to have a way of knowing which page of the pagination we are currently on at any one time, it does this by adding the page number to the url, this value (an integer) represents the segment of the url in which this number resides (more info below)
• total_items - The total number of items that we are paginating over, in the above example I use ORM to count the total number of results in the table I will be returning (I could infact optimise and just count the actual results that I am passing into the view, but for clarity I wrote it out like this)
• style - I am overwriting the default style set in my application config here to the ‘digg’ style
• items_per_page - The total number of items to display on any one page (self explanatory, this can be populated dynamically if you want the user to decide!)
• auto_hide - If there are fewer results than the value of items_per_page then the pagination links will be hidden

uri-segment continued: - In the example above the code resides in the Users controller within a function called list (our path would be users/list), in the example above I have set up the route below which enables the pagination number to be set as the second uri segment

<?php
$config['users/([0-9]+)'] = 'users/index/$1';
?>

This route maps users/<any number> to the users/list/<the number> path thus enabling the Pagination library to extract the current page number from the second uri segment

Outputting the Pagination links

All that is left to do now is output the links in the view using the following code (assuming you have made the profiler object available to the view in the $profiler variable (as above))

<?php
echo $pagination;
?>

And that is all there is to it!, how to use the Pagination library in a nut shell!

If anyone has any questions then please dont hesitate to contact me!

/Matt

This entry was posted on Saturday, June 21st, 2008 at 5:17 pm and is filed under Kohana, PHP. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.