Using the JTable class/de

Das Tutorial ist für

Einführung von JTable

Die JTable Klasse ist eine Implementierung des Design-Patterns Active Record. Es wird überall in Joomla! für Erstellen, Lesen, Aktualisieren und Löschen aka CRUD Aufgaben von Einträgen in Datenbanktabellen benutzt.

Seitdem JTable eine abstrakte Klasse ist, welche die Basis für alle Datenbanktabellen-Klassen darstellt, werden einige der aufgelisteten Methoden von Unterklassen überschrieben, sodass man für weitere Informationen die Dokumentation der jeweiligen Unterklasse anschauen sollte. Abgesehen davon, werden seit Joomla! 2.5 alle Attribute in JTable automatisch generiert, basierend auf dem Schema der jeweiligen Tabelle. Das bedeutet, es ist nicht mehr nötig Klassenvariablen zu deklarieren (obwohl man es immer noch tun kann, wenn man will).

Jede erstellte physische Datenbanktabelle sollte als Vertretung eine zugehörige Klasse haben, die von von JTable abgeleitet ist. JTable stellt viele Methoden zur Verfügung, die geläufige Veränderungen der Tabelle sehr viel einfacher macht. Eine der meist gebrauchten Funktionen ist zum Beispiel das Lesen einer Tabellenreihe in den Speicher, anhand eines Primärschlüsselwertes. Das kann einfach mit dem Benutzen der load-Methode bewerkstelligt werden. Dank der save-Methode kann die Tabellenreihe dann einfach aktualisiert werden, welche dabei ebenso vorgegebene Überprüfungen auf die Tabellenfelder ausführt.

Schreiben einer JTable-Erweiterung

Um JTable zu benutzen, erstellt man eine Erweiterung der JTable Klasse. In diesem Beispiel gibt es die Tabelle "#__recipes" mit einem automatisch hochzählenden Primärschlüssel "id", welche alle Rezepte beinhaltet. Das einzige was getan werden muss, um JTable zu benutzen, ist einen Konstruktor in der erweiternden JTable-Klasse zu erstellen. Der Klassenkonstruktor wird den Eltern-Konstruktor aufrufen um die Tabelle zu erhalten: Alles was es braucht ist der Name der Tabelle, den Namen der Primärschlüsselspalte und der Datenbankinstanz.

<?php

defined('_JEXEC') or die();

class TableRecipes extends JTable
{
	public function __construct($db)
	{
		parent::__construct( '#__recipes', 'id', $db );
	}
}

Wird diese Klasse als Teil der Backend-Komponente namens 'Recipes' benutzt, würde man diesen Code in der Datei platzieren: /administrator/components/com_recipes/tables/recipes.php.

Diese Funktionalität kann sowohl in Plugins, als auch in Komponenten benutzt werden. Als generelle Regel sollte man es vermeiden, aus einem Modul heraus, in eine Datenbank zu schreiben und dafür Plugins oder Komponenten zu benutzen. Nicht zu vergessen die eingebauten Konstanten, die man beim Verlinken eines eigenen Pfades benutzen kann (außerhalb des adminstrator/{com_Komponentenname}/tables Ordners).

Benutzen einer JTable-Klassenerweiterung

Sobald die Tabellenklasse fertig ist, kann sie im Model mit der Funktion getTable() benutzt werden.

public function getTable($type = 'Recipes', $prefix = 'Table', $config = array())
{
	return JTable::getInstance($type, $prefix, $config);
}

JTable-Klassen können in irgendwelchen anderen Joomla! Erweiterungen benutzt werden, indem sie JTable::addIncludePath() im Quellcode der Erweiterung nutzen (also com_Komponentenname anstatt com_recipes):

JTable::addIncludePath(JPATH_ADMINISTRATOR . '/components/com_recipes/tables');
$row = JTable::getInstance('recipes', 'Table', array());

Man beachte, dass die kleingeschriebene Version des Suffix des Klassennamens als erster Parameter benutzt wird und der Prefix 'Table' als zweiter. Außerdem gibt die Methode getInstance() von JTable ein JTableObject mit Referenz zurückgibt, anstatt eines Wertes.

