Documentation

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

Query Builder を使ったページネーションの方法

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

ORM を使ったページネーションの方法

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

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

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

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

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

設定

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

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

null

3

5

0

10

null

false

false

0.50

リンクのオフセット量

デフォルトで、 Pagination クラスはページネーションブロックの中央に ("現在のページ" の) アクティブなリンクを配置します。

設定にある link_offset の値を使うことで、この振舞いをコントロールすることができます。 この値は、float の 0 から 1 までの間か integer の 0 から 100 までの間 (パーセンテージのように) のどちらかで定義することができます。この値はデフォルトで 0.5 (= 50%) にセットされています。 この値を小さくした場合、アクティブなリンクは左へ移動し、 大きくした場合、アクティブなリンクは右へ移動します。

例

ここで、表示できるページが全部で 20 ページあると仮定してみましょう。 num_links は 5 にセットされていて、表示されるリンクは全部で 5 ページとなります、 同様に "前" と "次" のリンクも表示されています。現在選択しているページは 6 ページ目となります。

• デフォルトの設定である 0.5 では、

  «  4  5  6  7  8  »

  と表示されます、 選択しているページの 6 がブロックの中央部分にうまくキープされています。
• 設定を 0 に変更した場合、 Pagination は常にアクティブなリンクを最初のリンクとします。このケースでは、

  «  6  7  8  9  10  »

  と表示されます、選択しているページの 6 がブロックの最初のリンクになっています。
• 設定を 1 に変更した場合、 Pagination は常にアクティブなリンクを最後のリンクにします。このケースでは、

  «  2  3  4  5  6  »

  と表示されます。

アクティブの焦点を左や右へ徐々に移動させるために、範囲の中で任意の値を取ることができます。 当然ですが、表示したいリンクがあればあるほど、焦点の移動をするための粒度は細かくなっていきます。

これは十分なページがある場合に限って動作します。もしも、たったの 5 ページしかなくて、 5 つのリンクを表示したい、そして 3 ページ目が "現在のページ" の場合、 "前" と "次" のリンクは表示されませんし、 link_offset がどんな設定であっても "現在のページ" は中央となります。 これは単純に "現在のページ" のリンクを左や右へ移動できるほどの十分なページがないからです。

テンプレート

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

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

<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

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

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

静的インターフェイス

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

// 現在のページ番号を取ってくる
$page_number = Pagination::get('current_page');

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

// 列の総数を設定する
$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();