repo_zf1/documentation/manual/ja/module_specs/Zend_Paginator-Advanced.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.paginator.advanced">
    <title>高度な使用法</title>

    <sect2 id="zend.paginator.advanced.adapters">
        <title>独自のデータソースアダプタ</title>

        <para>
            同梱のアダプタでは対応していないようなデータ形式を処理したくなることもあるでしょう。
            そんな場合は自分でアダプタを書く必要があります。
        </para>

        <para>
            そのためには
            <classname>Zend_Paginator_Adapter_Interface</classname>
            を実装しなければなりません。このインターフェイスでは
            2 つのメソッドが必須となっています。
        </para>

        <itemizedlist>
            <listitem>
                <para>count()</para>
            </listitem>
            <listitem>
                <para>getItems($offset, $itemCountPerPage)</para>
            </listitem>
        </itemizedlist>

        <para>
            さらに、コンストラクタを実装してそのパラメータでデータソースを受け取り、
            protected あるいは private なプロパティにそれを保存する処理も作りたくなることでしょう。
            これをどのように実装するかはあなた次第です。
        </para>

        <para>
            これまでに SPL の
            <ulink url="http://www.php.net/~helly/php/ext/spl/interfaceCountable.html"><code>Countable</code></ulink>
            インターフェイスを使ったことがある方なら
            <code>count()</code> はおなじみでしょう。
            <classname>Zend_Paginator</classname> と組み合わせて使う場合、
            これはデータコレクション内の項目総数を返します。
            さらに、 <classname>Zend_Paginator</classname> のインスタンスには
            <code>countAllItems()</code> メソッドがあります。
            これはアダプタの <code>count()</code> メソッドへのプロキシです。
        </para>

        <para>
            <code>getItems()</code> メソッドは、ほんの少しだけ複雑です。
            これは、オフセットおよび 1 ページあたりの項目数を受け取ります。
            それにあわせて適切なデータを返す必要があります。
            配列の場合はこのようになるでしょう。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
return array_slice($this->_array, $offset, $itemCountPerPage);
]]>
            </programlisting>
        </para>

        <para>
            同梱のアダプタ (すべて <classname>Zend_Paginator_Adapter_Interface</classname>
            を実装しています) を見れば、
            自分のアダプタでこれをどのように実装すればいいのか参考になるでしょう。
        </para>
    </sect2>

    <sect2 id="zend.paginator.advanced.scrolling-styles">
        <title>独自のスクロール形式</title>

        <para>
            独自のスクロール形式を作成するには
            <classname>Zend_Paginator_ScrollingStyle_Interface</classname>
            を実装しなければなりません。このインターフェイスには
            <code>getPages()</code> メソッドが定義されています。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
public function getPages(Zend_Paginator $paginator, $pageRange = null);
]]>
            </programlisting>
        </para>

        <para>
            このメソッドは、いわゆる "ローカル" ページ
            (現在のページの周辺のページたち) の範囲のページの最小値・
            最大値を計算しなければなりません。
        </para>

        <para>
            他のスクロール形式を継承している (たとえば
            <classname>Zend_Paginator_ScrollingStyle_Elastic</classname>)
            のでない限り、自作のスクロール形式は必ずといっていいほど
            次のようなコードで終わることになるでしょう。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
return $paginator->getPagesInRange($lowerBound, $upperBound);
]]>
            </programlisting>
        </para>

        <para>
            このコールには特別な意味はありません。
            単に最小値と最大値の妥当性をチェックして、
            その範囲の配列を返しているだけです。
        </para>

        <para>
            新しいスクロール形式が用意できたら、どのディレクトリからそれを探すのかを
            <classname>Zend_Paginator</classname> に通知する必要があります。
            そのためには、次のようにします。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$prefix = 'My_Paginator_ScrollingStyle';
$path   = 'My/Paginator/ScrollingStyle/';
Zend_Paginator::addScrollingStylePrefixPath($prefix, $path);
]]>
            </programlisting>
        </para>
    </sect2>

    <sect2 id="zend.paginator.advanced.caching">
        <title>キャッシュ機能</title>

        <para>
            <classname>Zend_Paginator</classname> は、渡されたデータをキャッシュする機能があります。
            これを使用すると、アダプタが毎回データを取得することを回避できます。
            アダプタのデータを自動的にキャッシュさせるよう設定するには、
            <code>setCache()</code> メソッドに <classname>Zend_Cache_Core</classname> のインスタンスを渡します。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
$fO = array('lifetime' => 3600, 'automatic_serialization' => true);
$bO = array('cache_dir'=>'/tmp');
$cache = Zend_cache::factory('Core', 'File', $fO, $bO);
Zend_Paginator::setCache($cache);
]]>
            </programlisting>
        </para>

        <para>
            <classname>Zend_Paginator</classname> が <classname>Zend_Cache_Core</classname> のインスタンスを受け取ると、
            データがキャッシュされるようになります。キャッシュインスタンスを渡した後でも、
            場合によってはデータをキャッシュしたくないこともあるでしょう。そんな場合は
            <code>setCacheEnable()</code> を使用します。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
// $cache は Zend_Cache_Core のインスタンスです
Zend_Paginator::setCache($cache);
// ... スクリプトの後半で次のようにすると
$paginator->setCacheEnable(false);
// キャッシュが無効になります
]]>
            </programlisting>
        </para>

        <para>
            キャッシュが設定されると、データは自動的に格納され、必要に応じて取り出されるようになります。
            キャッシュを手動で空にできると便利でしょう。そうするには
            <code>clearPageItemCache($pageNumber)</code> をコールします。
            何もパラメータを渡さなければ、キャッシュ全体が空になります。
            ページ番号をパラメータとして渡すと、そのページのキャッシュを空にします。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
$items = $paginator->getCurrentItems();
// これで 1 ページ目がキャッシュに入りました
$page3Items = $paginator->getItemsByPage(3);
// これで 3 ページ目がキャッシュに入りました

// 3 ページ目のキャッシュをクリアします
$paginator->clearPageItemCache(3);

// すべてのキャッシュをクリアします
$paginator->clearPageItemCache();
]]>
            </programlisting>
        </para>

        <para>
            1 ページあたりのアイテム数を変更すると、キャッシュ全体が空になります。
            キャッシュの内容が無効になるからです。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
// アイテムを取得します
$items = $paginator->getCurrentItems();

// すべてのキャッシュデータが消去されます
$paginator->setItemCountPerPage(2);
]]>
            </programlisting>
        </para>

        <para>
            キャッシュ内のデータを見たり、直接アクセスしたりすることもできます。その場合には
            <code>getPageItemCache()</code> を使用します。
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
$paginator->setItemCountPerPage(3);
Zend_Paginator::setCache($cache);

// アイテムを取得します
$items = $paginator->getCurrentItems();
$otherItems = $paginator->getItemsPerPage(4);

// キャッシュされたアイテムを二次元配列で取得します
var_dump($paginator->getPageItemCache());
]]>
            </programlisting>
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->