Implementing rich text editor plugins

If your editors are missing a feature in the rich text editor for the page builder, you can extend the editor via plugins.

You can develop your own custom plugins or add existing Froala plugins. Many of the default Froala plugins are already included in the rich text editor. See the Froala documentation to find a list of all available plugins and instructions on how to add them. Froala plugins are covered by your Kentico Xperience license, so you do not need to purchase them separately.

Certain plugins were adjusted for the Xperience environment and are not identical to the corresponding default Froala plugins even though they share the same name, e.g., Image or Link.

Implementing plugins

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

Within the file, implement and add plugins according to the Froala documentation.




(function (pageBuilder) {
    var richTextEditor = pageBuilder.richTextEditor = pageBuilder.richTextEditor || {};

    // Retrieves the collection of plugins
    var plugins = richTextEditor.plugins = richTextEditor.plugins || [];

    // Creates a plugin
    var myFirstPlugin = function (FroalaEditor) {
            ...
        };

    // Adds the plugin to the collection
    plugins.push(myFirstPlugin);
})(window.kentico.pageBuilder);

To make the plugins available for your entire site, include the scripts containing the plugins into the website’s main layout (e.g. ~/Views/Shared/_Layout.cshtml). The scripts with plugins must be registered after page builder scripts.




@using Kentico.PageBuilder.Web.Mvc

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

@* Registers plugin scripts *@
@if (Context.Kentico().PageBuilder().EditMode)
{     
    <script src="~/Scripts/sampleButtonPlugin.js"></script>
}




@using Kentico.PageBuilder.Web.Mvc

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

@* Registers plugin scripts *@
@if (Context.Kentico().PageBuilder().EditMode)
{
    @Scripts.Render("~/Scripts/SamplePlugins.js")
}

After you create a new plugin, you need to add the given plugin to a toolbar configuration to make it available in the rich text editor.

The following example shows you how to create a simple plugin that allows you to replace occurrences of the word ‘you’ with ‘Thou’.

Create a new JavaScript file: ~/Scripts/sampleButtonPlugin.js

sampleButtonPlugin.js




(function (pageBuilder) {
    var richTextEditor = pageBuilder.richTextEditor = pageBuilder.richTextEditor || {};

    // Retrieves the collection of plugins
    var plugins = richTextEditor.plugins = richTextEditor.plugins || [];
    // Creates a new Sample Button
    var sampleButtonPlugin = function (FroalaEditor) {
            FroalaEditor.DefineIcon("sampleButtonIcon", { SVG_KEY: "help" });
            FroalaEditor.RegisterCommand("sampleButton", {
                title: "Sample Button",
                icon: "sampleButtonIcon",
                callback: function () {
                      var htmlContent = this.html.get();
                      htmlContent=htmlContent.replace(/you/gi, 'Thou');
                      this.html.set(htmlContent);
                }
            });
        };
    // Adds the plugin to the collection
    plugins.push(sampleButtonPlugin);

    // Retrieves the collection of toolbar configurations
    var configurations = richTextEditor.configurations = richTextEditor.configurations || {};
    // Overrides the default toolbar configuration to display the plugin button
    configurations["default"] = {
        toolbarButtons: ['paragraphFormat', '|', 'sampleButton', 'bold', 'italic', 'underline', '|', 'align', 'formatOL', 'formatUL']
    };
})(window.kentico.pageBuilder);

~/Views/Shared/_Layout.cshtml* file:

_Layout.cshtml




@if (Context.Kentico().PageBuilder().EditMode)
{
    <script src="~/Scripts/sampleButtonPlugin.js"></script>
}

_Layout.cshtml




@if (Context.Kentico().PageBuilder().EditMode)
{
    @Scripts.Render("~/Scripts/sampleButtonPlugin.js")
}

The functionality is now available under the ‘?’ button in the toolbar of the default Rich text widget.

Implementing plugins

Example – Creating a custom toolbar button