Documentation

Simple examples on how to use the Pagination class . You can put this inside your action methods in your controller.

How To Paginate with the Query Builder

$config = array(
	'pagination_url' => 'http://localhost/fuel/welcome/index/',
	'total_items'    => 10,
	'per_page'       => 5,
	'uri_segment'    => 3,
	// or if you prefer pagination by query string
	//'uri_segment'    => 'page',
);

// Create a pagination instance named 'mypagination'
$pagination = Pagination::forge('mypagination', $config);

$data['example_data'] = DB::select('id', 'value')
							->from('pagination')
							->limit($pagination->per_page)
							->offset($pagination->offset)
							->execute()
							->as_array();

// we pass the object, it will be rendered when echo'd in the view
$data['pagination'] = $pagination;

// return the view
return \View::forge('welcome/index', $data);

How To Paginate with ORM

$config = array(
	'pagination_url' => 'http://localhost/fuel/posts/index/',
	'total_items'    => Model_Post::count(),
	'per_page'       => 10,
	'uri_segment'    => 3,
	// or if you prefer pagination by query string
	//'uri_segment'    => 'page',
);

$pagination = Pagination::forge('mypagination', $config);

$data['example_data'] = Model_Post::query()
							->rows_offset($pagination->offset)
							->rows_limit($pagination->per_page)
							->get();

// we pass the object, it will be rendered when echo'd in the view
$data['pagination'] = $pagination;

// return the view
return \View::forge('posts/index', $data);

Configuration

You can configure the pagination instance in several ways. You can pass an array with the configuration when you forge the instance, or you can update the properties directly on the instance.

The following configuration settings can be defined:

null

3

5

0

10

null

false

false

0.50

'first'

Link offsets

By default, the Pagination class will try to position the active link (the one for the current page) in the middle of the pagination block.

You can control this behaviour using the link_offset value in the configuration. This value is defined either by a float between 0 and 1, or by an integer between 0 and 100 (like a percentage). By default this value is set to 0.5 (= 50%). If you make the value smaller, the active link will move to the left, if you make the value bigger, the active link will move to the right.

Example

Let's assume you have a total of 20 pages you can display. You have set num_links to 5, displaying links for 5 pages in total, and you're displaying previous and next links as well. The page you have currently selected is page 6.

• With the default setting of 0.5,

  «  4  5  6  7  8  »

  is displayed, keeping the selected page 6 nicely in the middle of the block.
• When you change the setting to 0, Pagination will always try to make the first link the active link. In this case,

  «  6  7  8  9  10  »

  is being displayed, making the selected page 6 the first link in the block.
• If you would change the setting to 1, Pagination will always try to make the last link the active link. In this case,

  «  2  3  4  5  6  »

  will be displayed.

You can use any value in the range, to progressively shift the active focus either left or right. Obviously, the more links you display, the more granular you can shift the focus.

This only works if there are enough pages to do so. If you only have 5 pages available, you want to display 5 links, and page 3 is the current page, no previous and next links are displayed, and the current page will be in the middle, no matter what the setting of link_offset is. There are simply not enough pages available to move the current page link left or right.

Templating

Every pagination instance uses a template to generate the HTML needed to create the pagination markup. You can store your standard templates in the config/pagination.php file. Copy the file from the core config folder to your app config folder before you make any modifications. The default configuration file comes with three templates, the FuelPHP default, and a Twitter Bootstrap v2 and v3 compatible template.

The following template entries must be defined:

<div class="pagination">\n\t{pagination}\n</div>\n

<span class="first">\n\t{link}\n</span>\n

««

\t\t<a href="{uri}">{page}</a>\n

<span class="previous">\n\t{link}\n</span>\n

«

\t\t<a href="{uri}" rel="prev">{page}</a>\n

<span class="previous-inactive">\n\t{link}\n</span>\n

\t\t<a href="{uri}" rel="prev">{page}</a>\n

<span>\n\t{link}\n</span>\n

\t\t<a href="{uri}">{page}</a>\n

<span class="active">\n\t{link}\n</span>\n

\t\t<a href="{uri}">{page}</a>\n

<span class="next">\n\t{link}\n</span>\n

»

\t\t<a href="{uri}" rel="next">{page}</a>\n

<span class="next-inactive">\n\t{link}\n</span>\n

\t\t<a href="{uri}" rel="next">{page}</a>\n

<span class="last">\n\t{link}\n</span>\n

»»

\t\t<a href="{uri}">{page}</a>\n

In the template, {uri} will be replaced by the generated pagination link (by # if inactive template), and {page} by the page number or the previous / next marker. If you want to use an image for these markers, just modify the corresponding link definitions in the template, replacing {page} by the markup for the image.

The configuration you pass when you forge the pagination instance will be merged with the default template defined in your configuration file. This will allow you to only pass the values you want to override. If your template in the configuration file is not complete, the default values as mentioned above will be used.

Static interface

For your convinience, the Pagination class also has a static interface that operates on the default instance only.

// fetch the current page number
$page_number = Pagination::get('current_page');

// this is an alias of
$page_number = Pagination::instance()->current_page;

// set the total number of rows
$page_number = Pagination::set('total_items', 610);

// this is an alias of
Pagination::instance()->total_items = 610;

For backward compatibility, the static methods set_config(), create_links(), next_link() and prev_link() will be emulated on the default instance, minimizing the migration effort needed when upgrading an existing application to FuelPHP v1.4+.

Note that there is no possible way to emulate direct access to static class properties at the moment, so if your application uses that, you'll have to change them:

// pre v1.4 usage:
Pagination::$per_page = 10;

// new usage:
Pagination::set('per_page', 10);

// pre v1.4 usage:
Model_Article::find()
	->order_by('date', 'ASC')
	->rows_offset(\Pagination::$offset)
	->rows_limit(\Pagination::$per_page)
	->get();

// new usage:
Model_Article::query()
	->order_by('date', 'ASC')
	->rows_offset(\Pagination::get('offset'))
	->rows_limit(\Pagination::get('per_page'))
	->get();