Pagination クラス

pagination クラスは、表示したいレコードのページネーションを簡単に設定することができます。

使い方

Pagination クラスの分かりやすい使用方法の例。コントローラのアクションメソッドへ書くことができます。

$config = array(
	'pagination_url' => 'http://localhost/fuel/welcome/index/',
	'total_items'    => 10,
	'per_page'       => 5,
	'uri_segment'    => 3,
	// もしくは、クエリ文字列によるページネーションがよいのであれば
	//'uri_segment'    => 'page',
);

// 'mypagination' という名前の pagination インスタンスを作る
$pagination = Pagination::forge('mypagination', $config);

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

// オブジェクトを渡し、ビューの中に echo で出力される時に表示される
$data['pagination'] = $pagination;

// ビューを返す
return \View::forge('welcome/index', $data);

設定

pagination インスタンスは、いくつかの方法で設定することができます。 インスタンスを forge するときに設定を配列で渡すこともできますし、インスタンスのプロパティを直接更新することもできます。

次の設定項目を定義することができます。

パラメータ デフォルト 説明
pagination_url string
null
ページネーションがあるページの URL 。null の場合、現在の URL から自動で検出します。
uri_segment integer|string
3
(整数のとき) URI セグメントがページ番号を持っています。(文字列のとき) クエリ文字列のフィールドがページ番号を持っています。
num_links integer
5
表示するリンクの総数。
total_items integer
0
アイテムの総数。通常は、 count() クエリの結果です。
per_page integer
10
1 ページあたりのアイテム数。
current_page integer
null
URI 中にページ番号が示されていなかった場合に読み込むページ。指定されなかったときのデフォルトは 1 。
show_first bool
false
true かつ最初のページではない場合に '最初のページヘ' のリンクを生成します。
show_last bool
false
true かつ最後のページではない場合に '最後のページヘ' のリンクを生成します。

テンプレート

全ての pagination インスタンスは、ページネーションのマークアップを作成するために HTML を生成するテンプレートを用います。 config/pagination.php ファイルに標準のテンプレートとして保存することができます。 変更を加える前に、コア設定フォルダからアプリケーション設定フォルダにファイルをコピーしてください。 デフォルトの設定ファイルとして、FuelPHP のデフォルトと Twitter Bootstrap v2 に適合するテンプレートの 2 つのテンプレートが付属しています。

次のテンプレートのエントリを定義する必要があります。

