Pagination¶
Mit der Pagination können Sie große Listen von Items (Tabelleneinträge, News-Beiträge, Artikel-Reviews) auf mehrere Seiten aufteilen, durch die der Betrachter blättern kann. Dabei können ihm Einstellungen zur Seitengröße und zur Sortierung angeboten werden. Alle festgelegten Einstellungen werden in der Browser-SESSION festgehalten.
Die Pagination kann auf zwei verschiedene Arten verwendet werden:
- Sie übergeben der Pagination ein fertiges Array als Eingabe.
Dieses Array wird sortiert und der momentan anzuzeigende Bereich wird ausgeschnitten.- Sie übergeben der Pagination die Gesamtanzahl der Einträge als Eingabe.
Das Paginations-Objekt liefert dann lediglich anhand der gewählten Optionen eine SQLLIMIT
- und eineORDER BY
-Klausel, die Sie in Ihre eigene SQL-Abfrage einbauen können.
Dateien der Pagination¶
Datei | Funktion |
---|---|
includes/src/Pagination/Pagination.php |
Paginations-Klasse |
admin/templates/bootstrap/tpl_inc/pagination.tpl |
Template-Datei für das Backend |
templates/Evo/snippets/pagination.tpl |
Template-Datei für das Frontend (EVO-Template) |
templates/NOVA/snippets/pagination.tpl |
Template-Datei für das Frontend (NOVA-Template) |
Quick-Start¶
Erzeugen Sie eine Instanz der Pagination.
Weisen Sie der neuen Pagination einen ID-String zu, mit dem diese Pagination und ihre in der SESSION gespeicherten
Einstellungen von anderen Instanzen unterschieden werden können.
$oPaginationStandard = new Pagination('standard');
Übergeben Sie der Pagination ein Array aller Items, durch die geblättert werden soll:
(Für Daten-Listen, die sich rein aus Datenbankabfragen erzeugen lassen, siehe: Eigene SQL-Abfrage.)
$oPaginationStandard = (new Pagination('standard'))
->setItemArray($oKuponStandard_arr)
->setSortByOptions([
['cName', 'Name'],
['cCode', 'Code'],
['nVerwendungenBisher', 'Verwendungen'],
['dLastUse', 'Zuletzt verwendet']
]);
Wie hier zu sehen ist, sind alle Methoden der Pagination chainable.
Zum Schluss stellen Sie die Pagination mit assemble()
fertig:
$oPaginationStandard = (new Pagination('standard'))
->setItemArray($oKuponStandard_arr)
->setSortByOptions([
['cName', 'Name'],
['cCode', 'Code'],
['nVerwendungenBisher', 'Verwendungen'],
['dLastUse', 'Zuletzt verwendet']
])
->assemble();
Wichtig
Danach sollten keine Setter mehr aufgerufen werden!
Übergeben Sie nun das Paginations-Objekt an Smarty.
$smarty->assign('oPaginationStandard', $oPaginationStandard);
Die Einträge der momentan gewählten Blätter-Seite erhalten Sie durch $oPaginationStandard->getPageItems()
.
Durch diese Liste können Sie dann entsprechend iterieren und die darin enthaltenen Elemente im Frontend ausgeben.
{foreach $oPaginationStandard->getPageItems() as $oKupon}
...
{/foreach}
Einbindung der Templates¶
Die Templates enthalten die Seitennavigation und die Kontrollelemente zum Sortieren und Einstellen der Seitengröße.
Es gibt zwei getrennte Templates für das Backend und für das Frontend.
Backend¶
{include file='tpl_inc/pagination.tpl'
oPagination=$oPagination
cParam_arr=['tab'=>$tab]
cAnchor=$tab}
Parameter:
Parameter | Verwendung |
---|---|
oPagination |
das Paginations-Objekt |
cParam_arr (optional) |
assoziatives Array von GET-Parametern, welche von der Pagination beim Seitenblättern oder Ändern von Optionen mit durchgeschleift werden sollen |
cAnchor (optional) |
ein zusätzlicher Ziel-Anker, der mit an die URL angehängt wird (Form: #foobar ) |
Frontend¶
{include file='snippets/pagination.tpl'
oPagination=$oPagination
cParam_arr=['tab'=>$tab]
cThisUrl='/target/path'
cParam_arr=['key1' => 'val1', 'key2' => 'val2', ...]
parts=['pagi', 'label']}
Parameter:
Parameter | Verwendung |
---|---|
oPagination |
das Pagination-Objekt |
cParam_arr (optional) |
siehe oben (Backend) |
cThisUrl (optional) |
eigener Pfad der einbindenden Seite |
parts (optional) |
Mit diesem Parameter kann die Anzeige auf einzelne Komponenten
des Templates eingeschränkt werden.
|
Methoden des Paginations-Objekts¶
Methode | Funktion |
---|---|
setRange($nRange) |
Da bei sehr großen Listen auch große Seitenzahlen
entstehen können, die die Navigation zu lang werden lassen, werden Auslassungspunkte ( ... ) eingefügt. Auf der linken und rechten Seite vom gerade aktiven Seitenlink werden dann jeweils maximal $nRange benachbarte Seitenlinks angezeigt. |
setItemsPerPageOptions($nItemsPerPageOption_arr) |
Legt die Auswahloptionen für „Einträge pro Seite“ fest. Diese werden in einer Selectbox zur Auswahl angeboten. Beispiel: [5, 10, 20, 50]
|
setSortByOptions($cSortByOption_arr) |
Legt die Auswahloptionen für die Sortierung fest. Beispiel: [
['cName', 'Name'],
['cCode', 'Code'],
['nVerwendungenBisher', 'Verwendungen'],
['dLastUse', 'Zuletzt verwendet']
]
|
setItemArray($oItem_arr) |
Legt das gesamte Array aller Items fest (erste Verwendungsmethode) |
setItemCount($nItemCount) |
Legt die gesamte Anzahl der Items fest (zweite Verwendungsmethode) |
setDefaultItemsPerPage($n) |
Setzt, wie viele Einträge standardmäßig pro Seite gezeigt werden |
setItemsPerPage($nItemsPerPage) |
Übergeht die gewählte Option für „Einträge pro Seite“ und
legt diese auf den Wert $nItemsPerPage fest. Dies ist nützlich, wenn Sie keine Auswahlmöglichkeiten anbieten möchten, sondern einen festen Wert vorgeben wollen. |
Eigene SQL-Abfrage¶
Oft müssen größere Datenmengen direkt aus der Datenbank dargestellt werden.
Für diesen Zweck existiert eine weitere Verwendungsmöglichkeit, bei der dem Paginations-Objekt lediglich die
Gesamtanzahl der anzuzeigenden Elemente übergeben wird (mittels setItemCount()
).
$oPagination->setItemCount(
Shop::Container()->getDB()->query(
'SELECT count(*) AS count FROM tkunden',
ReturnType::SINGLE_OBJECT
)->count);
Das Paginations-Objekt ermittelt nun die Position im Listing, an der sich der Benutzer beim Blättern befindet. Anschließend liest das Paginations-Object nur noch diesen „Datenbereich“ aus der Datenbank, was die Mengen an Daten, die übertragen werden müssen, erheblich reduziert.
Nach der Fertigstellung mit assemble()
können Sie dann die gewünschten SQL-Klauseln für LIMIT
, und bei Bedarf
auch für ORDER
, vom Paginations-Objekt abrufen (mittels getLimitSQL()
und getOrderSQL()
).
Diese SQL-Klauseln können Sie nun in einer eigenen SQL-Abfrage verwenden, um explizit nur diese Daten aus der Datenbank abholen zu müssen:
$pageOfData = Shop::Container()->getDB()->queryPrepared(
'SELECT * FROM tredirect LIMIT :limitation ORDER BY :sorting',
[
'limitation' => $oPagination->getLimitSQL(),
'sorting' => $oPagination->getOrderSQL()
],
ReturnType::ARRAY_OF_OBJECTS);
Abschließend übergeben Sie dann wieder das Paginations-Objekt an Smarty:
$smarty->assign('pageOfData', $pageOfData);