Plugin: Boxxer - API

With Warly Boxxer, boxes can also be used in your own data sets. The integration is very easy.


  1. Boxxer is activated by an ObjectType for the data set
  2. The layout of the boxes is configured in BoxxerObject
  3. The integration into the form of the data set is done by one line of code
  4. The display of the boxes in the frontend is done by one line of code

1 .ObjectType

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

Code
<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>
Attribute Required Description
name Name of the object type
definitionname de.warly.plugin.boxxer.object
classname The class that Boxxer configures for the record. Must implement the interface wcf\system\boxxer\object\IBoxxerObject.
formClassName The form class in which Boxxer should be included. Here only the "Add" form of the form has to be specified.
pageClassName If the record is to be displayed on a page of its own, the class of the page should be specified here. If the record is being displayed on multiple pages, as in the example of articles, the parent class should be specified. Omit this attribute if multiple of your records are displayed on a single page.

2. BoxxerObject

The BoxxerObject specified in the ObjectType must implement the interface wcf\system\boxxer\object\IBoxxerObject. There is the abstract class wcf\system\boxxer\object\AbstractBoxxerObject, which overwrites all methods of the interface, so that only the methods where something happens have to be implemented.


This API documents the use of wcf\system\boxxer\object\AbstractBoxxerObject as a basis. An own implementation of wcf\system\boxxer\object\IBoxxerObject is not recommended.

$boxxerObjectType


Specifies the ObjectType of the BoxxerObject. This is the name from step 1.

isBoxxerFormApplicable(AbstractForm $form) Boolean


Specifies whether Boxxer should be activated for the passed form (which is of type formClassName from the ObjectType). By default true is returned. This method must be overwritten only if Boxxer should be activated only under certain conditions.

getEditFormLink(int $objectID) String


Returns the URL for the record's edit form. Here a URL should be returned, which in the best case jumps directly to Boxxer. Example:

PHP
/**
* @inheritDoc
*/
public function getEditFormLink(int $objectID) {
return LinkHandler::getInstance()->getLink('ArticleEdit', ['id' => $objectID], '#boxxer');
}

configureLayout(BoxxerLayout $layout) Void


In this method, the layout for Boxxer is configured, i.e. which positions the record supports. The layout consists of rows, with one or more columns, which in turn contains one or more positions.


A layout with only one position could be configured like this:

PHP
$layout->appendRow(BoxxerLayoutRow::create([
BoxxerLayoutPosition::create('item.content', BoxxerLayoutPosition::PAGE_CONTENT_BOTTOM)
]));

This would create the position item.content, which allows boxes of the default position "In content area below".

For a detailed explanation of the layout creation options, see Create Layout below (coming soon).


If the dataset is displayed on a separate page, the standard page positions can be used in addition to your own positions. Here you can configure which page positions the data set or the page on which the data set is displayed should support. An example:

PHP
$layout->supportPagePositions([
    BoxxerLayoutPosition::PAGE_CONTENT_TOP,
    BoxxerLayoutPosition::PAGE_CONTENT_BOTTOM,
    BoxxerLayoutPosition::PAGE_SIDEBAR_RIGHT
]);

Here it is specified that the layout only supports the positions "Content top", "Content bottom" and "Right sidebar". Boxes created here will be merged with the boxes on the page in these positions. If the method supportPagePositions() is not called, all page positions are supported.

3. Integrate Boxxer into your form

The integration into your own form is only one line of code. There are two possibilities:

Form created with the Form Builder

Forms that are created with Form Builder can include Boxxer via a new field:

PHP
BoxxerObjectFormField::create()

As soon as the FormField is added, the Boxxer layout is displayed at the position in the form and can be used.

Regular Form

If the form in which Boxxer is to be included was created in the conventional way, Boxxer must be included in the template within the form tag:

HTML
{include file='__boxxerObject'}

4. Integrate Boxxer in the frontend

Depending on how the layout is configured and which position should be rendered, there are different possibilities:

Default page position

For standard page positions like "Content bottom" no extra code is required. The added boxes are rendered automatically.

Custom positions - default presentation

To render the boxes of a custom position the following call is sufficient:

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

The object to which the boxes belong and the position to be rendered are specified. Here the boxes of position article.content of the object $article are rendered.

Custom positions - custom presentation

If you want more flexibility in how the boxes are displayed, you can query the boxes with the following calls:

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