Appearance
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:
- A Box partial
- 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:
twig
{# 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.
bash
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.
yaml
# 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.
twig
{# 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.
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.