Boxes

Static and data-backed boxes

A static box renders a view. A data-backed box reads through a model and passes data to that view. Both extend Wbengine\Box\WbengineBoxAbstract and belong under App\Box\<Section>.

<?php
namespace App\Box\Central;

use Wbengine\Box\WbengineBoxAbstract;

class Welcome extends WbengineBoxAbstract
{
    public function Welcome(): string
    {
        return $this->getRenderer()->render(
            $this->getBoxTemplatePath(),
            ['name' => 'World']
        );
    }
}

Create src/View/Central/Welcome.tpl and bind module welcome, method welcome to a section and site in cms_boxes. Pass SQL values as bound parameters. Keep database access in a model when the box needs reusable query logic.

Strict and dynamic pages

Every page is either strict or dynamic (the strict field of the page).

• A strict page answers only its own address. /docs/ is valid and /docs/anything/ is a 404.
• A dynamic page answers its own address and everything after it. The page that is found is still /addons/, and the rest of the address, for example v21-2 and server-1 in /addons/v21-2/server-1/, is passed to the box as parameters. The box reads them with $this->getUrlParams() and works with them.

For a dynamic page the framework cannot know which parameters are valid, so the box decides. A box that does not accept an address, for example a third parameter that does not exist in /addons/v21-2/server-1/xyz/, throws \Wbengine\Exception\RuntimeException with the code 404, and the framework shows the 404 page. Without that, every address under the page would show the page. A dynamic page is listed in the sitemap by its own address only (see Search engines).

Sections, order and devices

A box belongs to a section of the layout and to the pages that show it (the sites of the box), and boxes of a section are shown in their order. A box is hidden from a page by taking the page off its list; the box itself stays.

A box can be limited to devices with device_min and device_strict. The device classes are 1 mobile, 2 tablet and 3 desktop. device_min 0 means any device. Otherwise the device must be at least device_min, and with device_strict it must be exactly device_min. The stored default (device_min 1, not strict) shows the box on every device. The page cache keeps one copy of a page per device class, so a device limit never shows a visitor a copy made for another class (see Caching).

Managing boxes without code

Boxes of a registered type can be added and changed through API v2 and by the assistant of the MCP server: list the box types and boxes, add a box to a section, change its order and device limit, take it off a page and put it back. A type is registered by the application in Application::registerBoxTypes() with its module, method and the sections it may be placed in. A type that shows the article of its page is marked, so a client knows that a page with such a box is not empty. See API.