Paginatoren

Paginatoren stellen Inhalte übersichtlich dar. Der Nutzer kann zwischen einer tabellarischen und einer grafischen Ansicht wählen.

Paginatoren einbinden.

Die folgenden Schritte sind notwendig um einen Paginator zu nutzen.

  1. Paginator im controller konfigurieren

  2. Paginator im Template einbinden

1. Paginator konfigurieren

Die Funktion setPaginator instanziert einen Paginator. Folgende Parameter können dabei gesetzt werden:

setPaginator(
'userP', // globaler Name des Paginators, dieser muss einmalig sein, da sich die Konfiturationen darauf beziehen
$data, // Array of objects
'id', // name des Feldes des Primärschlüssels
'index.php?action=users',// relativer Pfad
$p_config // Konfiguration, s. 1.1
);

1.0. Aufbereitung der Daten

Die Daten für Paginatoren werden in der Rege von den get-Funktionen der jeweiligen Klasse ermittelt. Für eine funktionierende Sortierung, sowie Filterung der aktuellen Datensätze - basierend auf der aktuellen Seite des Paginators wird der SQL Query der folgnende Code vorgestellt:

$order_param = orderPaginator($paginator, array('id' => 'gp',
'groups' => 'gp',
'description' => 'gp',
'creation_time' => 'gp',
'grade' => 'gr',
'semester' => 'se',
'institution' => 'ins'));

Für jedes Feld, das für eine Sortierung / Filerung relevant ist, muss definiert werden, in welcher Tabelle es sich befindet. Hier wird auf die Abkürzungen zurückgegriffen (s. Kapitel Datenbank).

Die Variable $order_param enthält nun alle Suchbegriffe, Filerungen usw. und wird wie folgt der SQL Query angehängt:

$db = DB::prepare('SELECT SQL_CALC_FOUND_ROWS gp.*, gr.grade, se.semester FROM groups AS gp, grade AS gr, semester AS se
WHERE se.id = gp.semester_id
AND gp.grade_id = gr.id AND gp.institution_id = ? '.$order_param);
$db->execute(array($id));

Damit der Paginator funktioniert, müssen die Daten als Array of Objects vorliegen. Hier exemplarisch ein Beispiel:

[
{
"id": 1,
"grade": "1. Klasse",
"description": "1. Klassenstufe (Grundschule)",
"creation_time": "0000-00-00 00:00:00",
"creator_id": 102,
"institution_id": 0,
"institution": "globaler Datensatz"
},
{
// 2. Datensatz
},
...
{
// n-ter Datensatz
}
]

Neben dem Daten-Array muss auch die Gesamtanzahl der gefundenen Datensätzen ermittelt werden. Dies geschieht idealerweise, indem man in der SQL Query dem SELECT Befehl den Befehl SQL_CALC_FOUND_ROWS nachstellt. Dies geschieht üblicherweise in der get-Funktion in der jeweiligen Klasse. Bevor nun das Array zurückgegeben wird muss folgender Code ausgeführt werden:

if ($paginator != ''){
set_item_total($paginator); //set item total based on FOUND ROWS()
}

Dadurch wird die gefundene Anzahl der Datensätze als in $_SESSION['SmartyPaginate'][$paginator]['item_total'] gespeichert.

1.1. Die Konfiguration

$p_config besteht aus einem Array, in dem festgelegt ist,

  • welche Felder aus $data angezeigt werden,

  • welche Felder mit dem Suchfeld am Paginator durchsucht werden,

  • wie die widgets (grafische Ansicht) aussehen soll,

  • welche Funktionen in der Spalte Optionen angezeigt werden.

Das folgende Beispiel zeigt exemplarisch die Konfiguration des User-Paginators

$p_config = array('id' => 'checkbox', // die erste Spalte enthält eine checkbox, mit der eine / mehrere Zeilen ausgewählt werden können.
'username' => 'Benutzername', // Die Spalte mit den Daten des Felds 'username'. Die Bezeichnung soll 'Benutzername' lauten.
'firstname' => 'Vorname',
'lastname' => 'Nachname',
'email' => 'Email',
'postalcode' => 'PLZ',
'city' => 'Ort',
/* 'state' => 'Bundesland', */ // auskommentiert: Felder, die zwar in $data vorhanden, aber nicht hier genannt sind, werden im Paginator nicht angezeigt
/* 'country' => 'Land', */
'p_search' => array('username','firstname','lastname','email','postalcode','city'), // Felder, die über das Suchfeld durchsucht werden können
'p_widget' => $p_widget, // Konfiguration der grafischen Ansicht
'p_options' => $p_options); // Funktionen die unter Optionen angezeigt werden sollen.

1.1.1 p_widget

$p_widget legt fest, welche Daten in der grafische Ansicht des Paginators angezeigt werden.

$p_widget = array('header' => 'username', // Titelzeile
'subheader01' => 'firstname, lastname', // 1. Subtitel, hier können mehrere Felder kommagetrennt angezeigt werden
'subheader02' => 'email', // 2. Subtitel
'file_id' => 'avatar_id', // Hintergrundbild
'circle_image'=> 'file_id'); // Vordergrundbild

1.1.2 p_options

$p_options legt fest, welche Funktionen in der Spalte Optionen angezeigt werden.

Im folgenden Beispiel gibt es die vier Funktionen: löschen, Eltern zuweisen, bearbeiten, Profilvorschau. Die Einstellungen jeder Funktion ist in einem Array gespeichert:

Die folgenden Einstellungen können gemacht werden:

  • onclick: javascript Funktion, die aufgerufen werden soll. Für __id__ wird die ID des aktuellen Datensatzes eingesetzt.

    • alternativ zu onclick kann auch href angegeben werden. Statt einer javascript Funktion muss dann eine url hinterlegt werden, auch in dieser kann __id__ genutzt werden.

  • capability: kann true oder false sein. Im Beispiel wird der Wert über die Funktion checkCapabilities ermittelt.

  • icon: font-awesom icon (css)

  • tooltip: Hilfetext (mouseover, bzw. firstclick auf Touchscreens )

$p_options = array('delete' => array('onclick' => "del('user',__id__);",
'capability' => checkCapabilities('user:delete', $USER->role_id, false),
'icon' => 'fa fa-trash',
'tooltip' => 'löschen'),
'parents' => array('onclick' => "formloader('parents','edit',__id__);",
'capability' => checkCapabilities('user:parentalAuthority', $USER->role_id, false),
'icon' => 'fa fa-child',
'tooltip' => 'Erziehungsberechtigung zuweisen'),
'edit' => array('onclick' => "formloader('profile','editUser',__id__);",
'capability' => checkCapabilities('user:updateUser', $USER->role_id, false),
'icon' => 'fa fa-edit',
'tooltip' => 'bearbeiten'),
'profile' => array('onclick' => "formloader('preview_user','full',__id__);",
'capability' => checkCapabilities('user:getGroups', $USER->role_id, false), //todo: use extra capability?
'icon' => 'fa fa-list-alt',
'tooltip' => 'Überblick'));

2. Paginatoren in Template einbinden

In Templates können Paginatoren wie folgt über das Smarty-Plugin html_paginator aufgerufen werden. Als Parameter muss dabei nur der Name(id), sowie der Titel des paginators gesetzt werden. Der Titel wird zur Zeit nur für die Druckausgabe benötigt.

{html_paginator id='userP' title='Benutzerliste'}