Configuring default toolbar buttons in TinyMCE 4 for Episerver

In Episerver update 206, a new version of the TinyMCE rich text editor was introduced. TinyMCE 4 is cleaner and slicker than the old one, and fully HTML5-compatible which will help us output more standards-friendly and accessible markup.

If you're trying out the new editor, you'll notice that the preconfigured toolbar contains just a handful of buttons, and is missing tools such as Insert Media, Anchor or HTML source.

Don't panic, we'll get them back with a little configuration so we'll end up with something like this:

TinyMCE now separated from the CMS UI

First off, having TinyMCE separated from the CMS into its own Nuget package means that we can update TinyMCE and Episerver independently, without breaking all our config.

Secondly, all TinyMCE config is now done in code - you can't change these settings through Admin mode like before.This is good since it'lll ensure all editor settings are maintained and deployed with the codebase. It's also an improvement that we now have a proper API to work with, instead of messing about with .js files! 

Each toolbar button comes from a plugin

Each toolbar button in TinyMCE comes from a plugin - and there are a lot of plugins available for TinyMCE 4. Some plugins contain just one function/button, while other contain several buttons.

Most are free to use, and most are included in the nuget package for Episerver (there are a few premium plugins available that has a license cost, and these are not included. You might want to check them out for extra oomph in pasting from Word/Excel, spellchecking or embedding rich media.)

Tip: To see the current TinyMCE configuration easily, start editing in a TinyMCE-enabled property (e.g. Main Body), then open dev tools in your browser and enter 'window.tinymce.settings': (credit: Antti Alasvuo)

In the TinyMCE nuget package, open the ZIP file ((\packages\EPiServer.CMS.TinyMce.2.0.0\content\modules\_protected\EPiServer.Cms.TinyMce) to find a list of all the included plugins (EPiServer.Cms.TinyMce.zip\2.0.0\ClientResources\tinymce\plugins)

Episerver will try to load the plugins from this location whenever you reference them in the TinyMCE configuration. 

Adding buttons to the toolbar

In order for buttons to show up in the TinyMCE editor toolbar, they have to: 
1) be explicitly loaded, using .AddPlugin()
and
2) be explicitly added to the toolbar, using .Toolbar() (note: this will overwrite any plugins previously added to the toolbar) - or .AppendToolbar() (does not overwrite the previous toolbar config, just adds your specified plugins to it)

To override the default settings, add an initialization module (just a new class, place it anywhere) like this:

using EPiServer.Cms.TinyMce.Core;
using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.ServiceLocation;

namespace MyEpiserverSite.Business.Initialization
{
    [ModuleDependency(typeof(TinyMceInitialization))]
    public class ExtendedTinyMceInitialization : IConfigurableModule
    {
        public void Initialize(InitializationEngine context)
        {
        }

        public void Uninitialize(InitializationEngine context)
        {
        }

        public void ConfigureContainer(ServiceConfigurationContext context)
        {
            context.Services.Configure<TinyMceConfiguration>(config =>
            {
                config.Default()
                    .AddPlugin("media wordcount anchor code")
                    .Toolbar("formatselect | epi-personalized-content epi-link anchor numlist bullist indent outdent bold italic underline alignleft aligncenter alignright | image epi-image-editor media code | epi-dnd-processor | removeformat | fullscreen")
                    .AddSetting("image_caption", true)
                    .AddSetting("image_advtab", true);
            });
        }
    }
}

Breaking down what happens in this example:

Basically, by adding this config in config.Default(), we are setting the global configuration for all XHTML fields that use the TinyMCE editor (for both page types and block types). 

Note: For a real site, you might want to limit the amount of generic global config, and rather add more specific config for your page/block types (you'll find an example in Ben's blog post - see "Configuring The Editor".)

We're also adding several plugins using .AddPlugin() - these will be added to what is preconfigured from Episerver, so you only have to add plugins that were not configured out-of-the-box. If you want to override the preconfigured ones, use .Plugins() instead. Plugin names should be separated by a space.

We have to explicitly add each plugin using .Toolbar() in order for them to show up in the toolbar. Plugin names should be separated by a space, and you can use a pipe character ('|') to group them. This will override the preconfigured toolbar, so you'll have to add all the plugins you need to this list.

Lastly, some plugins have advanced properties that can be enabled using .AddSettings(). For instance, "image_caption" will add an optional caption (figcaption) to images that are inserted in the editor. "image_advtab" will show the Advanced tab in the 'Insert/Edit Image' popup dialog (which is not visible out-of-the-box). 

Again, you can find all the available plugin names, their properties and settings on the TinyMCE plugins page.

All the plugins used in this tutorial

Using the config in this tutorial, we'll end up with a TinyMCE editor that looks like this:

The toolbar now consists of the following plugins (left to right):

• importcss - with the toolbar button 'formatselect' (shows the format/style dropdown list)
• epi-personalized-content (Personalized content, Visitor Groups)
• epi-link (Insert/edit link)
• anchor (Insert anchor)
• lists - with toolbar buttons 'numlist' and 'bullist' (numbered list and bulleted list)
• indent, outdent, bold, italic, underline, alignleft, aligncenter, alignright - default toolbar buttons included in the 'modern' theme
• image - with the toolbar button 'image' (Insert/edit image)
• epi-image-editor - with the toolbar button 'epi-image-editor' (Image editor)
• media - with the toolbar button 'media' (Insert/edit media)
• code - with the toolbar button 'code' (Source code)
• removeformat (Clear formatting)
• fullscreen - with the toolbar button 'fullscreen' (Fullscreen TinyMCE editor)
• wordcount - shown in lower right corner (word counter)