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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21740 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.paginator.advanced">
   5     <title>Advanced usage</title>
   6
   7     <sect2 id="zend.paginator.advanced.adapters">
   8         <title>Eigene Adapter für Quelldaten</title>
   9
  10         <para>
  11             An irgendeinem Punkt kann es passieren das man auf einen Datentyp stößt der nicht von
  12             den mitgelieferten Adaptern abgedeckt wird. In diesem Fall muß man seinen eigenen
  13             schreiben.
  14         </para>
  15
  16         <para>
  17             Um das zu tun, muß man <classname>Zend_Paginator_Adapter_Interface</classname>
  18             implementieren. Es gibt zwei Methoden die hierfür benötigt werden:
  19         </para>
  20
  21         <itemizedlist>
  22             <listitem><para>count()</para></listitem>
  23             <listitem><para>getItems($offset, $itemCountPerPage)</para></listitem>
  24         </itemizedlist>
  25
  26         <para>
  27             Zusätzlich kann es gewünscht sein einen Konstruktor zu implementieren der die
  28             Datenquelle als Parameter entgegennimmt und als geschützte oder private Eigenschaft
  29             abspeichert. Wie man das realisieren will liegt komplett in Eigenverantwortung.
  30         </para>
  31
  32         <para>
  33             Wenn man jemals schon das SPL Interface <ulink
  34                 url="http://www.php.net/~helly/php/ext/spl/interfaceCountable.html">
  35                 <code>Countable</code></ulink> verwendet hat, wird man mit
  36             <methodname>count()</methodname> umgehen können. <classname>Zend_Paginator</classname>
  37             verwendet es als totale Anzahl an Elementen in der Datensammlung. Zusätzlich bietet die
  38             <classname>Zend_Paginator</classname> Instanz eine
  39             <methodname>countAllItems()</methodname> Methode die auf die
  40             <methodname>count()</methodname> Methode des Adapters weiterleitet.
  41         </para>
  42
  43         <para>
  44             Die <methodname>getItems()</methodname> Methode ist nur etwas komplizierter. Hierfür,
  45             wird der Adapter mit einem Offset und der Anzahl an Einträgen die pro Seite dargestellt
  46             werden sollen, gefüttert. Man muß den entsprechenden Bereich an Daten zurückgeben. Für
  47             ein Array wurde das wie folgt funktionieren:
  48         </para>
  49
  50         <para>
  51             <programlisting language="php"><![CDATA[
  52 return array_slice($this->_array, $offset, $itemCountPerPage);
  53 ]]></programlisting>
  54         </para>
  55
  56         <para>
  57             Man sollte einen Blick auf die mitgelieferten Adapter werfen (alle welche
  58             <classname>Zend_Paginator_Adapter_Interface</classname> implementieren) um eine Idee zu
  59             bekommen wie man das selbst implementieren könnte.
  60         </para>
  61     </sect2>
  62
  63     <sect2 id="zend.paginator.advanced.scrolling-styles">
  64         <title>Eigene Scrolling Stile</title>
  65
  66         <para>
  67             Das Erstellen von eigenen Scrolling Stilen erfordert das man
  68             <classname>Zend_Paginator_ScrollingStyle_Interface</classname> implementiert, welche
  69             eine einzelne Methode, <methodname>getPages()</methodname>, definiert. Speziell,
  70         </para>
  71
  72         <para>
  73             <programlisting language="php"><![CDATA[
  74 public function getPages(Zend_Paginator $paginator, $pageRange = null);
  75 ]]></programlisting>
  76         </para>
  77
  78         <para>
  79             Diese Methode sollten eine untere und obere Grenze für die Seitenzahl innerhalb der
  80             sogenannten "lokalen" Seiten berechnen (das sind Seiten nahe der aktuellen Seite).
  81         </para>
  82
  83         <para>
  84             Solange es keinen anderen Scrolling Stil erweitert (siehe zum Beispiel
  85             <classname>Zend_Paginator_ScrollingStyle_Elastic</classname>, wird der eigene Scrolling
  86             Stil üblicherweise mit etwas ähnlichem sie der folgenden Codezeile enden:
  87         </para>
  88
  89         <para>
  90             <programlisting language="php"><![CDATA[
  91 return $paginator->getPagesInRange($lowerBound, $upperBound);
  92 ]]></programlisting>
  93         </para>
  94
  95         <para>
  96             Es ist nichts speziellen an diesem Aufruf; es ist mehr eine übliche Methode um die
  97             Gültigkeit der unteren und oberen Grenze zu prüfen und ein Array des Bereichs an den
  98             Paginator zurückzugeben.
  99         </para>
 100
 101         <para>
 102             Wenn man bereit ist den neuen Scrolling Stil zu benutzen, muß man
 103             <classname>Zend_Paginator</classname> bekanntgeben in welchem Verzeichnis er nachschauen
 104             muß. Um das zu tun muß das folgende ausgeführt werden:
 105         </para>
 106
 107         <para>
 108             <programlisting language="php"><![CDATA[
 109 $prefix = 'My_Paginator_ScrollingStyle';
 110 $path   = 'My/Paginator/ScrollingStyle/';
 111 Zend_Paginator::addScrollingStylePrefixPath($prefix, $path);
 112 ]]></programlisting>
 113         </para>
 114     </sect2>
 115
 116     <sect2 id="zend.paginator.advanced.caching">
 117         <title>Caching features</title>
 118
 119         <para>
 120             <classname>Zend_Paginator</classname> kann gesagt werden das es die Daten die Ihm
 121             bereits übergeben wurden, cachen soll, um zu verhindern das der Adapter sie jedes mal
 122             wenn Sie verwendet werden holen muß. Um dem Paginator zu sagen das die Daten des
 123             Adapters automatisch gecacht werden, muß der- <methodname>setCache()</methodname>
 124             Methode nur eine <classname>Zend_Cache_Core</classname> Instanz übergeben werden.
 125         </para>
 126
 127         <para>
 128             <programlisting language="php"><![CDATA[
 129 $paginator = Zend_Paginator::factory($someData);
 130 $fO = array('lifetime' => 3600, 'automatic_serialization' => true);
 131 $bO = array('cache_dir'=>'/tmp');
 132 $cache = Zend_cache::factory('Core', 'File', $fO, $bO);
 133 Zend_Paginator::setCache($cache);
 134 ]]></programlisting>
 135         </para>
 136
 137         <para>
 138             Sobald <classname>Zend_Paginator</classname> eine <classname>Zend_Cache_Core</classname>
 139             Instanz erhalten hat, werden Daten gecacht. Manchmal will man Daten nicht cachen selbst
 140             wenn man bereits eine Cacheinstanz übergeben hat. Man sollte dann hierfür
 141             <methodname>setCacheEnable()</methodname> verwenden.
 142         </para>
 143
 144         <para>
 145             <programlisting language="php"><![CDATA[
 146 $paginator = Zend_Paginator::factory($someData);
 147 // $cache ist eine Zend_Cache_Core Instanz
 148 Zend_Paginator::setCache($cache);
 149 // ... später im Skript
 150 $paginator->setCacheEnable(false);
 151 // Der Cache ist nun ausgeschaltet
 152 ]]></programlisting>
 153         </para>
 154
 155         <para>
 156             Wenn ein Cache gesetzt ist, werden Daten automatisch in Ihm gespeichert und von Ihm
 157             herausgeholt. Es kann nützlich sein den Cache manuell zu entleeren. Das kann durch den
 158             Aufruf von <methodname>clearPageItemCache($pageNumber)</methodname> getan werden. Wenn
 159             kein Parameter übergeben wird, wird der komplette Cache entleert. Optional kann ein
 160             Parameter übergeben werden der die Seitenanzahl repräsentiert die den Cache löschen :
 161         </para>
 162
 163         <para>
 164             <programlisting language="php"><![CDATA[
 165 $paginator = Zend_Paginator::factory($someData);
 166 Zend_Paginator::setCache($cache);
 167 $items = $paginator->getCurrentItems();
 168 // Seite 1 ist nun in Cache
 169 $page3Items = $paginator->getItemsByPage(3);
 170 // Seite 3 ist nun in Cache
 171
 172 // Den Cache für die Ergebnisse der Seite 3 löschen
 173 $paginator->clearPageItemCache(3);
 174
 175 // Alle Cachedaten löschen
 176 $paginator->clearPageItemCache();
 177 ]]></programlisting>
 178         </para>
 179
 180         <para>
 181             Das Ändern das Anzahl der Teile pro Seite wird den kompletten Cache leeren, das er
 182             ungültig geworden wäre :
 183         </para>
 184
 185         <para>
 186             <programlisting language="php"><![CDATA[
 187 $paginator = Zend_Paginator::factory($someData);
 188 Zend_Paginator::setCache($cache);
 189 // Einige Teile holen
 190 $items = $paginator->getCurrentItems();
 191
 192 // Alle Cachedaten werden ausgegeben :
 193 $paginator->setItemCountPerPage(2);
 194 ]]></programlisting>
 195         </para>
 196
 197         <para>
 198             Es ist auch möglich zu sehen welche Daten im Cache sind und direkt nach Ihnen zu fragen.
 199             Hierfür kann <methodname>getPageItemCache()</methodname> verwendet werden:
 200         </para>
 201
 202         <para>
 203             <programlisting language="php"><![CDATA[
 204 $paginator = Zend_Paginator::factory($someData);
 205 $paginator->setItemCountPerPage(3);
 206 Zend_Paginator::setCache($cache);
 207
 208 // Einige Teile holen
 209 $items = $paginator->getCurrentItems();
 210 $otherItems = $paginator->getItemsPerPage(4);
 211
 212 // Die gecachten Teile als zwei-dimensionales Array sehen
 213 var_dump($paginator->getPageItemCache());
 214 ]]></programlisting>
 215         </para>
 216     </sect2>
 217
 218     <sect2 id="zend.paginator.advanced.aggregator">
 219         <title>Zend_Paginator_AdapterAggregate Interface</title>
 220
 221         <para>
 222             Abhängig von der Anwendung kann es gewünscht sein Objekte zu Seiten zu verarbeiten,
 223             dessen interne Datenstruktur identisch zu existierenden Adaptern ist, aber bei denen
 224             man nicht will das die eigene Kapselung gebrochen wird um Zugriff auf diese Daten
 225             zu erlauben. In anderen Fällen könnte ein Objekt in einer "hat einen Adapter" Relation
 226             stehen, statt in einer "ist ein Adapter" Relation die
 227             <classname>Zend_Paginator_Adapter_Abstract</classname> promotet. Für diese Fälle kann
 228             man das <classname>Zend_Paginator_AdapterAggregate</classname> Interface verwenden das
 229             sich so verhält wie das <classname>IteratorAggregate</classname> Interface der SPL
 230             Erweiterung von <acronym>PHP</acronym>.
 231         </para>
 232
 233         <para>
 234             <programlisting language="php"><![CDATA[
 235 interface Zend_Paginator_AdapterAggregate
 236 {
 237     /**
 238      * Return a fully configured Paginator Adapter from this method.
 239      *
 240      * @return Zend_Paginator_Adapter_Abstract
 241      */
 242     public function getPaginatorAdapter();
 243 }
 244 ]]></programlisting>
 245         </para>
 246
 247         <para>
 248             Das Interface ist sehr klein und erwartet nur das eine Instanz von
 249             <classname>Zend_Paginator_Adapter_Abstract</classname> zurückgegeben wird. Eine
 250             Aggregate Instanz des Adapters wird dann von beiden erkannt, sowohl
 251             <code>Zend_Paginator::factory</code> als auch dem Konstruktor von Zend_Paginator
 252             und entsprechend behandelt.
 253         </para>
 254     </sect2>
 255 </sect1>