Pagination クラス

The pagination class allows you to easily setup pagination for records you display.

使い方

A simple example on how to use the Pagination class. You can put this inside your action methods in your controller.

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

$data['pagination'] = $pagination->render();
$this->render('welcome/index', $data);

設定

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:

パラメータ 規定値 説明
pagination_url string
null
The URL of page where you have pagination. If null, Fuel tries to detect it from the current URL.
uri_segment integer|string
3
The URI segment containing the page number (if integer). The query string field containing the page number (if string).
num_links integer
5
The total number of links to show.
total_items integer
0
The total number of items. Usually this is the result of a count() query.
per_page integer
10
The number of items per page.
current_page integer
null
The page to load if no page number is present in the URI. If not given, it defaults to 1.
show_first bool
false
Generates a 'to the first page' link if true and not already on the first page.
show_last bool
false
Generates a 'to the last page' link if true and not already on the last page.

テンプレート

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 two templates, the FuelPHP default, and a Twitter Bootstrap v2 compatible template.

The following template entries must be defined:

wrapper string
<div class="pagination">\n\t{pagination}\n</div>\n
Markup that will wrap the generated pagination markup.
first string
<span class="first">\n\t{link}\n</span>\n
Markup that will be used to generate the first page markup.
first-link string
\t\t<a href="{uri}">{page}</a>\n
Markup that will be used to generate the first page link.
previous string
<span class="previous">\n\t{link}\n</span>\n
Markup that will be used to generate the previous page markup.
previous-link string
\t\t<a href="{uri}">{page}</a>\n
Markup that will be used to generate the previous page link.
previous-inactive string
<span class="previous-inactive">\n\t{link}\n</span>\n
Markup that will be used to generate the previous page markup for inactive links.
previous-inactive-link string
\t\t<a href="{uri}">{page}</a>\n
Markup that will be used to generate the previous page markup for inactive links.
regular string
<span>\n\t{link}\n</span>\n
Markup that will be used to generate the markup for other pages.
regular-link string
\t\t<a href="{uri}">{page}</a>\n
Markup that will be used to generate the markup for other page links.
active string
<span class="active">\n\t{link}\n</span>\n
Markup that will be used to generate the markup for the current page.
active-link string
\t\t<a href="{uri}">{page}</a>\n
Markup that will be used to generate the markup for the link to the current page.
next string
<span class="next">\n\t{link}\n</span>\n
Markup that will be used to generate the next page markup.
next-link string
\t\t<a href="{uri}">{page}</a>\n
Markup that will be used to generate the next page link.
next-inactive string
<span class="next-inactive">\n\t{link}\n</span>\n
Markup that will be used to generate the next page markup for inactive links.
next-inactive-link string
\t\t<a href="{uri}">{page}</a>\n
Markup that will be used to generate the next page link for inactive links.
last string
<span class="last">\n\t{link}\n</span>\n
Markup that will be used to generate the last page markup.
last-link string
\t\t<a href="{uri}">{page}</a>\n
Markup that will be used to generate the last page link.

In the template, {uri} will be replaced by the generated pagination link, 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.

forge($name = 'default', $config = array())

The forge method allows you to create a new pagination instance, and configure it by passing an array.

静的 はい
パラメータ
Param Default Description
$name Required The name of the instance to be created. If no name is given, the 'default' instance is created.
$config
array()
The configuration array.
返り値 Pagination
// create a new pagination instance
$pagination = Pagination::forge('mypagination', array(
    'pagination_url' => 'http://docs.fuelphp.com/',
	'uri_segment' => 2,
	'total_items' => 10,
	'per_page' => 20,
));

instance($name = null)

The instance method allows you retrieve a previously forged instance, or return the default instance if no name was given.

静的 はい
Parameters
Param Default Description
$name
null
The name of the instance to be returned. If no name is given, the 'default' instance is created.
Returns mixed. a Pagination object, or false if the requested instance does not exist.
Example
// fetch the previously forged instance
$pagination = Pagination::instance('mypagination');

render()

The render method generates the markup to display the pagination links in the view.

静的 No
Parameters None
返り値 string
// fetch a previously forged instance, and render it
echo Pagination::instance('mypagination')->render();

first($marker = '&laquo;&laquo;')

The first method generates the markup to display a "First page" link for pagination.

静的 No
パラメータ
パラメータ 規定値 説明
$marker
'&laquo;&laquo;'
The text to be displayed in the link.
Returns string
Example
// fetch a previously forged instance, and render the "first page" link
echo Pagination::instance('mypagination')->first();

The "First page" link will only be shown if there is a first page, and you're not already on it. There is no inactive link support for 'first'.

previous($marker = '&laquo;')

The previous method generates the markup to display a "Previous" link for pagination.

静的 No
Parameters
Param Default Description
$marker
'&laquo;'
The text to be displayed in the link.
Returns string
Example
// fetch a previously forged instance, and render the "previous page" link
echo Pagination::instance('mypagination')->previous();

next($marker = '&raquo;')

The next method generates the markup to display a "Next" link for pagination.

静的 No
Parameters
Param Default Description
$marker
'&raquo;'
The text to be displayed in the link.
Returns string
Example
// fetch a previously forged instance, and render the "next page" link
echo Pagination::instance('mypagination')->next();

last($marker = '&raquo;&raquo;')

The last method generates the markup to display a "Last page" link for pagination.

静的 No
Parameters
Param Default Description
$marker
'&raquo;&raquo;'
The text to be displayed in the link.
Returns string
Example
// fetch a previously forged instance, and render the "last page" link
echo Pagination::instance('mypagination')->last();

The "Last page" link will only be shown if there are any pages, and you're not already on the last one. There is no inactive link support for 'last'.

pages_render()

The pages_render method generates the markup that displays the page links between previous and next links for pagination.

静的 No
Parameters None
Returns mixed
// fetch a previously forged instance, and render the "pages" link
echo Pagination::instance('mypagination')->pages_render();

静的インターフェイス

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

get($name)

The get method allows you to get a configuration item on the default instance.

静的 はい
パラメータ
パラメータ 規定値 説明
$name Required The name of the property to fetch.
Returns mixed, properly value, or null if the property doesn't exist.
// fetch the current page number
$page_number = Pagination::get('current_page');

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

set($name, $value)

The set method allows you to set a configuration item on the default instance to the given value.

静的 はい
Parameters
Param Default Description
$name Required The name of the property to set.
$value Required The value to set the property to.
Returns void
// 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;

// 新しい使用法:
Pagination::set('per_page', 10);

// v1.4 より前の使用法:
Model_Article::find()
	->order_by('date', 'ASC')
	->rows_offset(\Pagination::$offset)
	->rows_limit(\Pagination::$per_page)
	->get());

// 新しい使用法:
Model_Article::find()
	->order_by('date', 'ASC')
	->rows_offset(\Pagination::get('offset'))
	->rows_limit(\Pagination::get('per_page'))
	->get());