documentation/manual/ja/module_specs/Zend_Paginator-Usage.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20854 -->
   4 <sect1 id="zend.paginator.usage">
   5     <title>使用法</title>
   6
   7     <sect2 id="zend.paginator.usage.paginating">
   8         <title>データコレクションのページ処理</title>
   9
  10         <para>
  11             ページ処理を行うには、<classname>Zend_Paginator</classname>
  12             がデータにアクセスするための汎用的な方法が必要です。
  13             そのため、データへのアクセスはすべてデータソースアダプタを用いて行います。
  14             Zend Framework には、いくつかのアダプタが標準で同梱されています。
  15         </para>
  16
  17         <table id="zend.paginator.usage.paginating.adapters">
  18             <title>Zend_Paginator 用のアダプタ</title>
  19
  20             <tgroup cols="2">
  21                 <thead>
  22                     <row>
  23                         <entry>アダプタ</entry>
  24                         <entry>説明</entry>
  25                     </row>
  26                 </thead>
  27                 <tbody>
  28                     <row>
  29                         <entry>Array</entry>
  30                         <entry><acronym>PHP</acronym> の配列を使用します。</entry>
  31                     </row>
  32                     <row>
  33                         <entry>DbSelect</entry>
  34                         <entry>
  35                             <link linkend="zend.db.select"><classname>Zend_Db_Select</classname></link>
  36                             のインスタンスを使用し、配列を返します。
  37                         </entry>
  38                     </row>
  39                     <row>
  40                         <entry>DbTableSelect</entry>
  41                         <entry>
  42                             <link linkend="zend.db.table.fetch-all"><classname>Zend_Db_Table_Select</classname></link>
  43                             のインスタンスを使用し、
  44                             <classname>Zend_Db_Table_Rowset_Abstract</classname>
  45                             のインスタンスを返します。
  46                             これは、結果セットについての追加情報
  47                             (カラム名など) を提供します。
  48                         </entry>
  49                     </row>
  50                     <row>
  51                         <entry>Iterator</entry>
  52                         <entry>
  53                             <ulink url="http://www.php.net/~helly/php/ext/spl/interfaceIterator.html"><classname>Iterator</classname></ulink>
  54                             のインスタンスを使用します。
  55                         </entry>
  56                     </row>
  57                     <row>
  58                         <entry>Null</entry>
  59                         <entry>
  60                             データのページ処理を管理する際に <classname>Zend_Paginator</classname>
  61                             を使用しません。その場合でもページ処理コントロールの機能を使うことはできます。
  62                         </entry>
  63                     </row>
  64                 </tbody>
  65             </tgroup>
  66         </table>
  67
  68         <note>
  69             <para>
  70                 指定したクエリにマッチするすべての行を取得するのではなく、
  71                 DbSelect アダプタや DbTableSelect アダプタは
  72                 現在のページの表示のための必要最小限のデータのみを取得します。
  73             </para>
  74
  75             <para>
  76                 そのため、マッチする行の総数を得るための別のクエリが動的に生成されます。
  77                 しかし、総数を直接指定したり、総数を求めるクエリを直接指定したりすることもできます。
  78                 詳細な情報は、DbSelect アダプタの
  79                 <methodname>setRowCount()</methodname> メソッドを参照ください。
  80             </para>
  81         </note>
  82
  83         <para>
  84             <classname>Zend_Paginator</classname> のインスタンスを作成するには、
  85             コンストラクタでアダプタを指定しなければなりません。
  86         </para>
  87
  88         <programlisting language="php"><![CDATA[
  89 $paginator = new Zend_Paginator(new Zend_Paginator_Adapter_Array($array));
  90 ]]></programlisting>
  91
  92         <para>
  93             利便性を確保するために、Zend Framework に同梱されているアダプタ用の静的メソッド
  94             <methodname>factory()</methodname> も用意されています。
  95         </para>
  96
  97         <programlisting language="php"><![CDATA[
  98 $paginator = Zend_Paginator::factory($array);
  99 ]]></programlisting>
 100
 101         <note>
 102             <para>
 103                 <classname>Null</classname> アダプタの場合は、
 104                 データコレクションのかわりに要素数をコンストラクタで指定します。
 105             </para>
 106         </note>
 107
 108         <para>
 109             この状態でも技術的には既に使用可能ですが、
 110             ユーザが要求したページ番号をコントローラのアクション内で教えてやる必要があります。
 111             これにより、データを読み進めていくことが可能となります。
 112         </para>
 113
 114         <programlisting language="php"><![CDATA[
 115 $paginator->setCurrentPageNumber($page);
 116 ]]></programlisting>
 117
 118         <para>
 119             ページ番号は <acronym>URL</acronym> で指定するのがもっともシンプルな方法でしょう。
 120             <classname>Zend_Controller_Router_Interface</classname>
 121             互換のルータを使うことを推奨しますが、
 122             それが必須というわけではありません。
 123         </para>
 124
 125         <para>
 126             <acronym>INI</acronym> ファイルで定義するルートの例を次に示します。
 127         </para>
 128
 129         <programlisting language="php"><![CDATA[
 130 routes.example.route = articles/:articleName/:page
 131 routes.example.defaults.controller = articles
 132 routes.example.defaults.action = view
 133 routes.example.defaults.page = 1
 134 routes.example.reqs.articleName = \w+
 135 routes.example.reqs.page = \d+
 136 ]]></programlisting>
 137
 138         <para>
 139             この設定を使った (そして Zend Framework の <acronym>MVC</acronym> コンポーネントを使った)
 140             場合、現在のページ番号を設定するコードはこのようになります。
 141         </para>
 142
 143         <programlisting language="php"><![CDATA[
 144 $paginator->setCurrentPageNumber($this->_getParam('page'));
 145 ]]></programlisting>
 146
 147         <para>
 148             それ以外にもオプションがあります。詳細は
 149             <link linkend="zend.paginator.configuration">設定</link>
 150             を参照ください。
 151         </para>
 152
 153         <para>
 154             最後に、paginator のインスタンスをビューに割り当てます。
 155             <classname>Zend_View</classname> と ViewRenderer アクションヘルパーを使っている場合は、
 156             次のようになります。
 157         </para>
 158
 159         <programlisting language="php"><![CDATA[
 160 $this->view->paginator = $paginator;
 161 ]]></programlisting>
 162     </sect2>
 163
 164     <sect2 id="zend.paginator.usage.dbselect">
 165         <title>DbSelect および DbTableSelect アダプタ</title>
 166         <para>
 167             大半のアダプタの使用法は非常にわかりやすいものです。
 168             しかし、データベースアダプタについては、
 169             データベースからのデータの取得方法や件数の数え方についてのより詳細な説明が必要です。
 170         </para>
 171
 172         <para>
 173             DbSelect アダプタや DbTableSelect アダプタを使う際には、
 174             事前にデータベースからデータを取得する必要はありません。
 175             どちらのアダプタも、自動的にデータを取得して総ページ数を計算します。
 176             もしデータベースからのデータに対して何らかの処理が必要となるのなら、
 177             アダプタの <methodname>getItems()</methodname> メソッドをアプリケーション内で継承します。
 178         </para>
 179
 180         <para>
 181             さらに、これらのアダプタは、
 182             数を数える際にデータベースの全レコードを取得するわけでは
 183             <emphasis>ありません</emphasis>。そのかわりに、アダプタが元のクエリを修正し、
 184             それに対応する COUNT クエリを作成します。
 185             Paginator は、その COUNT クエリを実行して行数を取得するのです。
 186             そのぶんデータベースとの余分なやりとりが必要となりますが、結果セット全体を取得して
 187             <methodname>count()</methodname> を使うよりは何倍も高速になります。
 188             大量のデータを扱う場合などは特にそうです。
 189         </para>
 190
 191         <para>
 192             データベースアダプタは、すべてのモダンなデータベース上で実行できる
 193             もっとも効率的なクエリを作成しようとします。
 194             しかし、使用するデータベースやスキーマ設定によっては
 195             行数を取得するのにもっと効率的な方法があるかもしれません。
 196             そのような場合のために、データベースアダプタでは独自の COUNT
 197             クエリを設定できるようにもなっています。たとえば、
 198             別々のテーブルにある blog の投稿の数を調べるには、
 199             次の用に設定すればより高速な count クエリが使用できるでしょう。
 200         </para>
 201
 202         <programlisting language="php"><![CDATA[
 203 $adapter = new Zend_Paginator_Adapter_DbSelect($db->select()->from('posts'));
 204 $adapter->setRowCount(
 205     $db->select()
 206        ->from(
 207             'item_counts',
 208             array(
 209                Zend_Paginator_Adapter_DbSelect::ROW_COUNT_COLUMN => 'post_count'
 210             )
 211          )
 212 );
 213
 214 $paginator = new Zend_Paginator($adapter);
 215 ]]></programlisting>
 216
 217         <para>
 218             この方法は、小規模なデータや単純な select クエリの場合にはあまり劇的な効果を得られません。
 219             しかし、複雑なクエリや大規模なデータを扱う場合は
 220             かなりパフォーマンスが向上することでしょう。
 221         </para>
 222     </sect2>
 223
 224     <sect2 id="zend.paginator.rendering">
 225         <title>ビュースクリプトによるページのレンダリング</title>
 226
 227         <para>
 228             ビュースクリプトを使用してページ項目のレンダリング
 229             (<classname>Zend_Paginator</classname> を使うよう設定している場合)
 230             とページ処理コントロールの表示を行います。
 231         </para>
 232
 233         <para>
 234             <classname>Zend_Paginator</classname> は <acronym>SPL</acronym> の
 235             <ulink url="http://www.php.net/~helly/php/ext/spl/interfaceIteratorAggregate.html"><classname>IteratorAggregate</classname></ulink>
 236             インターフェイスを実装しているので、
 237             項目を順次処理したり表示したりするのは簡単です。
 238         </para>
 239
 240         <programlisting language="php"><![CDATA[
 241 <html>
 242 <body>
 243 <h1>Example</h1>
 244 <?php if (count($this->paginator)): ?>
 245 <ul>
 246 <?php foreach ($this->paginator as $item): ?>
 247   <li><?php echo $item; ?></li>
 248 <?php endforeach; ?>
 249 </ul>
 250 <?php endif; ?>
 251
 252 <?php echo $this->paginationControl($this->paginator,
 253                              'Sliding',
 254                              'my_pagination_control.phtml'); ?>
 255 </body>
 256 </html>
 257 ]]></programlisting>
 258
 259         <para>
 260             最後のほうでビューヘルパーをコールしているところに注目しましょう。
 261             PaginationControl 4 つまでのパラメータを受け取ります。
 262             paginator のインスタンス、スクロール形式、
 263             そして追加パラメータの配列です。
 264         </para>
 265
 266         <para>
 267             2 番目と 3 番目のパラメータは重要です。
 268             ビュー partial はページ処理コントロールの
 269             <emphasis>見た目</emphasis>を決めるために用いられ、
 270             一方スクロール形式はその <emphasis>振る舞い</emphasis>
 271             を決めるために用いられます。ビュー partial
 272             が、次のようなページ処理コントロール形式だっととしましょう。
 273         </para>
 274
 275         <para>
 276             <inlinegraphic align="center" valign="middle"
 277                 fileref="figures/zend.paginator.usage.rendering.control.png"
 278                 format="PNG"/>
 279         </para>
 280
 281         <para>
 282             ここで "next" リンクを数回クリックしたときに、いったい何が起こるでしょう?
 283             そう、いろんなことが起こりえます。
 284             クリックし続けても現在のページがずっと中央に表示される (Yahoo!
 285             形式) かもしれませんし、
 286             表示される範囲はそのままで現在のページの位置がどんどん右にずれていき、
 287             表示範囲の最後をページでさらに "next" をクリックしたときに一番左に戻るかもしれません。
 288             ページを進めるたびにページ数そのものが増加 ("scroll")
 289             していく (Google 形式) も考えられます。
 290         </para>
 291
 292         <para>
 293             4 種類のスクロール形式が Zend Framework に組み込まれています。
 294         </para>
 295
 296         <table id="zend.paginator.usage.rendering.scrolling-styles">
 297             <title>Zend_Paginator のスクロール形式</title>
 298
 299             <tgroup cols="2">
 300                 <thead>
 301                     <row>
 302                         <entry>スクロール形式</entry>
 303                         <entry>説明</entry>
 304                     </row>
 305                 </thead>
 306                 <tbody>
 307                     <row>
 308                         <entry>All</entry>
 309                         <entry>
 310                             すべてのページを返します。
 311                             総ページ数が比較的少なめのときなど、
 312                             ドロップダウンメニュー形式でページ選択をさせる際に便利です。
 313                             そのような場合は、利用できるすべてのページを
 314                             一度にユーザに見せることになるでしょう。
 315                         </entry>
 316                     </row>
 317                     <row>
 318                         <entry>Elastic</entry>
 319                         <entry>
 320                             Google 風のスクロール形式で、
 321                             ユーザがページを移動するのにあわせて拡大・縮小します。
 322                         </entry>
 323                     </row>
 324                     <row>
 325                         <entry>Jumping</entry>
 326                         <entry>
 327                             ユーザがページを進めるにつれて、
 328                             ページ番号が表示範囲の最後に向けて進んでいきます。
 329                             表示範囲を超えると、新しい範囲の最初の位置に移動します。
 330                         </entry>
 331                     </row>
 332                     <row>
 333                         <entry>Sliding</entry>
 334                         <entry>
 335                             Yahoo! 風のスクロール形式で、
 336                             現在表示されているページが常にページ範囲の中央
 337                             (あるいは可能な限りそれに近い場所)
 338                             にあるようにします。これがデフォルトの形式です。
 339                         </entry>
 340                     </row>
 341                 </tbody>
 342             </tgroup>
 343         </table>
 344
 345         <para>
 346             4 番目、そして最後のパラメータはオプションの連想配列です。
 347             ここで、ビューパーシャルから (<varname>$this</varname> を用いて)
 348             使用したい追加変数を指定します。
 349             たとえば、ページ移動用のリンクに使用する追加の
 350             <acronym>URL</acronym> パラメータなどを含めることができます。
 351         </para>
 352
 353         <para>
 354             デフォルトのビュー partial とスクロール形式、
 355             そしてビューのインスタンスを設定してしまえば、
 356             PaginationControl のコールを完全に除去できます。
 357         </para>
 358
 359         <programlisting language="php"><![CDATA[
 360 Zend_Paginator::setDefaultScrollingStyle('Sliding');
 361 Zend_View_Helper_PaginationControl::setDefaultViewPartial(
 362     'my_pagination_control.phtml'
 363 );
 364 $paginator->setView($view);
 365 ]]></programlisting>
 366
 367         <para>
 368             これらの値をすべて設定すると、
 369             ビュースクリプト内で単純な echo
 370             文を使用するだけでページ処理コントロールをレンダリングできるようになります。
 371         </para>
 372
 373         <programlisting language="php"><![CDATA[
 374 <?php echo $this->paginator; ?>
 375 ]]></programlisting>
 376
 377         <note>
 378             <para>
 379                 もちろん、<classname>Zend_Paginator</classname>
 380                 を別のテンプレートエンジンで使用することもできます。
 381                 たとえば、Smarty を使用する場合は次のようになります。
 382             </para>
 383
 384             <programlisting language="php"><![CDATA[
 385 $smarty->assign('pages', $paginator->getPages());
 386 ]]></programlisting>
 387
 388             <para>
 389                 そして、テンプレートからは次のようにして paginator の値にアクセスします。
 390             </para>
 391
 392             <programlisting language="php"><![CDATA[
 393 {$pages->pageCount}
 394 ]]></programlisting>
 395         </note>
 396
 397         <sect3 id="zend.paginator.usage.rendering.example-controls">
 398             <title>ページ処理コントロールの例</title>
 399
 400             <para>
 401                 次のページ処理コントロールの例が、
 402                 とりあえず使い始めるにあたっての参考となることでしょう。
 403             </para>
 404
 405             <para>
 406                 検索のページ処理
 407             </para>
 408
 409             <programlisting language="php"><![CDATA[
 410 <!--
 411 See http://developer.yahoo.com/ypatterns/pattern.php?pattern=searchpagination
 412 -->
 413
 414 <?php if ($this->pageCount): ?>
 415 <div class="paginationControl">
 416 <!-- 前のページへのリンク -->
 417 <?php if (isset($this->previous)): ?>
 418   <a href="<?php echo $this->url(array('page' => $this->previous)); ?>">
 419     &lt; Previous
 420   </a> |
 421 <?php else: ?>
 422   <span class="disabled">&lt; Previous</span> |
 423 <?php endif; ?>
 424
 425 <!-- ページ番号へのリンク -->
 426 <?php foreach ($this->pagesInRange as $page): ?>
 427   <?php if ($page != $this->current): ?>
 428     <a href="<?php echo $this->url(array('page' => $page)); ?>">
 429         <?php echo $page; ?>
 430     </a> |
 431   <?php else: ?>
 432     <?php echo $page; ?> |
 433   <?php endif; ?>
 434 <?php endforeach; ?>
 435
 436 <!-- 次のページへのリンク -->
 437 <?php if (isset($this->next)): ?>
 438   <a href="<?php echo $this->url(array('page' => $this->next)); ?>">
 439     Next &gt;
 440   </a>
 441 <?php else: ?>
 442   <span class="disabled">Next &gt;</span>
 443 <?php endif; ?>
 444 </div>
 445 <?php endif; ?>
 446 ]]></programlisting>
 447
 448             <para>
 449                 項目のページ処理
 450             </para>
 451
 452             <programlisting language="php"><![CDATA[
 453 <!--
 454 See http://developer.yahoo.com/ypatterns/pattern.php?pattern=itempagination
 455 -->
 456
 457 <?php if ($this->pageCount): ?>
 458 <div class="paginationControl">
 459 <?php echo $this->firstItemNumber; ?> - <?php echo $this->lastItemNumber; ?>
 460 of <?php echo $this->totalItemCount; ?>
 461
 462 <!-- 最初のページへのリンク -->
 463 <?php if (isset($this->previous)): ?>
 464   <a href="<?php echo $this->url(array('page' => $this->first)); ?>">
 465     First
 466   </a> |
 467 <?php else: ?>
 468   <span class="disabled">First</span> |
 469 <?php endif; ?>
 470
 471 <!-- 前のページへのリンク -->
 472 <?php if (isset($this->previous)): ?>
 473   <a href="<?php echo $this->url(array('page' => $this->previous)); ?>">
 474     &lt; Previous
 475   </a> |
 476 <?php else: ?>
 477   <span class="disabled">&lt; Previous</span> |
 478 <?php endif; ?>
 479
 480 <!-- 次のページへのリンク -->
 481 <?php if (isset($this->next)): ?>
 482   <a href="<?php echo $this->url(array('page' => $this->next)); ?>">
 483     Next &gt;
 484   </a> |
 485 <?php else: ?>
 486   <span class="disabled">Next &gt;</span> |
 487 <?php endif; ?>
 488
 489 <!-- 最後のページへのリンク -->
 490 <?php if (isset($this->next)): ?>
 491   <a href="<?php echo $this->url(array('page' => $this->last)); ?>">
 492     Last
 493   </a>
 494 <?php else: ?>
 495   <span class="disabled">Last</span>
 496 <?php endif; ?>
 497
 498 </div>
 499 <?php endif; ?>
 500 ]]></programlisting>
 501
 502             <para>
 503                 ドロップダウンのページ処理
 504             </para>
 505
 506             <programlisting language="php"><![CDATA[
 507 <?php if ($this->pageCount): ?>
 508 <select id="paginationControl" size="1">
 509 <?php foreach ($this->pagesInRange as $page): ?>
 510   <?php $selected = ($page == $this->current) ? ' selected="selected"' : ''; ?>
 511   <option value="<?php
 512         echo $this->url(array('page' => $page));?>"<?php echo $selected ?>>
 513     <?php echo $page; ?>
 514   </option>
 515 <?php endforeach; ?>
 516 </select>
 517 <?php endif; ?>
 518
 519 <script type="text/javascript"
 520      src="http://ajax.googleapis.com/ajax/libs/prototype/1.6.0.2/prototype.js">
 521 </script>
 522 <script type="text/javascript">
 523 $('paginationControl').observe('change', function() {
 524     window.location = this.options[this.selectedIndex].value;
 525 })
 526 </script>
 527 ]]></programlisting>
 528         </sect3>
 529
 530         <sect3 id="zend.paginator.usage.rendering.properties">
 531             <title>プロパティの一覧</title>
 532
 533             <para>
 534                 次のオプションが、ページ処理コントロールのビュー
 535                 partial で使用可能です。
 536             </para>
 537
 538             <table id="zend.paginator.usage.rendering.properties.table">
 539                 <title>ビュー partial のプロパティ</title>
 540
 541                 <tgroup cols="3">
 542                     <thead>
 543                         <row>
 544                             <entry>プロパティ</entry>
 545                             <entry>型</entry>
 546                             <entry>説明</entry>
 547                         </row>
 548                     </thead>
 549                     <tbody>
 550                         <row>
 551                             <entry>first</entry>
 552                             <entry>integer</entry>
 553                             <entry>最初のページ番号 (つまり 1)</entry>
 554                         </row>
 555                         <row>
 556                             <entry>firstItemNumber</entry>
 557                             <entry>integer</entry>
 558                             <entry>
 559                                 このページの最初の項目の番号
 560                             </entry>
 561                         </row>
 562                         <row>
 563                             <entry>firstPageInRange</entry>
 564                             <entry>integer</entry>
 565                             <entry>
 566                                 スクロール形式で返された範囲内の最初のページ
 567                             </entry>
 568                         </row>
 569                         <row>
 570                             <entry>current</entry>
 571                             <entry>integer</entry>
 572                             <entry>現在のページ番号</entry>
 573                         </row>
 574                         <row>
 575                             <entry>currentItemCount</entry>
 576                             <entry>integer</entry>
 577                             <entry>このページの項目の数</entry>
 578                         </row>
 579                         <row>
 580                             <entry>itemCountPerPage</entry>
 581                             <entry>integer</entry>
 582                             <entry>各ページに表示できる項目の最大数</entry>
 583                         </row>
 584                         <row>
 585                             <entry>last</entry>
 586                             <entry>integer</entry>
 587                             <entry>最後のページ番号</entry>
 588                         </row>
 589                         <row>
 590                             <entry>lastItemNumber</entry>
 591                             <entry>integer</entry>
 592                             <entry>
 593                                 このページの最後の項目の番号
 594                             </entry>
 595                         </row>
 596                         <row>
 597                             <entry>lastPageInRange</entry>
 598                             <entry>integer</entry>
 599                             <entry>
 600                                 スクロール形式で返された範囲内の最後のページ
 601                             </entry>
 602                         </row>
 603                         <row>
 604                             <entry>next</entry>
 605                             <entry>integer</entry>
 606                             <entry>次のページ番号</entry>
 607                         </row>
 608                         <row>
 609                             <entry>pageCount</entry>
 610                             <entry>integer</entry>
 611                             <entry>ページ数</entry>
 612                         </row>
 613                         <row>
 614                             <entry>pagesInRange</entry>
 615                             <entry>array</entry>
 616                             <entry>
 617                                 スクロール形式で返されたページの配列
 618                             </entry>
 619                         </row>
 620                         <row>
 621                             <entry>previous</entry>
 622                             <entry>integer</entry>
 623                             <entry>前のページ番号</entry>
 624                         </row>
 625                         <row>
 626                             <entry>totalItemCount</entry>
 627                             <entry>integer</entry>
 628                             <entry>項目の総数</entry>
 629                         </row>
 630                     </tbody>
 631                 </tgroup>
 632             </table>
 633         </sect3>
 634     </sect2>
 635 </sect1>
 636 <!--
 637 vim:se ts=4 sw=4 et:
 638 -->