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

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.

It is also possible to define the YAML inside the partial itself. This is useful for simple use-cases.

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.

TIP

You can also create new Boxes directly in October's backend in the Editor section.

Reference implementation

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

CLARIFICATION

By default, you place your partials in your theme directory. oc-bootstrap-boxes-plugin offers Third-Party-Boxes and is therefore implemented differently than the default use-case.

However, the partial structure is the same, so feel free to use it as a reference.