Boxes Plugin for October CMS #

Concepts #

The Boxes plugin allows you to build websites using a visual page builder.

The core part of the plugin is a building block called Box.

A Box consists of two parts:

1. A Box partial
2. A Box config file

The Box partial is a standard October CMS partial. You can use any partial from any theme that you have built, there are no special requirements.

The Box config is a YAML file that defines the data schema of the partial. The YAML is used to render the backend form which a user can use to edit the partial's contents.

Multiple Boxes can be put together to build a Box Page.

Registering your first Box #

Let's say you have a partial in your theme, which you would like to make usable in Boxes:

{# title-text-image.htm #}
<h1>This is a title</h1>

<p>With some paragraph<p>

<img src="image.jpg" alt="">

The first thing you have to do is to create a YAML file in the same directory and with the same name as your partial.

partials/
  title-text-image.htm
  title-text-image.yaml # create this file

In the YAML file, add at least a unique handle. All other properties are optional.

In this example, we give the Box a human-readable name and define a simple form to edit the Box's data.

# title-text-image.yaml
handle: title-text-image
name: Title, Text and Image
form:
    fields:
        title:
            label: Title
            type: text
        text:
            label: Content
            type: richeditor
        image:
            label: Image
            type: fileupload
            mode: image

Next, replace the static content in your partial with dynamic Twig code.

The partial has access to a box variable that contains all the data that was entered in the backend.

{# title-text-image.htm #}
<h1>{{ box.title }}</h1>

<p>{{ box.text | raw }}<p>

<img src="{{ box.image.thumb(200, auto) }}" alt="">

You can now create a new Page in the Boxes Editor and add your newly created Box to it.

Reference implementation #

See the oc-bootstrap-boxes-plugin's partial directory for a complete example implementation of Boxes.