Plugin and Tailor Integration Pro Feature

The Boxes Editor can be integrated with any plugin. The integration allows an end-user to compose content for any model type with the Editor (like Blog posts).

Use the Boxes Editor in Tailor

Using the Boxes Editor as your content editor in Tailor is very easy.

To display the Editor in a Tailor backend form, define a form field like this:

fields:
    boxes_content:
        label: Boxes Content
        tab: Content           # Put the Editor on its own tab. It won't look good otherwise.
        span: adaptive         # This makes sure the Boxes Editor looks good in Tailor.
        type: boxes            # This loads the Boxes Editor.
        previewLayout: default # Optional, the CMS layout to use for the preview.
        partialContexts:
            - blog             # Optional, see "Contexts" below.

In your frontend, you can then use the render method on your field to get the rendered HTML content:

[section yourSectionVar]
handle = "Your\Handle"
entrySlug = "{{ :slug }}"
==

{{ yourSectionVar.boxes_content.render() | raw }}

If you use partials with components or JS/CSS assets, please see manually initializing partials below.

Use the Boxes Editor in a custom plugin

To use the Boxes Editor in a custom plugin, first define a new morphOne relation on your model.

<?php namespace YourVendor\YourPlugin\Models;

use Model;
use OFFLINE\Boxes\Models\Page;

class YourModel extends Model
{
    public $morphOne = [
        'your_relation' => [    // Any name you want
            \OFFLINE\Boxes\Models\Content::class,
            'name' => 'content' // Has to be called 'content'
        ]
    ];
}

You can call the relation as you wish (your_relation in the example above). It is required to pass a name of content in the relation configuration.

Next, add the Boxes Editor to your form by adding the following field in your fields.yaml. The Editor must be placed on its own tab to render correctly.

tabs:
    fields:
        your_relation:
            label: Boxes Content
            tab: Content           # Put the Editor on its own tab. It won't look good otherwise.
            span: adaptive         # Give the Editor enough room!
            type: boxes            # This loads the Boxes Editor
            previewLayout: default # Optional, the CMS layout to use for the preview.
            partialContexts:
                - blog             # Optional, see "Contexts" below.

To render the content that was designed in Boxes, simply call the render() method on the relation:

$html = YourModel::find(1)->your_relation->render();

or in Twig:

{{ your_model.your_relation.render() | raw }}

If you use partials with components or JS/CSS assets, please see manually initializing partials below.

Get the related model from a partial

Sometimes, you want to get the related model in a partial. For example, if you want to display the title of a blog post in a partial.

To get the related model, you can use the context.model variable and access the content relation.

{# blog-header.htm #}
{% set relatedModel = context.model.content %}

{# Display the title of the related model
<h1>{{ relatedModel.title }}</h1>

Manually initializing partials

If you use partials with components or JS/CSS assets, you need to manually initialize the partials in your layout or your CMS page. This is because the Boxes content is rendered on-demand inside your plugin's partials and not during the default October CMS page life-cycle. This means most of Boxes' code is never executed - like the code that initializes the components for you.

To initialize your partials, you need to call the init method on your_relation in the onInit lifecycle hook of your layout or CMS page:

title = "Some page"
url = "/some-page"

[section post]
handle = "Blog\Post"
==
// Add this to initialize the components.
function onInit()
{
    // "post" is the name of your component, registered above.
    // This can be a Tailor component or any other model.
    $this['post']->your_relation?->init();
}
==
<section>
    {{ post.your_relation.render() | raw }}
</section>

Contexts

When using the Boxes Editor in your own custom plugins, you may want to use only a subset of all available partials in your plugin (like special partials for a blog section).

This is possible by defining a partialContexts array in your form field configuration.

Every partial can define which contexts it is available in using the contexts key. By defining a partialContexts array in your form field configuration, only partials that are available in the defined contexts will be available in the Editor.

A context can be any custom string, like blog or shop. The default context is used when editing a Box Page in the backend.

fields:
    your_relation:
        # ...
        type: boxes
        partialContexts:
            - blog     # Include only partials with
            - shop     # the "blog" or "shop" context.
          # - default  # Include the "default" context to include
                       # all partials that have no special context
                       # defined as well.

Apply a page template

You can use the template key to apply a Page Template for each new record.

fields:
    your_relation:
        # ...
        type: boxes
        template: blog # apply the "blog" page template