Creating a TinyMCE addon for Statamic 3

It’s no secret: I do love TinyMCE. It provides an excellent authoring experience, that produces clean and reliable HTML, and can easily be customised and extended to suit the flexible needs of clients.

And I’ve recently fallen for Statamic too. While I’ve only been putting it through its paces locally so far, its flexibility has so much potential for projects built on Laravel that also need some content management capabilities. Better yet, it is extensible for both public and private add-ons – from field types to complete UI sections – there’s room for creating something really cool, and harness the pleasure granted coding with Laravel while we’re at it too.

While Statamic does come with Bard – which is also worth a look for some really cool flexibility and authoring magic – I do have some clients that have fallen in love with TinyMCE. Pair this with TinyMCE’s insanely configurable appearance, including a superb API for external plugins with version 5, it really is a powerhouse WYSIWYG content editor.

With so many shifts in my toolset this year, learning new skills has been so exciting. Such a nerd, I know, but I love this stuff. And took this as an opportunity to look under the hood of Statamic a little further and write an add-on for the Statamic marketplace for TinyMCE.

Not only did this require working with Statamic, but also was my first exposure to:

• An organisation package for Mity Digital in Github,

• Creating a package on packagist, and

• Creating a product on the Statamic Marketplace

OK, so points 1 and 3 there are really straight forward. Actually 2 is too… but still was a great opportunity to continue learning, not just with the usual ‘composer require’, but also learning how packages are managed and deployed to run with composer – and also how they’re developed in place. So that’s a really neat and useful background to have.

The add-on itself is open source, and free, so if you’re a Statamic user, give it a try and let me know your thoughts. Check it out:

• on the Statamic Marketplace

• on Github

Feel free to explore the code too. Rather than talk about the actual creation of the add-on, I thought it may be more interesting to share some justifications and thought process around why I ended up building it the way I did.

Firstly, note this is for Statamic 3 only. You can install the component one of two ways:

Install via the Statamic Marketplace within the Statamic Control Panel

Under Tools, go to Addons, and search for “TinyMCE” – you can one-click install from here

Install via composer

Or, you can install using composer:

After you have installed the component, using either method, publish the config file.

Finally, in your Laravel/Statamic .env file, add a new key TINYMCE_CLOUD_APIKEY, and enter your Tiny Cloud API key as the value.

There are two levels of configuration here:

• Defaults for the init config, and

• Settings for a per-field init config

Under Tools, you’ll see “TinyMCE Cloud” where you can enter your default init value that all created TinyMCE fieldtypes will use as a base – and can then tinker and tweak from there.

Next up, you need to add TinyMCE to one of your Blueprints.

When you are creating your Blueprints and Fieldsets, each time you add a TinyMCE field, you will have the ability to update its init value. So you could have one field be fully featured, and another be really light and streamlined – and even have multiple instances per Blueprint.

When you’ve done this, you’re good to go authoring.

I feel the Tiny-hosted version of TinyMCE is definitely the way to go. It does require a (free) API key, but also takes the hassle out of relying on TinyMCE as a dependency within your project.

Using the cloud-based version of TinyMCE means that you’re always being served the latest stable version of the 5 branch – and that’s great for your authors to receive any bug fixes that may be deployed too.

One of the other perks is that you don’t need to include TinyMCE in your app’s bundle. Even with code chunking, TinyMCE can be a rather large library, and excluding it from your build process can help your application remain lighter, and also introduce the potential for caching of the TinyMCE code from Tiny’s servers too, which is incredibly useful for when your app bundles need to be updated – one less thing for your users to re-download.

To be honest, this is a decision I tossed around a bit.

While putting the API key in the config screen would be really useful in keeping all the configuration in one place, API keys typically should not be stored in your version control.

When the configuration file (that stores the init config) is saved, its data is output to a yaml file that should be stored in your version control for the project – so any of your developers and deployments can have that centralised global init.

If the API key were placed here too, the API key would be most probably committed at some stage, and this could risk your API keys becoming visible where they’re not meant to be-  especially if your repository is public.

Keeping the API key in the .env file gives you the option – if needed – to utilise different API keys for different deployments, and keep it out of your VCS.

Have you seen the TinyMCE configuration options? There’s a lot… and a UI may start to become really overwhelming to use, and also risk falling out of date if/when Tiny add new configuration options.

I would say that the majority of the time, it will be the developer who will look at the configuration of TinyMCE, not the author, so writing an object is no different from using TinyMCE in any other project.

I thought about it – and if there is demand can explore this further – but to get started, wanted to keep it simple.

Yes! This is a key requirement for me, and the cloud-hosted TinyMCE version gives you freedom to configure your editor instances as if you were self-hosted.

You just need to make sure your plugin files are part of your app’s build process, and made publicly accessible so they can be loaded like any other public asset on your site.

Head over to the Statamic Marketplace, Addons with your Statamic control panel, or just to the command line for some composer love and you’re good to go.

Find out more at the statamic-tinymce-cloud Github repo.