Ein Datenbankwidget repräsentiert die Datenbankstrukturen eines Plugins. Diese Informationen werden als JSON in der widget.json im Hauptverzeichnis des jeweiligen Plugins abgelegt. Jede dieser Dateien definiert die Datenbanktabellen und deren Spalten im jeweiligen Plugin. Zusätzlich können Beziehungen zwischen Tabellen definiert werden. Die Datenbankwidgets sind eng mit der Doctrine Implementation von brandbox verwoben.
Datenbankwidgets werden pro Mandant und Plugin gecached. Dieser Cache wird bei der Installation von brandbox, bei einem Update der brandbox oder durch manche Plugins aktualisiert. Sollte ein solcher Vorgang durch ein Plugin ausgelöst werden ist dies in der entsprechenden Dokumentation erläutert.
Aufbau des Plugins
Zwei zentrale Einstiegspunkte für das Plugin sind die Methoden \brandbox\component\doctrine\lib\entityAbstract::getWidget und \brandbox\component\doctrine\lib\repository\repositoryAbstract::getWidget. Beide liefern eine Repräsentation der jeweiligen Datenbanktabelle für welche das Repository bzw. das Entity gilt. Diese Repräsentation ist ein Objekt welches das Interface \brandbox\component\widget\lib\widget\interfaces\repositoryInterface implementiert.
Die Repräsentation eines Repositories ist nur ein Bestandteil eines Datenbankwidgets für ein Plugin. Ein Datenbankwidget unterteilt sich in die Repräsentation eines Plugins, einer Beziehung zwischen zwei Tabellen, einer Tabelle, einer Feldgruppe und eines Feldes. Jeder Bestandteil implementiert ein entsprechendes Interface.
| Bestandteil | Interface | Beschreibung |
|---|---|---|
| Plugin | \brandbox\component\widget\lib\widget\interfaces\pluginInterface | Repräsentiert ein Plugin als Ganzes. Beinhaltet alle Beziehungen welche in diesem Plugin definiert wurden und alle in diesem Plugin definierten Tabellen. |
| Beziehung zwischen zwei Tabellen | \brandbox\component\widget\lib\widget\interfaces\relationInterface | Bildet eine Eltern-Kind-Beziehung zwischen zwei Tabellen ab. |
| Tabelle (auch Repository genannt) | \brandbox\component\widget\lib\widget\interfaces\repositoryInterface | Stellt eine Datenbanktabelle dar und enthält Informationen über Name, Ergebnisspalten, Feldgruppen, etc. |
| Feldgruppe | \brandbox\component\widget\lib\widget\interfaces\groupInterface | Repräsentiert eine Gruppe von Feldern und wird von brandbox meist in Form von Reitern bei einem Formular abgebildet. Enthält Informationen über die Gruppe selbst und darin enthaltene Felder. |
| Feld | \brandbox\component\widget\lib\widget\interfaces\columnInterface | Bildet ein Feld in einer Datenbanktabelle ab. Enthält unter anderem Informationen über die Darstellung, Bezeichnung und Identifikation eines Feldes. |
Um die o.g. Repräsentationen abbilden zu können wird eine Definitionsdatei benötigt. Diese wird widget.json genannt und befindet sich im Hauptverzeichnis des jeweiligen Plugins. Die Datei wird durch das Datenbankwidget-Plugin eingelesen, verarbeitet, ggf. durch andere Plugins mit weiteren Informationen angereichert, in die o.g. Repräsentationen überführt und in einen Cache aufgenommen.
Die widget.json muss dem in bundle/component/widget/widget-schema.json definierten JSON-Schema folgen.
Verwendung
Neben den zwei o.g. Einstiegspunkten bietet die Hauptklasse \brandbox\component\widget\engine ein Reihe von Methoden durch welche Bestandteile des Datenbankwidgets abgefragt werden können.
| Methode | Beschreibung |
|---|---|
getWidget($plugin, $force = false) | Gibt den Plugin-Bestandteil des Datenbankwidgets für das in $plugin definierte Plugin zurück. Mit dem Parameter $forcekann zusätzlich eine Aktualisierung des Caches für dieses Datenbankwidget erzwungen werden. Je nach Größe, Komplexität und Abhängigkeit zur Anreicherung durch andere Plugins kann eine Cache-Aktualisierung für eine Datenbankwidget einige Zeit in Anspruch nehmen. |
getWidgets($force = false, $noAcl = false) | Liefert den Plugin-Bestandteil aller Plugins welche über eine Datenbankwidget-Definition verfügen. Der Parameter $force verhält sich analog zu o.g. Beschreibung. Mit dem Parameter $noAcl kann zusätzlich die ACL-Prüfung durch brandbox ausgehebelt werden. Dadurch werden auch Plugin-Bestandteile von Plugins geliefert auch wenn diese nicht sichtbar für den aktuellen Benutzer sind. |
getRepositoryWidgetByRepositoryIdentifier($identifier, $force = false) | Gibt die Tabellenrepräsentation (Tabellen-Bestandteil) für die Datenbanktabelle, welche durch den eindeutigen Identifikator definiert wurde, zurück. Auch hier verhält sich der Parameter $force analog zu o.g. Beschreibung. |
getRelationsByTargetTableIdentifier($identifier) | Liefert alle Beziehungsbestandteile aus allen Datenbankwidgets sofern die Kind-Tabelle dem angegebenen Identifikator entspricht. |
getRelationsBySourceTableIdentifier($identifier) | Liefert alle Beziehungsbestandteile aus allen Datenbankwidgets sofern die Eltern-Tabelle dem angegebenen Identifikator entspricht. |
Anlegen eines neuen Datenbankwidgets
Um ein Datenbankwidget für ein Plugin zu erstellen, muss im Hauptverzeichnis des jeweiligen Plugins die Datei widget.json erstellt werden. Diese muss mindestens den folgenden Inhalt besitzen:
{
"name": "pluginType/pluginName",
"tables": [],
"relations": []
}
| Eigenschaft | Beschreibung |
|---|---|
name | Der eindeutige Name des Plugins in welchem dieses Datenbankwidget erstellt wird. |
tables | Definition aller Tabellen, welche sich in diesem Plugin befinden und durch das Datenbankwidget abgebildet werden sollen. |
relations | Definition aller Eltern-Kind-Beziehungen zwischen Tabellen. Die Eltern- und/oder die Kind-Tabelle müssen sich in diesem Plugin befinden. |
Definition einer Tabelle
Tabellen die in einem Datenbankwidget eines Plugins definiert werden müssen auch in selbigem Plugin existieren. Jede Tabellendefinition muss sich innerhalb der tables-Eigenschaft befinden. Die minimal notwendige Definition umfasst folgende Eigenschaften:
{
"identifier": "",
"labels": {},
"columns": []
}
| Eigenschaft | Beschreibung |
|---|---|
identifier | Der eindeutige Identifikator der Tabelle |
labels | Ein Objekt welche den Namen der Tabelle in den verfügbaren Systemsprachen beinhaltet. {
"de": "Der Name der Tabelle in Deutsch",
"en": "Der Name der Tabelle in Englisch"
}
|
columns | Definition aller Feldgruppen und Felder in dieser Tabelle. Sollen bestimmte Felder aus einer Tabelle nicht angezeigt werden, so muss hier deren Definition einfach ausgelassen werden. |
Definition einer Feldgruppe
Feldgruppen existieren nicht als Spalte in einer Datenbanktabelle. Sie gruppieren lediglich Felder. brandbox stellt diese Feldgruppen meist als Reiter in einem Formular dar.
Felder, welche direkt in einer Tabelle und nicht innerhalb einer Gruppe definiert werden, werden der Feldgruppe "Allgemein" zugeordnet. Diese Feldgruppe darf in keinem Datenbankwidget definiert werden.
{
"identifier": "",
"formType": "group",
"labels": {},
"columns": []
}
| Eigenschaft | Beschreibung |
|---|---|
identifier | Der, innerhalb der Tabelle eindeutige, Identifikator dieser Feldgruppe |
formType | Im Falle einer Feldgruppe muss immer group eingetragen werden. |
labels | Analog zu der labels-Eigenschaft bei einer Tabellendefinition. |
columns | Analog zu der columns-Eigentschaft bei einer Tabellendefinition mit der Einschränkung, dass keine Feldgruppen in Feldgruppen definiert werden dürfen. |
Definition eines Feldes
Felder in einer Tabellendefinition repräsentieren Spalten in der jeweiligen Datenbanktabelle. Felder dürfen entweder direkt in einer Tabelle oder in einer Feldgruppe innerhalb einer Tabelle definiert werden. Die minimal Notwendige Definition:
{
"identifier": "",
"formType": "",
"labels": {}
}
| Eigenschaft | Beschreibung |
|---|---|
identifier | Der eindeutige Identifikator der entsprechenden Spalte innerhalb der Datenbanktabelle. Der hier genutzt Identifikator muss als Property in einer entsprechenden Entity-Klasse der Datenbanktabelle existieren. |
formType | Der Formulartyp welcher genutzt werden soll um dieses Feld darzustellen. Erlaubte Angaben sind unter anderem Eine vollständige Liste kann der JSON-Schema-Definition für eine Manche Formulartypen benötigen ggf. eine erweiterte Konfiguration. |
labels | Analog zu der labels-Eigenschaft bei einer Tabellen und Feldgruppendefinition. |