Create Episerver TinyMCE Default Templates

11/2/2018

Quick Summary

In this post, I will be describing how to add custom templates to your Episerver TinyMCE. Using templates can improve the content entry experience for your editors by minimizing the amount of editing that needs to be done. This is especially helpful when dealing with large amounts of content that will be formatted in similar ways.

Episerver & TinyMCE

If you are not familiar with the TinyMCE, you might know it by WYSIWYG (What you see is what you get) or rich text editor. It’s a property that allows you add content with custom fonts, styles, and even images. You can even edit the markup of the content, and see how it would render on your site.

TinyMCE Example Image

As of Episerver 11, the TinyMCE functionality was pulled out into its own NuGet package Episerver.CMS.TinyMCE. As I was going through the TinyMCE documentation for the different plugins and features that could be configured, I came across this templates feature.

Although there is a lot of configuration that can be done for the TinyMCE, I will be focusing only on the template feature in this post. While I plan to expand on more in the future, I encourage you to check out the Episerver documentation on your own for how to configure things. The TinyMCE documentation I already mentioned contains information on the individual plugins.

Implementation

I will go through the individual steps you need to take to get your templates setup. I created a simple example in an Episerver Alloy site using two basic templates. You can view it on my Github Repository for reference.

Building the Templates

The templates themselves are just plain HTML. You can add them to your solution and customize them with any custom styles you wish. The examples I built, one of which is displayed below, are just made up of some markup I pulled from another section of the Alloy site.

<div class="mceTmpl">
    <div class="span8">
        <h1>Title</h1>
        <p class="introduction">This is some introduction text</p>
        <div class="row">
            <div class="span8 clearfix">
            </div>
        </div>
        <div class="row">
            <div class="block articlepage teaserblock span4">
                <div class="border">
                    <h2>Sub Item Title</h2>
                    <p>Subtitle.</p>
                </div>
            </div>
        </div>
    </div>
</div>

The only thing TinyMCE requires you to have in your custom template is a div surrounding your template with the mceTmpl class.

TinyMCE Initialization

Now that you have your templates built, you need to add them to the TinyMCE settings upon initialization.

As I mentioned, I won’t be going through all the different ways to configure the TinyMCE. I would suggest reading up on the links I provided above. A few of the things you are able to configure are custom style formats, block formats, what plugins can be used and are in the toolbar, and even the height and width of the TinyMCE when its rendered. The ExtendedTinyMceInitialization in the Alloy project has a few examples of these features being added to specific content types. I added the following to it for our templates:

public void ConfigureContainer(ServiceConfigurationContext context)
{
    context.Services.Configure<TinyMceConfiguration>(config =>
    {
        // Add content CSS to the default settings.
        config.Default()
            .ContentCss("/static/css/editor.css")
            .AddSetting("templates", new[]
            {
                new
                {
                    title = "Article Template 1",
                    url = "../../Static/html/templates/article_template_1.html",
                    description = "Template w/title and text"
                },
                new
                {
                    title = "Article Template 2",
                    url = "../../Static/html/templates/article_template_2.html",
                    description = "Template with title and image"
                }
            })
            .AddPlugin($"{DefaultValues.EpiserverPlugins} template")
            .Toolbar($"{DefaultValues.Toolbar} | template");
    });
}

As you can see above, we add a new setting for “templates” to the TinyMCE configuration. The setting takes a list of objects, each of which specifies the title of the template, the path to the template file, and a description of the template.

    new
    {
        title = "Article Template 2",
        url = "../../Static/html/templates/article_template_2.html",
        description = "Template with title and image"
    },

After you add the setting, you need to specify the fact that you are using the template plugin. I added it along with the default plugins that Episerver specifies.

    .AddPlugin($"{DefaultValues.EpiserverPlugins} template")

Finally, you need to specify that you want the template icon to appear in the toolbar. Again, I added it alongside the default toolbar items Episerver specifies. Take note of the fact that unlike when adding plugins, you must separate the different items with a verticle pipe.

    .Toolbar($"{DefaultValues.Toolbar} | template");

And that’s all you need to get the templates working.

TinyMCE Template Selection

Final Thoughts

Overall, I think this is a pretty powerful feature for your editors. Especially if you want to start specifying templates based on content type. A couple of places I can see this being utilized is if there is a campaign that gets renewed over and over with small tweaks. Or if there is going to be a large migration of content, such as blog articles, from a non-Episerver site. This can definitely help the editor get the structure of the page created quickly, allowing for a better experience of copying content over.

Let me know if you have any thoughts, suggestions, or can think of other use cases for these templates. As always, feel free to create a pull request or send me a message on twitter