Plugin: Boxxer - API

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>

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.

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:

BoxxerObjectFormField::create()

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:

{include file='__boxxerObject'}

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:

{include file='__boxxerBoxes' object=$article position='article.content'}

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:

{$__wcf->getBoxxerHandler()->getBoxes($article, 'article.content')}

$boxes = BoxxerHandler::getInstance()->getBoxes($article, 'article.content');