repo_zf1Php7/documentation/manual/en/module_specs/Zend_Paginator-Advanced.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.paginator.advanced">
    <title>Advanced usage</title>

    <sect2 id="zend.paginator.advanced.adapters">
        <title>Custom data source adapters</title>

        <para>
            At some point you may run across a data type that is not covered by
            the packaged adapters. In this case, you will need to write your
            own.
        </para>

        <para>
            To do so, you must implement
            <classname>Zend_Paginator_Adapter_Interface</classname>. There are two
            methods required to do this:
        </para>

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

        <para>
            Additionally, you'll want to implement a constructor that takes
            your data source as a parameter and stores it as a protected or
            private property. How you wish to go about doing this
            specifically is up to you.
        </para>

        <para>
            If you've ever used the SPL interface
            <ulink url="http://www.php.net/~helly/php/ext/spl/interfaceCountable.html"><code>Countable</code></ulink>,
            you're familiar with <code>count()</code>. As used with
            <classname>Zend_Paginator</classname>, this is the total number of items
            in the data collection.
            Additionally, the <classname>Zend_Paginator</classname> instance provides a method
            <code>countAllItems()</code> that proxies to the adapter
            <code>count()</code> method.
        </para>

        <para>
            The <code>getItems()</code> method is only slightly more
            complicated. For this, your adapter is supplied with an offset and
            the number of items to display per page. You must return the
            appropriate slice of data. For an array, that would be:
        </para>

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

        <para>
            Take a look at the packaged adapters (all of which implement the
            <classname>Zend_Paginator_Adapter_Interface</classname>) for ideas of how you
            might go about implementing your own.
        </para>
    </sect2>

    <sect2 id="zend.paginator.advanced.scrolling-styles">
        <title>Custom scrolling styles</title>

        <para>
            Creating your own scrolling style requires that you implement
            <classname>Zend_Paginator_ScrollingStyle_Interface</classname>, which defines
            a single method, <code>getPages()</code>. Specifically,
        </para>

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

        <para>
            This method should calculate a lower and upper bound for page
            numbers within the range of so-called "local" pages (that is, pages
            that are nearby the current page).
        </para>

        <para>
            Unless it extends another scrolling style (see
            <classname>Zend_Paginator_ScrollingStyle_Elastic</classname> for an example),
            your custom scrolling style will inevitably end with something
            similar to the following line of code:
        </para>

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

        <para>
            There's nothing special about this call; it's merely a convenience
            method to check the validity of the lower and upper bound and
            return an array of the range to the paginator.
        </para>

        <para>
            When you're ready to use your new scrolling style, you'll need to
            tell <classname>Zend_Paginator</classname> what directory to look in. To do
            that, do the following:
        </para>

        <para>
            <programlisting language="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>Caching features</title>

        <para>
            <classname>Zend_Paginator</classname> can be told to cache the data it has already
            passed on, preventing the adapter from fetching them each time they are used.
            To tell paginator to automatically cache the adapter's data, just pass to
            its <code>setCache()</code> method a <classname>Zend_Cache_Core</classname> instance.
        </para>

        <para>
            <programlisting language="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>
            As far as <classname>Zend_Paginator</classname> has got a <classname>Zend_Cache_Core</classname> instance, data will
            be cached. Sometimes you would like not to cache data even if you already passed
            a cache instance. You should then use <code>setCacheEnable()</code> for that.
        </para>

        <para>
            <programlisting language="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
// $cache is a Zend_Cache_Core instance
Zend_Paginator::setCache($cache);
// ... later on the script
$paginator->setCacheEnable(false);
// cache is now disabled
]]></programlisting>
        </para>

        <para>
            When a cache is set, data are automatically stored in it and pulled out from
            it. It then can be useful to empty the cache manually. You can get this done by
            calling <code>clearPageItemCache($pageNumber)</code>.
            If you don't pass any parameter, the whole cache will be empty. You can optionally
            pass a parameter representing the page number to empty in the cache:
        </para>

        <para>
            <programlisting language="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
$items = $paginator->getCurrentItems();
// page 1 is now in cache
$page3Items = $paginator->getItemsByPage(3);
// page 3 is now in cache

// clear the cache of the results for page 3
$paginator->clearPageItemCache(3);

// clear all the cache data
$paginator->clearPageItemCache();
]]></programlisting>
        </para>

        <para>
            Changing the item count per page will empty the whole cache
            as it would have become invalid:
        </para>

        <para>
            <programlisting language="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
// fetch some items
$items = $paginator->getCurrentItems();

// all the cache data will be flushed:
$paginator->setItemCountPerPage(2);
]]></programlisting>
        </para>

        <para>
            It is also possible to see the data in cache and ask for them directly.
            <code>getPageItemCache()</code> can be used for that:
        </para>

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

// fetch some items
$items = $paginator->getCurrentItems();
$otherItems = $paginator->getItemsPerPage(4);

// see the cached items as a two-dimension array:
var_dump($paginator->getPageItemCache());
]]></programlisting>
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->