弱小PHPerの憂鬱

CakePHP1.2.4.8284のページャーの全メソッドと引数を解説。

公式マニュアルには$paginatorの解説が全く載っていません。
マニュアルでは「$paginator->numbersで前後10件ずつ表示したい」「1ページ目にリンクしたい」すら解決できません。
他に解説しているところもほとんど見あたりませんでした。

仕方ないのでソースから解読。
よくわかんないところは想像で適当に補っています。
特に$optionsの中身とかはさっぱりわからないので間違っている可能性大。

first ( [ $first [ , $options ] ] )
1ページ目へのリンクを作成
引数	解説
$first	リンクに表示する文字
$options	要素はtag,after,model,separator,url,update

last ( [ $last [ , $options ] ] )
最終ページへのリンクを作成
引数	解説
$last	リンクに表示する文字
$options	要素はtag,before,model,separator,url,update

prev ( [ $title [ , $options [ , $disabledTitle [ , $disabledOptions ] ] ] ] )
前のページにリンク
引数	解説
$title	リンクに表示する文字
$options	要素はurl,step,escape,model,tag,model,update ただしtagはバグで？効かない
$disabledTitle	前のページが存在しない場合に表示する文字列
$disabledOptions	前のページが存在しない場合に適用するオプション 要素は$optionsと同じ。 こちらはtag有効。

next ( [ $title [ , $options [ , $disabledTitle [ , $disabledOptions ] ] ] ] )
次のページにリンク
引数	解説
$title	リンクに表示する文字
$options	要素はurl,step,escape,model,tag,model,update ただしtagはバグで？効かない
$disabledTitle	次のページが存在しない場合に表示する文字列
$disabledOptions	次のページが存在しない場合に適用するオプション 要素は$optionsと同じ。 こちらはtag有効。

numbers ( [ $options ] )
前後数ページへのリンクを表示
引数	解説
$options	要素はtag,before,after,first,last,separator,model,modulus,url,update またはtrue(before,after,first,lastを指定したことになる)

sort ( $title [ , $key [ , $options ] ] )
ソート
引数	解説
$title	リンクに表示する文字列。 ただし$keyが無い場合、$titleが$keyに入れられ、$titleはキャメルケースされて表示される。
$key	ソートするカラム名。
$options	要素はurl,model,update

