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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 21829 -->
<!-- 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
            <methodname>count()</methodname> 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
            <methodname>countAllItems()</methodname> Methode die auf die
            <methodname>count()</methodname> Methode des Adapters weiterleitet.
        </para>

        <para>
            Die <methodname>getItems()</methodname> 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>

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

        <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 einzelne Methode, <methodname>getPages()</methodname>, definiert. Speziell,
        </para>

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

        <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>

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

        <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>

        <programlisting language="php"><![CDATA[
$prefix = 'My_Paginator_ScrollingStyle';
$path   = 'My/Paginator/ScrollingStyle/';
Zend_Paginator::addScrollingStylePrefixPath($prefix, $path);
]]></programlisting>
    </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- <methodname>setCache()</methodname>
            Methode nur eine <classname>Zend_Cache_Core</classname> Instanz übergeben werden.
        </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>
            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
            <methodname>setCacheEnable()</methodname> verwenden.
        </para>

        <programlisting language="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>
            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 <methodname>clearPageItemCache($pageNumber)</methodname> 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>

        <programlisting language="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>
            Das Ändern das Anzahl der Teile pro Seite wird den kompletten Cache leeren, das er
            ungültig geworden wäre :
        </para>

        <programlisting language="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>
            Es ist auch möglich zu sehen welche Daten im Cache sind und direkt nach Ihnen zu fragen.
            Hierfür kann <methodname>getPageItemCache()</methodname> verwendet werden:
        </para>

        <programlisting language="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>
    </sect2>

    <sect2 id="zend.paginator.advanced.aggregator">
        <title>Zend_Paginator_AdapterAggregate Interface</title>

        <para>
            Abhängig von der Anwendung kann es gewünscht sein Objekte zu Seiten zu verarbeiten,
            dessen interne Datenstruktur identisch zu existierenden Adaptern ist, aber bei denen
            man nicht will das die eigene Kapselung gebrochen wird um Zugriff auf diese Daten
            zu erlauben. In anderen Fällen könnte ein Objekt in einer "hat einen Adapter" Relation
            stehen, statt in einer "ist ein Adapter" Relation die
            <classname>Zend_Paginator_Adapter_Abstract</classname> promotet. Für diese Fälle kann
            man das <classname>Zend_Paginator_AdapterAggregate</classname> Interface verwenden das
            sich so verhält wie das <classname>IteratorAggregate</classname> Interface der SPL
            Erweiterung von <acronym>PHP</acronym>.
        </para>

        <programlisting language="php"><![CDATA[
interface Zend_Paginator_AdapterAggregate
{
    /**
     * Return a fully configured Paginator Adapter from this method.
     *
     * @return Zend_Paginator_Adapter_Abstract
     */
    public function getPaginatorAdapter();
}
]]></programlisting>

        <para>
            Das Interface ist sehr klein und erwartet nur das eine Instanz von
            <classname>Zend_Paginator_Adapter_Abstract</classname> zurückgegeben wird. Eine
            Aggregate Instanz des Adapters wird dann von beiden erkannt, sowohl
            <code>Zend_Paginator::factory</code> als auch dem Constructor von
            <classname>Zend_Paginator</classname> und entsprechend behandelt.
        </para>
    </sect2>
</sect1>