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>

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:

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

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

$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.

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:

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:

{include file='__boxxerObject'}

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:

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

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

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