wrapper string
<div class="pagination">\n\t{pagination}\n</div>\n
生成されたページネーションのマークアップを囲むマークアップ。
first string
<span class="first">\n\t{link}\n</span>\n
"最初のページ" のマークアップを生成するために使われるマークアップ。
first-inactive string なし このページが最初かシングルのとき、"最初のページ" のマークアップを生成するために使われるマークアップ。
first-inactive-link string なし このページが最初かシングルのとき、"最初のページ" のリンクを生成するために使われるマークアップ。
first-marker string
&laquo;&laquo;
"最初のページ" のマーカーを生成するために使われるマークアップ。
first-link string
\t\t<a href="{uri}">{page}</a>\n
"最初のページ" のリンクを生成するために使われるマークアップ。
previous string
<span class="previous">\n\t{link}\n</span>\n
"前のページ" のマークアップを生成するために使われるマークアップ。
previous-marker string
&laquo;
"前のページ" のマーカーを生成するために使われるマークアップ。
previous-link string
\t\t<a href="{uri}" rel="prev">{page}</a>\n
"前のページ" のリンクを生成するために使われるマークアップ。
previous-inactive string
<span class="previous-inactive">\n\t{link}\n</span>\n
非アクティブなリンクとして "前のページ" のマークアップを生成するために使われるマークアップ。
previous-inactive-link string
\t\t<a href="{uri}" rel="prev">{page}</a>\n
非アクティブなリンクとして "前のページ" のリンクを生成するために使われるマークアップ。
regular string
<span>\n\t{link}\n</span>\n
"その他ページ" のマークアップを生成するために使われるマークアップ。
regular-link string
\t\t<a href="{uri}">{page}</a>\n
"その他ページ" のリンクのマークアップを生成するために使われるマークアップ。
active string
<span class="active">\n\t{link}\n</span>\n
"現在のページ" のマークアップを生成するために使われるマークアップ。
active-link string
\t\t<a href="{uri}">{page}</a>\n
"現在のページ" のリンクのマークアップを生成するために使われるマークアップ。
next string
<span class="next">\n\t{link}\n</span>\n
"次のページ" のマークアップを生成するために使われるマークアップ。
next-marker string
&raquo;
"次のページ" のマーカーを生成するために使われるマークアップ。
next-link string
\t\t<a href="{uri}" rel="next">{page}</a>\n
"次のページ" のリンクを生成するために使われるマークアップ。
next-inactive string
<span class="next-inactive">\n\t{link}\n</span>\n
非アクティブなリンクとして "次のページ" のマークアップを生成するために使われるマークアップ。
next-inactive-link string
\t\t<a href="{uri}" rel="next">{page}</a>\n
非アクティブなリンクとして "次のページ" のリンクを生成するために使われるマークアップ。
last string
<span class="last">\n\t{link}\n</span>\n
"最後のページ" のマークアップを生成するために使われるマークアップ。
last-marker string
&raquo;&raquo;
"最後のページ" のマーカーを生成するために使われるマークアップ。
last-link string
\t\t<a href="{uri}">{page}</a>\n
"最後のページ" のリンクを生成するために使われるマークアップ。
last-inactive string なし このページが最後かシングルのとき、"最後のページ" のマークアップを生成するために使われるマークアップ。
last-inactive-link string なし このページが最後かシングルのとき、"最後のページ" のリンクを生成するために使われるマークアップ。

