17.16 Pager 
| Besprochene Version: 2.2.76 | Lizenz: PHP-Lizenz |
| Klassendatei(en): Pager/Pager.php | |
Das Paket Pager gehört nicht zu den eigentlichen HTML-Paketen. Es wurde erst nachträglich den HTML-Paketen zugeordnet. Daher liegt die dazugehörige Datei auch im Verzeichnis Pager und nicht in HTML.
Möchten Sie eine umfangreiche Anzahl von Datensätzen ausgeben, stellt sich oft das Problem, dass die Daten nicht auf einmal ausgegeben werden können. Also müssen die Daten »durchgeblättert« werden. Das kann allerdings, wenn Sie es selbst programmieren müssen – recht aufwändig sein. Das Paket Pager nimmt Ihnen diese Arbeit ab. Es stellt Ihnen Möglichkeiten zum Durchblättern der Daten und zum automatischen Generieren einer Navigation zur Verfügung.
Der Code aus Listing 17.32 und Abbildung 17.18 veranschaulichen das.
require_once ('Pager/Pager.php');
// Daten, die ausgegeben werden sollen
$daten = array('Meier', 'Müller', 'Mayer', 'Paulsen',
'Schoirer', 'Möhrke','Gustavson',
'Simpson', 'Troy', 'Bender', 'Adams',
'Suraski','Gutmans','Lerdorf'
);
// Parameter zum Initialisieren des Objekts
$params = array(
'mode' => 'Jumping', // Jumping Mode
'perPage' => 4, //Datensaetze pro Seite
'delta' => 3, //Seiten in der Navigation
'itemData' => $daten // Auszugebende Daten
);
// Neues Objekt instanziieren
$pager = Pager::factory($params);
// Daten für diese Seite auslesen
$akt_daten = $pager->getPageData();
// Navigationsdaten auslesen
$navi = $pager->getLinks();
// Navigation ausgeben lassen
echo "$navi[all]<p />";
// Einzelne Datensaetze ausgeben
foreach ($akt_daten as $name)
{
echo "Name: $name<br />";
}Listing 17.32 Ausgabe von Daten mit PEAR::Pager
Die auszugebenden Daten sind als Array an die Factory-Methode zu übergeben. Dieses Array wird Teil eines assoziativen Arrays, in dem auch andere Parameter spezifiziert werden, die das Verhalten der Klasse beeinflussen.
Abbildung 17.18 Ausgabe im Browser
Zuerst ist hier sicher der Schlüssel mode zu nennen, mit dem der Navigationsmodus festgelegt werden kann. Neben 'Jumping' können Sie hier auch 'Sliding' angeben. Die beiden Modi unterscheiden sich primär in der Navigation. Nachfolgend finden Sie Beispiele, wie die beiden Modi sich verhalten, wenn in beiden Fällen delta=3 angegeben wurde und von der ersten Seite beginnend weitergeblättert wird.
| Jumping | Sliding |
| 1 2 3 Next >> | 1 | 2 | 3 | 4 | 5 | 6 | 7 » [9] |
| << Back 1 2 3 Next >> | [1] « 1 | 2 | 3 | 4 | 5 | 6 | 7 » [9] |
| << Back 1 2 3 Next >> | [1] « 1 | 2 | 3 | 4 | 5 | 6 | 7 » [9] |
| << Back 4 5 6 Next >> | [1] « 1 | 2 | 3 | 4 | 5 | 6 | 7 » [9] |
| << Back 4 5 6 Next >> | [1] « 2 | 3 | 4 | 5 | 6 | 7 | 8 » [9] |
Im Modus »Jumping« werden also immer so viele direkte Links angezeigt, wie die Zahl vorgibt, die in delta abgelegt ist. Wenn Sie das Sliding nutzen, werden doppelt so viele Links plus ein direkter Link angezeigt. Mit einem delta von drei ergeben sich also sieben direkte Links.
Der zweite große Unterschied ist, dass beim Jumping die aktuelle Seite in der Navigation von links nach rechts »durchläuft«, und wenn das Ende erreicht wurde, dann springt die Navigation um den Wert von delta weiter. Beim Sliding wird die aktuelle Seite immer in der Mitte gehalten, sobald die Mitte erreicht wurde. Bei jedem Weiterblättern wird die Navigation dann um eins verschoben. Wie Sie in Abbildung 17.18 sehen können, wird dabei die Nummer der aktuellen Seite als Query-String übergeben, also an die URL der Datei angehängt.
Der Schlüssel perPage enthält die Information, wie viele Datensätze pro Seite angezeigt werden sollen.
Mit diesen Schlüsseln kommt man im Normalfall schon recht weit. Aber Sie können das Verhalten des Pakets noch mit vielen weiteren Array-Inhalten steuern. Die wichtigsten Schlüssel finden Sie in Tabelle 17.10.
Die Methode getPageData() liefert jeweils den Ausschnitt aus dem Array mit den Daten für die aktuelle Seite zurück. Möchten Sie nur die Daten für die aktuelle Seite haben, liefert die Methode sie Ihnen direkt zurück. Sie können ihr aber auch die Nummer einer Seite übergeben, deren Daten Sie explizit auslesen wollen. Adressieren Sie dabei ein Set von Daten, das nicht existiert, liefert die Methode false zurück.
Die Methode getLinks() stellt Ihnen ein Array mit Daten zur Verfügung, aus dem Sie die Navigation erstellen können. Der Schlüssel all, der in Listing 17.32 genutzt wird, verweist hierbei auf eine komplett fertige Navigationszeile, die direkt ausgegeben werden kann.
Das Array kann sowohl indiziert als auch assoziativ genutzt werden. Die Bedeutung der Schlüssel und Index-Werte ist in Tabelle 17.11 beschrieben.
| Wert | Schlüssel | Bedeutung |
| 0 | back | Link auf die vorhergehende Seite |
| 1 | pages | Direkte Links auf die Seiten im Anzeigebereich |
| 2 | next | Link auf die nächste Seite |
| 3 | first | Link auf die erste Seite |
| 4 | Last | Link auf die letzte Seite |
| 5 | all | Komplett fertige Navigationszeile |
Mit diesen Werten können Sie also recht schnell eine individuelle Navigation aufbauen.
Dadurch, dass die Links in diesem Fall schon vorkonfiguriert sind, ist das System nur bedingt flexibel. Der Entwickler war aber so freundlich, eine recht große Anzahl an Methoden vorzusehen, auf deren Basis Sie selbst eine Navigation erstellen können.
Die ID, also die Nummer der aktuellen Seite können Sie hierbei jeweils mit getCurrentpageID() auslesen. Um nicht selbst rechnen zu müssen, können Sie die ID der vorhergehenden und nächsten Seite mit getPreviousPageID() und getNextPageID() auslesen. Diese beiden Methoden haben auch den Vorteil, dass sie false zurückgeben, wenn keine vorhergehende oder nächste Seite existiert.
Die Gesamtzahl der Seiten stellt numPages() Ihnen zur Verfügung, und die Gesamtzahl der enthaltenen Datensätze kann mit numItems() ausgelesen werden. Möchten Sie herausfinden, welche Datensätze auf einer bestimmten Seite zur Verfügung stehen, hilft getOffsetByPageID() Ihnen weiter. Die Methode bekommt die ID einer Seite übergeben oder nutzt die ID der aktuellen, wenn Sie nichts anderes spezifizieren, und liefert Ihnen ein Array aus zwei Elementen zurück. Die erste Zahl spezifiziert dabei die Nummer des ersten Datensatzes auf der Seite, und die zweite die Nummer des letzten Datensatzes. Arbeiten Sie im Modus Jumping, so ist auch eine Umkehrfunktion namens getPageIdByOffset() definiert. Diese Methode, die es im Sliding-Modus nicht gibt, bekommt die Nummer eines Datensatzes übergeben, berechnet, auf welcher Seite dieser zu finden ist, und gibt die ID dieser Seite zurück.
getPageRangeByPageId() bekommt die ID einer Seite übergeben und gibt die IDs der ersten und der letzten Seite, die in der Navigation ausgegeben werden, als Array zurück.
Um möglichst elegant prüfen zu können, ob vor oder hinter der aktuellen Seite noch weitere folgen, können Sie isFirstPage() und isLastPage() nutzen. Beide Methoden bekommen keine Parameter übergeben und teilen Ihnen über einen booleschen Wert mit, ob die aktuelle Seite die erste bzw. die letzte Seite ist. Sollten Sie feststellen, dass Sie sich auf der letzten Seite befinden, stellt sich natürlich die Frage, ob für die letzte Seite noch genauso viele Datensätze vorliegen wie für die vorhergehenden Seiten. In diesem Fall ist isLastePageComplete() sehr hilfreich. Sollte die letzte Seite genauso viele Datensätze enthalten wie die vorhergehenden, bestätigt die Methode das mit einem true und liefert andernfalls ein false.
