Widget
- Dominik Hisler
- Sebastian Schulz
In diesem Tutorial erhalten Sie einen Überblick über die Widgets von brandbox sowie deren Einsatzzwecke mit Codebeispielen. Sie können weitere Informationen über die Widgets in der entsprechenden Entwicklerdokumentation finden.
Was sind Widgets?
Ein Widget wird in brandbox genutzt um Eingabefelder sowie deren Anordnung innerhalb von Sets und Gruppen zu beschreiben. Diese Definitionen werden unter anderem von den nachfolgenden Komponenten als Basis für deren Aufgaben eingesetzt:
Validierung (
Brandbox/Validator)Formulare (
Component/Form)Datenveränderung (
Brandbox/Casting)
Ein Widget basiert entweder auf einer klassischen Widgetdefinition (widget.json) oder einer Strukturdefinition (structure.json). Mit der Strukturmodellierung (ehemals Datenmodellierung) können die Widgets auch auf Basis einer benutzerdefinierten Konfiguration definiert werden. Zudem kann über die Strukturmodellierung oder eine Modellierungsdefinition (modelling.json) eine klassische Widgetdefinition erweitert und verändert werden. Das nachfolgende Diagramm gibt Ihnen eine Übersicht über die Zusammenhänge und Abhängigkeiten der einzelnen Widgetbestandteile.
Was sind Identifikatoren?
Jeder Teil einer Definition verfügt über einen Identifikator welcher entweder global oder lokal eindeutig sein muss. Zudem sind manche Identifikatoren durch äußere Umstände bereits vorgegeben und können innerhalb der Definition nicht verändert werden. Frei wählbare Identifikatoren dürfen nur aus den Zeichen a bis z, A bis Z sowie den Ziffern 0 bis 9 bestehen.
Wie definiere ich einen Widgetbestandteil?
Jedes Codepaket in brandbox kann eine Widget-, eine Modellierungs- und mehrere Strukturdefinitionen besitzen. Diese Definitionen werden in einer JSON-Datei abgelegt welche einem entsprechenden JSON-Schema folgen muss. Diese Schemata können auch in PHPStorm zur Validierung und Hilfestellung beim Erstellen dieser Dateien eingebunden werden.
Bestandteil | Dateiname | JSON-Schema |
|---|---|---|
Widgetdefinition |
|
|
Modellierungsdefinition |
|
|
Strukturdefinition |
|
|
Wann benötige ich eine Widgetdefinition?
Sobald ein Codepaket in brandbox über Entities für Doctrine verfügt, muss eine widget.json für das entsprechende Paket erstellt werden um die Entity (Tabelle) sowie deren Eigenschaften (Eingabefelder) zu beschreiben und optional in Gruppen und Sets zu organisieren. Eine Eigenschaft muss nicht zwingend in der Widgetdefinition enthalten sein, die Entity selbst allerdings schon. Der Klassenname der erstellten Entity entspricht dem Tabellenidentifikator und die Namen der Eigenschaften den Eingabefeldidentifikatoren.
Wann benötige ich eine Modellierungsdefinition?
Ähnlich zur Strukturmodellierung kann eine Modellierungsdefinition genutzt werden um bereits existierende Tabellen zu erweitern. In einer Modellierungsdefinition können keine neuen Tabellen definiert werden. Zusammen mit der Eigenschaftserweiterung aus Doctrine können hiermit "echte" Tabellenspalten ergänzt werden. Wenn keine Eigenschaftserweiterung genutzt wird, muss das zu erweiternde Entity mindestens ein ODM-Entity sein.
Wann benötige ich eine Strukturdefinition?
Eine Strukturdefinition wird genutzt um ein Widget ohne Tabellenbezug zu definieren. Mögliche Einsatzzwecke sind Formulare in Modals.
Codebeispiele
Wie rufe ich eine Widgetdefinition ab?
use Brandbox\Framework\Brandbox\Widget;
$definition = $this
->staticController(Widget\Manager::class)
->getRepositoryWidget('CustomEntityIdentifier')
;Wie rufe ich eine Strukturdefinition ab?
use Brandbox\Framework\Brandbox\Widget;
$definition = $this
->staticController(Widget\Manager::class)
->getDefinitionWidget('brandbox/custom-app/src/Custom/Package/Lib/Structure/CustomDefinition.json')
;Wie erstelle ich ein Formular aus einem Widget?
use Brandbox\Framework\Component\Form;
$builder = $this
->staticController(Form\Manager::class)
->getStandardBuilder()
;
$builder->container = $definition;
$builder->prefix = 'CustomFormPrefix';
$builder->payloads = [
'FieldIdentifierA' => 'Eingabefeldwert A'
];
$element = $this
->staticController(Form\Manager::class)
->getFrameworkForm($builder)
;