テンプレートの中で、{uri} は生成されたページネーションのリンク (非アクティブなときは #) に置き換えられます。 同様に、{page} はページ番号もしくは "前" や "次" のマーカーに置き換わります。 マーカーに画像を使用したいときは、 テンプレートの中にある該当するリンクの定義を {page} から画像のマークアップへ置き換えるだけで修正できます。

pagination インスタンスを forge するときに渡す設定は、設定ファイルで定義されているデフォルトのテンプレートとマージされます。 これは、あなたが上書きしたい値だけを渡せばよいということです。 設定ファイルのテンプレートが完全ではない場合、 上記に記載したデフォルト値が使われます。

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

forge メソッドは、新しい pagination インスタンスを作成し、配列を渡すことで設定ができます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$name 必須 作られるインスタンスの名前。名前が指定されていない場合は、'default' インスタンスが作られます。
$config
array()
設定の配列。
返り値 Pagination
// pagination インスタンスを作る
$pagination = Pagination::forge('mypagination', array(
    'pagination_url' => 'http://docs.fuelphp.com/',
	'uri_segment' => 2,
	'total_items' => 10,
	'per_page' => 20,
));

instance($name = null)

instance メソッドは、予め forge されたインスタンスを取得することができます。名前が指定されなかった場合は、default インスタンスを返します。 

静的 はい
パラメータ
パラメータ デフォルト 説明
$name
null
返されるインスタンスの名前。名前が指定されていない場合は、'default' インスタンスが作られます。 
返り値 mixed 。Pagination オブジェクト、または要求したインスタンスが存在しない場合は false 。
// 予め forge されたインスタンスを取ってくる
$pagination = Pagination::instance('mypagination');

render($raw = false)

render メソッドは、ビューの中で表示するページネーションのリンクのマークアップを生成します。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$raw
false
true の場合、ページネーションのマークアップを表示する代わりに生の pagination データを配列として返す。
返り値 string
// 予め forge されたインスタンスを取ってきて、表示する
echo Pagination::instance('mypagination')->render();

Pagination オブジェクトは、オブジェクトを echo で出力する時に render() メソッドを呼ぶ、 または文字列にキャストする __toString() メソッドを持っています。

first($marker = null)

first メソッドは、ページネーションで "最初のページ" のリンクを表示するマークアップを生成します。 マーカーとして使用する文字列が与えられなかった場合、テンプレートから "first-marker" の値が使われます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$marker
null
リンクの中に表示されるテキスト。デフォルトは、テンプレートの 'first-marker' の値。
返り値 string
// 予め forge されたインスタンスを取ってきて、"最初のページ" のリンクを表示する
echo Pagination::instance('mypagination')->first();

"最初のページ" のリンクは、最初のページが存在し、(このページが) 最初のページではない場合のみ表示されます。 デフォルトでは、'最初' の非アクティブなリンクは提供されません。

previous($marker = null)

previous メソッドは、ページネーションで "前のページ" のリンクを表示するマークアップを生成します。 マーカーとして使用する文字列が与えられなかった場合、テンプレートから "previous-marker" の値が使われます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$marker
null
リンクの中に表示されるテキスト。デフォルトは、テンプレートの 'previous-marker' の値。
返り値 string
// 予め forge されたインスタンスを取ってきて、"前のページ" のリンクを表示する
echo Pagination::instance('mypagination')->previous();

next($marker = null)

next メソッドは、ページネーションで "次のページ" のリンクを表示するマークアップを生成します。 マーカーとして使用する文字列が与えられなかった場合、テンプレートから "next-marker" の値が使われます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$marker
null
リンクの中に表示されるテキスト。デフォルトは、 テンプレートの 'next-marker' の値。
返り値 string
// 予め forge されたインスタンスを取ってきて、"次のページ" のリンクを表示する
echo Pagination::instance('mypagination')->next();

last($marker = null)

last メソッドは、ページネーションで "最後のページ" のリンクを表示するマークアップを生成します。 マーカーとして使用する文字列が与えられなかった場合、テンプレートから "last-marker" の値が使われます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$marker
null
リンクの中に表示されるテキスト。デフォルトは、 テンプレートの 'last-marker' の値。
返り値 string
// 予め forge されたインスタンスを取ってきて、"最後のページ" のリンクを表示する
echo Pagination::instance('mypagination')->last();

"最後のページ" のリンクは、最後のページが存在し、(このページが) 最後のページではない場合のみ表示されます。 デフォルトでは、 '最後' の非アクティブなリンクは提供されません。

pages_render()

pages_render メソッドは、ページネーションで "前" と "次" のリンクの間にある "ページ" のリンクを表示するマークアップを生成します。

静的 いいえ
パラメータ なし
返り値 mixed
// 予め forge されたインスタンスを取ってきて、"ページ" のリンクを表示する
echo Pagination::instance('mypagination')->pages_render();

静的インターフェイス

便宜のため、 Pagination クラスは default インスタンスのみを扱う静的インターフェースを持っています。

get($name)

get メソッドは、default インスタンスの構成アイテムを取得できます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$name 必須 取ってくるプロパティの名前。
返り値 mixed 。プロパティ値、またはプロパティが存在しない場合は null
// 現在のページ番号を取ってくる
$page_number = Pagination::get('current_page');

// これは下記の別名
$page_number = Pagination::instance()->current_page;

set($name, $value)

set メソッドは、default インスタンスの構成アイテムを指定した値で設定できます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$name 必須 設定するプロパティの名前。
$value 必須 プロパティに設定する値。
返り値 void
// 列の総数を設定する
$page_number = Pagination::set('total_items', 610);

// これは下記の別名
Pagination::instance()->total_items = 610;

下位互換性のため、set_config()create_links()next_link()prev_link() の静的メソッドは、 既存の FuelPHP v1.4 以降のアプリケーションをアップグレードするときの移行にかかる影響を最小限に抑えるために、 default インスタンスとしてエミュレートされます。

今のところ、静的クラスのプロパティへの直接アクセスをエミュレートする方法がないことに注意してください。 アプリケーションでそのようなことを行いたいときは、それらを変更する必要があります。

// v1.4 より前の使用法:
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::query()
	->order_by('date', 'ASC')
	->rows_offset(\Pagination::get('offset'))
	->rows_limit(\Pagination::get('per_page'))
	->get();