Plugin: Boxxer - API

Mit Warly Boxxer lassen sich Boxen auch in den eigenen Datensätzen nutzen. Die Einbindung ist denkbar einfach.

  1. Durch einen ObjectType wird Boxxer für den Datensatz aktiviert
  2. Das Layout der Boxen wird im BoxxerObject konfiguriert
  3. Die Einbindung in das Formulars des Datensatzes erfolgt durch eine Zeile Code
  4. Die Anzeige der Boxen im Frontend erfolgt durch eine Zeile Code

1. ObjectType

Boxxer wird per ObjectType im eigenen Datensatz aktiviert. Hier eine Beispielkonfiguration:

HTML
<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>


Attribut Pflichtangabe Beschreibung
name Name des ObjectType
definitionname de.warly.plugin.boxxer.object
classname Die Klasse, die Boxxer für den Datensatz konfiguriert. Muss das Interface wcf\system\boxxer\object\IBoxxerObject implementieren.
formClassName Die Formularklasse, in der Boxxer eingebunden werden soll. Hier muss nur die "Add"-Form des Formulars angegeben werden.
pageClassName Sollte der Datensatz auf einer eigenen Seite angezeigt werden, sollte hier die Klasse der Seite angegeben werden. Wird der Datensatz auf mehreren Seiten angezeigt sollte, wie im Beispiel von Artikeln, die übergeordnete Klasse angegeben werden. Lasse dieses Attribut weg, wenn mehrere Datensätze auf einer Seite angezeigt werden.

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:

PHP
/**
 * @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:

PHP
$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:

PHP
$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:

PHP
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:

HTML
{include file='__boxxerObject'}

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:

HTML
{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:

HTML
{$__wcf->getBoxxerHandler()->getBoxes($article, 'article.content')}
PHP
$boxes = BoxxerHandler::getInstance()->getBoxes($article, 'article.content');