Customizing the rich text editor toolbar

To provide a better experience for content editors, you can customize the toolbar of the rich text editor to display a specific set of buttons and format options. You can create multiple widgets with rich text editors, each with a different toolbar.

To customize the editor toolbar, you need to:

1. Define toolbar configurations
2. Assign configurations to widgets

Defining toolbar configurations

Within your live site project, create a JavaScript file for toolbar configurations. It is recommended to store this file in the ~/wwwroot/Scripts or ~/Scripts folder.

In this file, define the toolbar options for each configuration as seen in the following code example.

(function (pageBuilder) {
    var richTextEditor = pageBuilder.richTextEditor = pageBuilder.richTextEditor || {};
    var configurations = richTextEditor.configurations = richTextEditor.configurations || {};
    // Overrides the "default" configuration of the Rich text widget, assuming you have not specified a different configuration
    // The below configuration adds the h5 and h6 values to the paragraphFormat and removes the code value. Also sets the toolbar to be visible without selecting any text.
    configurations["default"] = {
        toolbarVisibleWithoutSelection: true,
        paragraphFormat: {
            N: "Normal",
            H1: "Headline 1",
            H2: "Headline 2",
            H3: "Headline 3",
            H4: "Headline 4",
            H5: "Headline 5",
            H6: "Headline 6",
        },
    };

    // Defines a new configuration for a simple toolbar with only formatting
    // options and disables the inline design of the toolbar
    configurations["simple"] = {
        toolbarButtons: ['paragraphFormat', '|', 'bold', 'italic', 'underline', '|', 'align', 'formatOL', 'formatUL'],
        paragraphFormatSelection: true,
        toolbarInline: false
    };
})(window.kentico.pageBuilder);

Certain plugins that can be included within toolbars were adjusted for the Xperience environment (e.g. insertImage and insertLink), but these plugins override the corresponding Froala plugins and you can use the default code names to include them in your custom toolbar configurations.

Assigning configurations to widgets

There are two ways to assign different toolbar configurations to widgets:

• Link different configurations to specific pages
• Specify multiple configurations and reference them from custom Rich text widgets

You can combine both approaches. For example, you can create a script to customize the default Rich text widget and render it on specific pages. Then you can create an additional script where you define configurations for custom widgets and render this script globally through a shared layout.

Customizing the toolbar based on location

Any rich text widget, including the default Rich text widget, can be customized to use a different toolbar depending on its location. For example, you can configure it to display one toolbar on the home page and a different toolbar on landing pages.

Edit the view of the page where you want to apply the customization and register the desired configuration script. You can also register the script in a layout or a page template to affect multiple pages. The toolbar configuration script needs to be registered after page builder scripts.

@using Kentico.PageBuilder.Web.Mvc

...

@* Registers page builder scripts *@
@Html.Kentico().PageBuilderScripts()

@* Registers the toolbar configuration script *@
@if (Context.Kentico().PageBuilder().EditMode)
{
    @Scripts.Render("\~/Scripts/SimpleConfiguration.js")
}

Customizing the toolbar of custom widgets

Custom widgets containing the rich text inline editor can be configured to display a specific toolbar configuration. When rendering the rich text inline editor in the view of a widget, specify the configuration name as an additional parameter of the RichTextEditor method. If you do not specify a configuration, a default configuration (named default) is used.

@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Components.Web.Mvc.InlineEditors

@* Adds the rich text inline editor, using the 'custom' toolbar configuration *@
@Html.Kentico().RichTextEditor(editablePropertyName, "custom");

To make your toolbar configuration available for all pages, include the corresponding script in your site’s main layout (e.g. ~/Views/Shared/_Layout.cshtml). The toolbar configuration script must be registered after page builder scripts.

@using Kentico.PageBuilder.Web.Mvc

...

@* Registers page builder scripts *@
@Html.Kentico().PageBuilderScripts()

@* Registers the toolbar configuration script *@
@if (Context.Kentico().PageBuilder().EditMode)
{
    @Scripts.Render("\~/Scripts/MyComponentConfiguration.js")
}