Rich Editor / WYSIWYG Field

richeditor - renders a visual editor for rich formatted text, also known as a WYSIWYG editor.

html_content:
    type: richeditor
    label: Contents

The following field properties are supported and commonly used.

You may specify how large the field size should be with the size property.

html_content:
    type: richeditor
    label: Contents
    size: huge

Use the toolbarButtons property to specify custom buttons.

html_content:
    type: richeditor
    label: Contents
    toolbarButtons: bold|italic|underline

The double-pipe || character can be used to include a separator with the buttons.

toolbarButtons: bold|italic|underline||insertPageLink||undo|redo||clearFormatting

The available toolbar buttons are:

# Toolbar Definitions

Toolbar definitions are named button configurations that can be shared by many rich editor fields and managed visually in the Settings → Editor Settings → Toolbar Buttons area. Each definition has a unique code, a label and a description explaining where it is used. Definitions are edited with a visual builder by dragging buttons between the toolbar and the available buttons palette.

The following definitions are included by default.

Use the toolbar property to reference a definition from a rich editor field. The same code can be shared by any number of fields, and updating the definition updates every field that references it.

description:
    type: richeditor
    toolbar: shop-content

A definition with no buttons inherits the default toolbar. This makes it possible to give an area of the admin panel its own toolbar code without prescribing any buttons, the fields simply follow the default toolbar until the definition is customized. The visual builder displays the inherited buttons for empty definitions, and modifying them makes the definition independent from the default toolbar. Definitions that have been changed from their registered configuration display as modified, along with a Reset to Default option to restore them.

Administrators may also create their own definitions with new codes using the Create Toolbar button, which can then be referenced from form fields and blueprints in the same way.

# Registering a Toolbar Definition

Plugins register toolbar definitions using the registerRichEditorToolbars method of the plugin registration file. Each definition supplies a label and a description, along with an optional button list.

public function registerRichEditorToolbars()
{
    return [
        'shop-content' => [
            'label' => 'Shop Content',
            'description' => 'Used by shop product and category descriptions.',
        ],
    ];
}

The definition above contains no buttons, so it inherits the default toolbar until an administrator customizes it. Specify the buttons value as a comma separated list to register an opinionated button set, which also acts as the baseline for the Reset to Default feature.

public function registerRichEditorToolbars()
{
    return [
        'shop-content' => [
            'label' => 'Shop Content',
            'description' => 'Used by shop product and category descriptions.',
            'buttons' => 'paragraphFormat, bold, italic, |, insertImage, insertPageLink, html',
        ],
    ];
}

Registered definitions appear in the settings area automatically, where administrators can review and customize them. Custom buttons registered in JavaScript can be included in a definition by their registered name.

# Toolbar Precedence

The toolbar button list is resolved for each editor from the first available source.

1. The field toolbarButtons property, used exactly as written.
2. The field toolbar property, resolved to its toolbar definition.
3. The default toolbar definition, when it has been customized.
4. The built-in default button list.

Custom buttons registered with a toolbar placement (see below) are added to the default toolbar automatically, and the default definition in the settings area displays them in place. Modifying the default toolbar stores the visible buttons exactly, making the placed buttons real entries that can be moved or removed. Every other source is used verbatim, so include the custom button name in the toolbar definition to display it there.

# Registering a Custom Button

Custom toolbar buttons are registered in JavaScript using the oc.richEditor.registerButton function. The API is available on every backend page, even when no rich editor is present, and the definition is editor-agnostic, it is not coupled to the underlying editor engine.

oc.richEditor.registerButton('insertCustomThing', {
    label: 'Insert Something',
    icon: 'icon-star',
    toolbar: 'end',
    undo: true,
    focus: true,
    onClick: function(editor) {
        editor.insertHtml('<strong>My Custom Thing!</strong>');
    }
});

Register the JavaScript globally on every backend page, so the button is available to every rich editor surface, including the form widget and the CMS editor.

Event::listen('backend.page.beforeDisplay', function($controller) {
    $controller->addJs('/plugins/october/test/assets/js/custom-button.js');
});

The following properties are supported by the button definition.

# The Editor Instance

The onClick function receives an editor object with the following methods, which remain stable across editor engine versions.

# Trigger a Modal from a Custom Button

Use the oc.popup JavaScript function to open a modal window.

oc.popup({
    handler: 'onLoadPopup'
});

Use the backend.ajax.beforeRunHandler to register a global AJAX handler. The makePartial method can be called to render a partial with the modal contents inside.

Event::listen('backend.ajax.beforeRunHandler', function ($controller, $handler) {
    if ($handler === 'onLoadPopup') {
        return $controller->makePartial('~/path/to/my/partials/_popup_form.php');
    }
});

# Advanced Editor Options

Use the editorOptions property to customize the editor options. This is an advanced property, since all options defined here are proxied directly to the editor control.

html_content:
    type: richeditor
    editorOptions:
        imageDefaultWidth: 0

The options are proxied to the underlying Froala editor. The most commonly used options are listed below, grouped by area.

# Image Options

# File Upload Options

# Drag and Drop

# Where to find the full list

The editorOptions values are passed through to the underlying Froala v2 editor. Every available option, along with its default, is declared at the top of each plugin file under vendor_drm/froala/js/plugins/ in the October CMS source — for example image.js for image options and file.js for file upload options.

# Example: block all image insertion

html_content:
    type: richeditor
    editorOptions:
        imageUpload: false
        imagePaste: false
        imageMove: false