Plugin: Boxxer - API
Mit Warly Boxxer lassen sich Boxen auch in den eigenen Datensätzen nutzen. Die Einbindung ist denkbar einfach.
- Durch einen ObjectType wird Boxxer für den Datensatz aktiviert
- Das Layout der Boxen wird im BoxxerObject konfiguriert
- Die Einbindung in das Formulars des Datensatzes erfolgt durch eine Zeile Code
- Die Anzeige der Boxen im Frontend erfolgt durch eine Zeile Code
1. ObjectType
Boxxer wird per ObjectType im eigenen Datensatz aktiviert. Hier eine Beispielkonfiguration:
<type>
<name>de.warly.plugin.boxxer.object.article</name>
<definitionname>de.warly.plugin.boxxer.object</definitionname>
<classname>wcf\system\boxxer\object\ArticleBoxxerObject</classname>
<formClassName>wcf\acp\form\ArticleAddForm</formClassName>
<pageClassName>wcf\page\AbstractArticlePage</pageClassName>
</type>
2. BoxxerObject
Das im ObjectType angegebene BoxxerObject muss das Interface wcf\system\boxxer\object\IBoxxerObject implementieren. Es gibt die abstrakte Klasse wcf\system\boxxer\object\AbstractBoxxerObject, welche alle Methoden des Interfaces überschreibt, sodass nur noch die Methoden implementiert werden müssen, in denen etwas passiert.
Diese API dokumentiert die Verwendung von wcf\system\boxxer\object\AbstractBoxxerObject als Basis. Eine eigene Implementierung von wcf\system\boxxer\object\IBoxxerObject ist nicht empfohlen.
$boxxerObjectType
Gibt den ObjectType des BoxxerObjects an. Dies ist der name aus Schritt 1.
isBoxxerFormApplicable(AbstractForm $form) Boolean
Gibt an, ob Boxxer für das übergebene Formular (welches vom Typ formClassName aus dem ObjectType ist) aktiviert werden soll. Standardmäßig wird hier true zurückgegeben. Diese Methode muss nur überschrieben werden, wenn Boxxer nur unter gewissen Bedingungen aktiviert werden soll.
getEditFormLink(int $objectID) String
Gibt die URL für das Bearbeitenformular des Datensatzes zurück. Hier sollte eine URL zurückgegeben werden, die im besten Fall direkt zu Boxxer springt. Beispiel:
/**
* @inheritDoc
*/
public function getEditFormLink(int $objectID) {
return LinkHandler::getInstance()->getLink('ArticleEdit', ['id' => $objectID], '#boxxer');
}
configureLayout(BoxxerLayout $layout) Void
In dieser Methode wird das Layout für Boxxer konfiguriert, also welche Positionen der Datensatz unterstützt. Das Layout besteht aus Reihen, mit ein oder mehreren Spalten, die wiederum ein oder mehrere Positionen enthält.
Ein Layout mit nur einer Position könnte so konfiguriert werden:
$layout->appendRow(BoxxerLayoutRow::create([
BoxxerLayoutPosition::create('item.content', BoxxerLayoutPosition::PAGE_CONTENT_BOTTOM)
]));
Damit würde die Position item.content erstellt werden, die Boxen der Standardposition "Im Inhaltsbereich unten" erlaubt.
Eine genaue Erklärung welche Möglichkeiten es bei der Layouterstellung gibt, gibt es weiter unten im Abschnitt Layout erstellen (Bald).
Wenn der Datensatz auf einer eigenen Seite dargestellt wird, können neben eigenen Positionen auch die Standard-Seitenpositionen verwendet werden. Hier kann konfiguriert werden, welche Seitenpositionen der Datensatz bzw. die Seite auf dem der Datensatz angezeigt wird, unterstützen soll. Ein Beispiel:
$layout->supportPagePositions([
BoxxerLayoutPosition::PAGE_CONTENT_TOP,
BoxxerLayoutPosition::PAGE_CONTENT_BOTTOM,
BoxxerLayoutPosition::PAGE_SIDEBAR_RIGHT
]);
Hier wird angegeben, dass das Layout nur die Positionen "Im Inhaltsbereich oben", "Im Inhaltsbereich unten" und "Rechte Seitenleiste" unterstützt. Boxen die hier angelegt werden, werden mit den Boxen der Seite auf diesen Positionen zusammengefügt. Wenn die Methode supportPagePositions() nicht aufgerufen wird, werden alle Seitenpositionen unterstützt.
3. Boxxer im Formular einbinden
Die Integration in das eigene Formular ist nur eine Zeile Code. Hier gibt es zwei Möglichkeiten:
Formular die mit dem Form Builder erstellt sind
Formulare die per Form Builder erstellt sind, können Boxxer über ein neues Feld einbinden:
Sobald das FormField hinzugefügt wurde, wird das Boxxer Layout an der Stelle im Formular angezeigt und kann verwendet werden.
Reguläres Formular
Wenn das Formular, in das Boxxer eingebunden werden soll, auf die herkömmliche Weise erstellt wurde, muss im Template innerhalb des form-Tags Boxxer eingebunden werden:
4. Boxxer im Frontend einbinden
Je nachdem wie das Layout konfiguriert ist und welche Position gerendert werden soll, gibt es unterschiedliche Möglichkeiten:
Standard-Seitenposition
Für Standard-Seitenpositionen wie z.B. "Im Inhaltsbereich unten" bedarf es keinem Extra Code. Die hinzugefügten Boxen werden automatisch gerendert.
Eigene Positionen - Standarddarstellung
Um die Boxen einer eigenen Position rendern zu lassen genügt der folgende Aufruf:
Dabei wird das Objekt zu dem die Boxen gehören und die zu rendernde Position angegeben. Hier werden die Boxen der Position article.content des Objekts $article gerendert.
Eigene Positionen - Eigene Darstellung
Möchte man größere Flexibilität, wie die Boxen dargestellt werden, kann man die Boxen über folgende Aufrufe abfragen: