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

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

    <sect2 id="zend.paginator.advanced.adapters">
        <title>Eigene Adapter für Quelldaten</title>

        <para>
            An irgendeinem Punkt kann es passieren das man auf einen Datentyp stößt der nicht von den
            mitgelieferten Adaptern abgedeckt wird. In diesem Fall muß man seinen eigenen schreiben.
        </para>

        <para>
            Um das zu tun, muß man <classname>Zend_Paginator_Adapter_Interface</classname> implementieren. Es gibt
            zwei Methoden die hierfür benötigt werden:
        </para>

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

        <para>
            Zusätzlich kann es gewünscht sein einen Konstruktor zu implementieren der die Datenquelle als
            Parameter entgegennimmt und als geschützte oder private Eigenschaft abspeichert. Wie man das
            realisieren will liegt komplett in Eigenverantwortung.
        </para>

        <para>
            Wenn man jemals schon das SPL Interface
            <ulink url="http://www.php.net/~helly/php/ext/spl/interfaceCountable.html"><code>Countable</code></ulink>
            verwendet hat, wird man mit <code>count()</code> umgehen können. <classname>Zend_Paginator</classname> verwendet
            es als totale Anzahl an Elementen in der Datensammlung. Zusätzlich bietet die
            <classname>Zend_Paginator</classname> Instanz eine <code>countAllItems()</code> Methode die auf die
            <code>count()</code> Methode des Adapters weiterleitet.
        </para>

        <para>
            Die <code>getItems()</code> Methode ist nur etwas komplizierter. Hierfür, wird der Adapter mit einem
            Offset und der Anzahl an Einträgen die pro Seite dargestellt werden sollen, gefüttert. Man muß den
            entsprechenden Bereich an Daten zurückgeben. Für ein Array wurde das wie folgt funktionieren:
        </para>

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

        <para>
            Man sollte einen Blick auf die mitgelieferten Adapter werfen (alle welche
            <classname>Zend_Paginator_Adapter_Interface</classname> implementieren) um eine Idee zu bekommen wie man das
            selbst implementieren könnte.
        </para>
    </sect2>

    <sect2 id="zend.paginator.advanced.scrolling-styles">
        <title>Eigene Scrolling Stile</title>

        <para>
            Das Erstellen von eigenen Scrolling Stilen erfordert das man
            <classname>Zend_Paginator_ScrollingStyle_Interface</classname> implementiert, welche eine eizelne Methode,
            <code>getPages()</code>, definiert. Speziell,
        </para>

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

        <para>
            Diese Methode sollten eine untere und obere Grenze für die Seitenzahl innerhalb der sogenannten
            "lokalen" Seiten berechnen (das sind Seiten nahe der aktuellen Seite).
        </para>

        <para>
            Solange es keinen anderen Scrolling Stil erweitert (siehe zum Beispiel
            <classname>Zend_Paginator_ScrollingStyle_Elastic</classname>, wird der eigene Scrolling Stil üblicherweise mit
            etwas ähnlichem sie der folgenden Codezeile enden:
        </para>

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

        <para>
            Es ist nichts speziellen an diesem Aufruf; es ist mehr eine übliche Methode um die Gültigkeit der
            unteren und oberen Grenze zu prüfen und ein Array des Bereichs an den Paginator zurückzugeben.
        </para>

        <para>
            Wenn man bereit ist den neuen Scrolling Stil zu benutzen, muß man <classname>Zend_Paginator</classname>
            bekanntgeben in welchem Verzeichnis er nachschauen muß. Um das zu tun muß das folgende ausgeführt
            werden:
        </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>Caching features</title>

        <para>
            <classname>Zend_Paginator</classname> kann gesagt werden das es die Daten die Ihm bereits übergeben wurden,
            cachen soll, um zu verhindern das der Adapter sie jedes mal wenn Sie verwendet werden holen muß.
            Um dem Paginator zu sagen das die Daten des Adapters automatisch gecacht werden, muß der-
            <code>setCache()</code> Methode nur eine <classname>Zend_Cache_Core</classname> Instanz übergeben werden.
        </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>
            Sobald <classname>Zend_Paginator</classname> eine <classname>Zend_Cache_Core</classname> Instanz erhalten hat, werden Daten gecacht. Manchmal will
            man Daten nicht cachen selbst wenn man bereits eine Cacheinstanz übergeben hat. Man sollte dann
            hierfür <code>setCacheEnable()</code> verwenden.
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
// $cache ist eine Zend_Cache_Core Instanz
Zend_Paginator::setCache($cache);
// ... später im Skript
$paginator->setCacheEnable(false);
// Der Cache ist nun ausgeschaltet
]]>
            </programlisting>
        </para>

        <para>
            Wenn ein Cache gesetzt ist, werden Daten automatisch in Ihm gespeichert und von Ihm herausgeholt.
            Es kann nützlich sein den Cache manuell zu entleeren. Das kann durch den Aufruf von
            <code>clearPageItemCache($pageNumber)</code> getan werden. Wenn kein Parameter übergeben wird,
            wird der komplette Cache entleert. Optional kann ein Parameter übergeben werden der die
            Seitenanzahl repräsentiert die den Cache löschen :
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
$items = $paginator->getCurrentItems();
// Seite 1 ist nun in Cache
$page3Items = $paginator->getItemsByPage(3);
// Seite 3 ist nun in Cache

// Den Cache für die Ergebnisse der Seite 3 löschen
$paginator->clearPageItemCache(3);

// Alle Cachedaten löschen
$paginator->clearPageItemCache();
]]>
            </programlisting>
        </para>

        <para>
            Das Ändern das Anzahl der Teile pro Seite wird den kompletten Cache leeren, das er ungültig
            geworden wäre :
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$paginator = Zend_Paginator::factory($someData);
Zend_Paginator::setCache($cache);
// Einige Teile holen
$items = $paginator->getCurrentItems();

// Alle Cachedaten werden ausgegeben :
$paginator->setItemCountPerPage(2);
]]>
            </programlisting>
        </para>

        <para>
            Es ist auch möglich zu sehen welche Daten im Cache sind und direkt nach Ihnen zu fragen. Hierfür
            kann <code>getPageItemCache()</code> verwendet werden:
        </para>

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

// Einige Teile holen
$items = $paginator->getCurrentItems();
$otherItems = $paginator->getItemsPerPage(4);

// Die gecachten Teile als zwei-dimensionales Array sehen
var_dump($paginator->getPageItemCache());
]]>
            </programlisting>
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->