Skip to content

Editor Customization

It is possible that your theme will require certain tweaks when it is rendered in the Boxes Editor. You have different options to apply your tweaks.

Editor-only styles

The Boxes Editor adds a .oc-boxes-edit-mode class to the html element in the preview window. You can use it to add custom styles to any element on the page if it is rendered inside the editor.

css
.oc-boxes-edit-mode .header {
    /* Do not use a fixed scrolling header in the editor */
    position: static;
}

TIP

If you are using Tailwind CSS make sure to safelist this class, so it does not get purged from your generated CSS output.

Injecting additional CSS or JS

Using the offline.boxes.editorRender Event, you get access to the BoxesPageEditor component. Using the usual addCss and addJs method, you can inject your custom assets when the editor is rendered.

These assets will only be available in the Boxes Editor preview but not when the page is rendered in the frontend.

Add the following code to your app/Provider.php boot method:

php
<?php

namespace App;

use Illuminate\Support\Facades\Event;
use OFFLINE\Boxes\Classes\Events;
use OFFLINE\Boxes\Components\BoxesPageEditor;
use System\Classes\AppBase;

class Provider extends AppBase
{
    public function register()
    {
        parent::register();

        \Event::listen(
            \OFFLINE\Boxes\Classes\Events::EDITOR_RENDER,
            function (\OFFLINE\Boxes\Components\BoxesPageEditor $editor) {
                $editor->addCss('any-custom.css');
                $editor->addJs('any-custom.js');
            }
        );
    }
}

Reacting to editor events

The Editor emits a number of events that you can listen to in your JS code.

See JS Events for a list of available events.

Re-initializing your partials

You might have some JS code in your partials that needs to be re-initialized when the editor refreshes the preview.

You can listen for the offline.boxes.editorRefreshed event and re-initialize your partials.

js
// Register this event in any JS file that is available in the context of the editor.
window.document.addEventListener('offline.boxes.editorRefreshed', function (e) {
    // Re-initialize your dependencies here.
    initSliders();
});

Changing the order of partial sections

The order of the partial sections in the "Add new Box" modal is alphabetical by default.

You can create a boxes.yaml file in your theme directory and define a custom order for the sections in there:

yaml
# themes/your-theme/boxes.yaml
sections:
- Section A
- Section B
- Section C

Sections that are not mentioned in this file will be added at the end of the list in alphabetical order.