Reservierte Datenbankfeldnamen

Manche der optionalen Features von JTable brauchen speziell benannte Felder in der Datenbanktabelle. Wenn man diese zusätzlichen Funktionalitäten braucht, sollte man sicherstellen, dass diese genannten Felder in der Tabelle vorhanden sind. Die Feldnamen sollten als reserviert angesehen werden und bei dem Versuch sie, für etwas anderes als dem von JTable ursprünglich vorgesehenen Zweck zu benutzen, könnten Konflikte entstehen.

Feldname	Methoden die den Feldnamen benutzen
checked_out	checkOut, checkIn, isCheckedOut
checked_out_time	checkOut, checkIn, isCheckedOut
hits	hit
ordering	getNextOrder, reorder, move
published	publish

Check-in/Check-out

Joomla! Tabellen haben einen einfachen Mechanismus implementiert, der eine Race Condition verhindert, während Reihen in der Datenbank verändert werden. Das hängt davon ab, ob die Datenbankfelder namens "checked_out" und "checked_out_time" vorhanden sind und ob diese Felder in der view (JForm) drin sind. JTable unterstützt dann automatisch diesen Mechanismus, sodass er auch einfach in den eigenen Tabellen genutzt werden kann.

Zugriffszähler

Manche Joomla-Tabellen beinhalten ein Feld namens "hits", welches aufnimmt, wie oft die Tabellenreihe aufgerufen wurde. JTable bietet eine einfache Methode, die das Feld hochzählt: hit.

Beispiel JForm-Felder für reservierte Datenbanknamen in JTable

<field	name="state"
	type="list"
	label="JSTATUS"
	description="JFIELD_PUBLISHED_DESC"
	size="1"
	default="1">
	<option value="1">JPUBLISHED</option>
	<option	value="0">JUNPUBLISHED</option>
	<option	value="2">JARCHIVED</option>
	<option	value="-2">JTRASHED</option>
</field>
<field	name="checked_out"
	type="hidden"
	filter="unset"
	/>
<field	name="checked_out_time"
	type="hidden"
	filter="unset"
	/>
<field	name="created_user_id"
	label="JGLOBAL_FIELD_CREATED_BY_LABEL"
	type="hidden"
	filter="unset"
	/>
<field	name="created_time"
	label="JGLOBAL_FIELD_CREATED_LABEL"
	type="hidden"
	filter="unset"
	/>
<field	name="modified_user_id"
	label="JGLOBAL_FIELD_MODIFIED_BY_LABEL"
	type="hidden"
	filter="unset"
	/>
<field	name="modified_time"
	label="JGLOBAL_FIELD_MODIFIED_LABEL"
	type="hidden"
	filter="unset"
	/>
<field	name="hits"
	type="text"
	id="hits"
	class="readonly"
	label="JGLOBAL_HITS"
	size="20"
	readonly="true"
	filter="unset"
	/>

Praktische Klassenfunktionen

• load Methode um einen Datensatz, anhand seines Primärschlüsselwertes (id) oder einer Kombination von Kriterien, in ein JTable-Objekt zu laden.
• bind Methode um ein JTable-Objekt an ein generisches key/value-Array zu binden. Das heißt, sie weist die Werte eines Arrays einem JTable-Objekt und dessen Attributen zu, bei denen die Array-Schlüssel passen.
• check Methode um Daten zu überprüfen, bevor sie im Objekt abgelegt werden.
• store Methode um das Objekt in der Datenbank abzulegen.
• save Methode die als Abkürzung zum Verbinden, Prüfen und Speichern einer JTable-Instanz in die Datenbanktabelle dient.

Siehe auch

• Teil 7 von J3.x:Developing an MVC Component/Using the database
• Teil 14 von J2.5:Developing a MVC Component/Adding configuration

Zusammenfassung

Wenn JTable richtig erweitert wurde, beinhaltet die Klasse alle grundlegenden Funktionen die man braucht, um Einträge in einer Datenbanktabelle zu verwalten und aufzurufen.