[DRAFT] October CMS 4.5 - Feature Release

Version 4.5 of October CMS contains some changes. This is a running document of changes.

Table of Contents

• How to Upgrade to v4.5
• Rich Editor Toolbar Definitions
• Editor-Agnostic Custom Buttons
• Notable Minor Changes

How to Upgrade to v4.5

There are two ways to upgrade, by clicking the Check for Updates button in the admin panel, or via console commands. For command line interface, please use the following commands:

php artisan october:update

Rich Editor Toolbar Definitions

The rich editor toolbar is now managed through named toolbar definitions, shared button configurations that any rich editor field can reference by code. Definitions are managed visually in the Settings → Editor Settings → Toolbar Buttons area, where each definition has a unique code, a label and a description explaining where it is used.

Visual builder: each definition opens in a popup containing a drag and drop builder, with the current toolbar shown as a row of button tiles above a palette of every available button, including custom buttons registered by plugins. A Modified column in the list shows which definitions have been changed from their registered configuration, and a Reset to Default button restores them.

The following definitions are included by default.

Referencing from fields: the new toolbar field property references a definition from any 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

Plugin registration: plugins seed their own definitions using the new 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.',
        ],
    ];
}

A definition with no buttons inherits the default toolbar, so a plugin can give its area of the admin panel a dedicated toolbar code without prescribing any buttons, and the fields simply follow the default toolbar until an administrator customizes the definition. Administrators may also create entirely new definitions with the Create Toolbar button.

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.

The legacy toolbar setting stored under Editor Settings is migrated into the default definition automatically.

See the rich editor documentation for full details.

Editor-Agnostic Custom Buttons

Custom toolbar buttons are now registered with the oc.richEditor.registerButton JavaScript function, a new API that is decoupled from the underlying editor engine. The API is available on every backend page, even when no rich editor is present, so a plugin script can register buttons unconditionally.

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

Global loading: register the script 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');
});

Placement: the toolbar property places the button in the default toolbar automatically, using start, end, { before: 'name' } or { after: 'name' }, with an optional separator hint. The default definition in the settings area displays placed buttons within the toolbar, and modifying the toolbar stores the visible buttons exactly, making them real entries that can be moved or removed. Buttons registered without a placement are still available to include in any toolbar definition by name.

The editor instance: the onClick function receives an editor object with stable methods for inserting content, managing the selection and recording undo steps, such as insertHtml, insertUiBlock, getContent, setContent, saveSelection and restoreSelection. The definition and the editor object are not coupled to the underlying editor engine, so registered buttons carry forward across editor engine versions.

Backwards compatibility: the previous oc.richEditorRegisterButton function continues to work as a deprecated shim that translates the old configuration into the new registry. The oc.richEditorButtons array is no longer used, so scripts that modified it directly should move to oc.richEditor.registerButton.

See the rich editor documentation for full details.

Notable Minor Changes

This is the end of the document, you may read the announcement blog post or visit the changelog for more information.