url ( [ $options [ , $asArray [ , [ $model ] ] ] )
指定されたURLを返す
引数	解説
$options	要素はpage,sort,direction,order。 デフォルトは現在のURL。
$asArray	返り値を配列として返すか否かのフラグ。 falseの場合、そのまま完全なURLが返ってくる。 trueの場合、link()の第二引数として使用する配列形式で返す。
$model	別のモデルを使用する場合に指定。

link ( $title [ , $url [ , $options ] ] )
任意のリンクを作成して返す
引数	解説
$title	リンクに表示する文字列。
$url	URLに出力するキーと値の配列。 現在のURLの値とマージされる。
$options	要素はmodel,url,update
使用例	$paginator->link('リンク',array('a'=>'b'));　→　現在のアドレスに/a:b/がプラスされたURLへのリンクが作成される。

currrent ( [ $model ] )
現在のページ数を返す
引数	解説
$model	デフォルト以外のモデルをチェックしたい場合に指定。

params ( [ $model ] )
ページャーの関連パラメータを取得
引数	解説
$model	デフォルト以外のモデルをチェックしたい場合に指定。

options ( [ $options ] )
ページャーの関連パラメータを設定
引数	解説
$options	params()で参照できる情報を上書きできる。 モデル名から含めた配列で指定が必要。 ビューからでは指定できない内容が多い。
使用例	$paginator->options(array('Hoge'=>array('page'=>10)))　→　現在のページを10ページということにする

counter ( [ $options ] )
現在の件数やページ数などを返す
引数	解説
$options	要素はmodel,format,separator ただし引数を文字列で与えた場合、$options['format']として扱われる。
$options['format']	$options['format']は特殊なので此処で解説。 無指定、'pages'の場合、「3 of 50」(50ページ中3ページ目の意味) 'range'の場合、「41 - 60 of 999」(999件中41-60件目の意味) それ以外の場合、入力した中から以下の文字列が置換されて返ってきます。 　%page%→現在のページ数 　%pages%→全ページ数 　%current%→1ページあたりの件数 　%count%→全件数 　%start%→現在のページの開始件数 　%end%→現在のページの終了件数
使用例	$paginator->counter(array('format'=>'range'))　→　「41 - 60 of 999」 $paginator->counter('全%pages%ページ中%page%ページ目を表示')　→　「全50ページ中10ページ目を表示」

hasPage ( $model , [ $page ] )
該当のページが存在するかチェック
引数	解説
$model	ページが存在するかチェックしたいモデル名。 ただし数値を入れた場合、ここが第二引数の$page扱いになる。
$page	チェックしたいページ数。
使用例	$paginator->hasPage('Hoge',10)　→　Hogeモデルのページャに10ページ目が存在するかチェック $paginator->hasPage(10)　→　現在のモデルのページャに10ページ目が存在するかチェック

hasPrev ( [ $model ] )
前のページが存在するかチェック
引数	解説
$model	チェックしたいモデル名。 デフォルトは現在のモデル。

hasNext ( [ $model ] )
次のページが存在するかチェック
引数	解説
$model	チェックしたいモデル名。 デフォルトは現在のモデル。

defaultModel ( )
デフォルトのモデル名を取得
引数	解説
なし	基本的に内部用

sortKey ( [ $model [ , $options ] ] )
ソートのORDER BYの値を取得。passedArgs['sort']に近い
引数	解説
$model	デフォルト以外のモデルを使用する場合に指定。
$options	sort,order,defaults

sortDir ( [ $model [ , $options ] ] )
ソートの順番(ASC,DESC)を取得。passedArgs['direction']に近い
引数	解説
$model	デフォルト以外のモデルを使用する場合に指定。
$options	order,defaults,direction

各メソッドに出てくる引数$optionsは、以下のような要素を持った配列で渡します。

要素	解説
tag	ページャーは通常<span>で括られるが、それを変更する。
separator	リンクが複数出力される場合、間を分けるセパレータ。
before	リンクの前に入れる文字列。
after	リンクの後ろに入れる文字列。
first	先頭へのリンクを表す文字列。 数値を入れた場合、一件目から該当件数を表示する。
last	最後へのリンクを表す文字列。 数値を入れた場合、後ろから該当件数を表示する。
model	デフォルトのモデルではなく、別のモデルのページャを使用したい場合にモデル名を入れる。
modulus	前後を合わせて何ページ表示するか。 前3ページ、後6ページといった指定は出来ない。
url	配列で指定。 リンクのアドレスに指定した値が追加されます。
step	前後step数先のページへのリンクを作成する。
update	デフォルトは'Html'で、取れる値は'Html'か'Ajax'。 どちらの形式のリンクを作成するか。
sort,order,defaults,direction	？ '/(?:\w+\.)?(\w+)/'って何だ？

で、見ていて色々とバグっぽい挙動を見つけました。
$paginator->first(5)みたいに数値を渡すと、2～5では与えた文字に1ページ目へのリンクとなり、6以降を渡すと$options['first']=5を渡したのと同じ挙動になります。
$options['params']を$paginator->numbers()に渡すとページャが死んじゃいますし、$options['options']を$paginator->first()や$paginator->last()に渡すとやっぱり死にます。
一部のメソッド内で$optionsをectract()してるので、おかしくなるのは大抵そのせいです。
このectract()って全く意味がない使い方に見えるんだが、何故こんなことしているのだろう？
あと基本的に括りは<span>ですが、何故かfirst()とlast()だけ<div>なのは何故。

つうか、そもそも$paginatorって使いにくいよね。
未だPEAR::Pagerに勝るものはないと思う。


CakePHPの記事一覧