...

v5.3

...

...

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.

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.

...

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.

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.

...

getWidget($plugin, $force = false)

...

$force

...

getWidgets($force = false, $noAcl = false)

...

getRepositoryWidgetByRepositoryIdentifier($identifier, $force = false)

...

getRelationsByTargetTableIdentifier($identifier)

...

getRelationsBySourceTableIdentifier($identifier)

...

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": []
}

...

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": []
}

...

{
  "de": "Der Name der Tabelle in Deutsch",
  "en": "Der Name der Tabelle in Englisch"
}

...

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.

{
  "identifier": "",
  "formType": "group",
  "labels": {},
  "columns": []
}

...

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": {}
}

...

...

...

Ein Widget wird in brandbox zur Definition von Eingabefeldern, Gruppen, Sets, Datenbanktabellen, Relationen und Strukturen genutzt, um auf diese im Code programmatisch zugreifen zu können. Die Datenmodellierung erweitert Widget um eine neue Definition für Formularmasken und bietet zudem die Möglichkeit bestehende Definitionen über Datenpflege zu verändern/erweitern.

Definition per widget.json

Über eine widget.json, welche pro Codepaket erstellt werden kann, werden die in diesem Codepaket vorhandenen Datenbanktabellen sowie die Beziehung zwischen Datenbanktabellen definiert. Diese Dateien werden automatisch durch brandbox verarbeitet und im o.g. Cache zwischengespeichert.

Abrufen einer Widgetdefinition

use Brandbox\Framework\Component\Widget;

$definition = $this
	->staticController(Widget\Manager::class)
	->getPackageWidget('Custom/Package')
;

// Die Definition einer Datenbanktabelle kann aber auch direkt anhand ihres Identifikators abgerufen werden ...
$definition = $this
	->staticController(Widget\Manager::class)
	->getRepositoryWidget('CustomEntityIdentifier')
;

Definition per structure.json

Eine Strukturdefinition ist anders als eine Widgetdefinition nicht direkt an ein Codepaket gebunden, wird aber ebenfalls innerhalb eines Codepaket abgelegt. Es können allerdings beliebig viele Strukturdefinition pro Codepaket erstellt werden.

Abrufen einer Strukturdefinition

use Brandbox\Framework\Component\Widget;

$definition = $this
	->staticController(Widget\Manager::class)
	->getDefinitionWidget('[Pfad zur Strukturdefinition ohne Hauptverzeichnis (/var/www/)]')
;

Definition per modelling.json

Die Modellingdefinition ist sehr ähnlich zur Strukturdefinition, sie wird allerdings zur Erweiterung von bereits existierenden Widgetdefinitionen genutzt und daher sehr ähnlich zur Datenmodellierung in brandbox. Jedes Codepaket kann eine modelling.json enthalten. Diese muss, wie die widget.json, im Hauptverzeichnis des Codepakets abgelegt werden.

Alle modelling.json-Dateien werden beim Aufbau des Widgetcaches eingelesen und mit der exitierenden Widgetstruktur vermischt. Es gibt keine programmatische Zugriffsmöglichkeit auf diese Struktur.