Extend Contentful rich text editor capabilities with TinyMCE

Writing and publishing content is as ubiquitous as the internet. And the first thing that comes to mind when writers consider self-publishing, is to use a Content Management System (CMS), like WordPress. It’s no surprise then to hear that WordPress is used by 63.3% of the CMSs tracked by W3techs – which equates to 43.2% of all websites.

But what if you need more flexibility? A CMS can only bend and stretch so far in terms of a unique design and comfortable UX for readers. And if you’re looking to choose a CMS that fits  both your writer's needs and  front end developer’s publishing infrastructure, then it’s a tough task. 

However a headless CMS, like the Contentful infrastructure lets you author your content in a web app and then post that content through an API (so developers can work more easily with the content).

For even more flexibility, Contentful provides a UI Extensions mechanism, which allows developers to add a custom component for Contentful rich text editing. A trusted rich text editor that offers flexibility and features for Contentful rich text editing, is TinyMCE, which now has a dedicated Contentful integration. 

This article explains the integration steps, specifically going through what you need to know to integrate TinyMCE into the Contentful headless CMS, and access TinyMCE Premium features.

What is a headless CMS?

A headless CMS is a platform designed for writing, managing and publishing content. You writers don’t need to understand core HTML tags, the intricacies of space, color, and fonts, or the dynamic possibilities of JavaScript in the web browser. 

The "head" – the front end that readers see – is "cut" from the core or body content that makes up a written post on a website, hence "headless". Omar Benseddik writes a great summary of the headless CMS.

How does a headless CMS work?

Headless CMSs make the content available to a developer via an API, by parsing the content from the API into their website publishing infrastructure. Headless CMSs are also often used with static site generators, such as Gatsby or Hugo, where it’s consumed via an API for publishing. 

Is Contentful a headless CMS, really?

Contentful is definitely a headless CMS, and was designed as such when Sascha Konietzke and Paolo Negri founded and launched Contentful in 2013. It works by providing a writing and editing interface with customizable input and rich text field types where writers and content managers can write their content. 

Writers make use of the Contentful rich text field to draft their content.

Does Contentful have a WYSIWYG editor?

The default Contentful WYSIWYG editor is called a “Rich Text field type”. Editing options include bold, italics, underline, code, links, ordered lists, unordered lists, blockquotes, and a horizontal line. The toolbar is customizable as well if you need to change the options available.

However, it does not (inbuilt) have an extensive range of advanced features, when compared to a true rich text editor, like TinyMCE.

How to use the Contentful rich text field type

For developers, the Rich Text field type emits out content to the front end in JSON format, and not HTML, so you'll need a stringify or parser set up to handle posted content. 

For example, the JSON structure arrives in a series of arrays where  the key is "nodeType" and the values that form the content are "document, "paragraph", and "text". These values are modified by keys such as "value", "data", and "marks" . For example, the "marks" value might be "type": "italic".

How to handle the Contentful Rich Text field Type HTML

To speed up the process of converting JSON, Contentful provides RTF rendered. These are packages you can use, which fit into different programming languages and frameworks.

How to handle the Contentful table HTML

The key rendering point to know about when handling Contentful rich text tables is that tables are one of the kinds of blocks that need to have specific children. For example, a table block in the JSON can only have a table row as a child element. Here is the complete list of parent and child block relationships:

• Table > Table Row
• Table Row > Table Cell, or Table Header Cell
• Table Cell > Paragraph
• Table Header Cell > Paragraph

How to integrate TinyMCE with Contentful

To install TinyMCE for Contentful:

1. Sign up for an API Key at https://www.tiny.cloud/auth/signup/, or use your existing API Key.
   
   Signing up for a TinyMCE API key grants 14 days FREE trial access to all our Premium plugins, and also removes any warnings concerning domain names from the TinyMCE text area. 

Try TinyMCE in your CMS, and sign up for your FREE API key today

2. In your My Account dashboard, go to the Approved Domains page, and add the domain contentful.tiny.cloud
3. Log in to your Contentful dashboard, go to Settings, Extensions
4. Click Add Extension, then Install from Github.
5. Enter the URL:
6. https://github.com/tinymce/tinymce-contentful/blob/master/extension.json
7. Enter your Tiny Account API Key (generated when you signed up)
8. Click Save

You then need to configure TinyMCE as the Contentful rich text field.

1. Under the Content Model tab on the dashboard, and click Add content type.
2. Give the content type a name, and check the API identifier, which is generated from the name.
3. In the Content Type window that opens, click on Add field, and set it as type Text.
4. Give the Text field type a name, such as “TinyMCE”, and under Select type, choose the Long text, full-text search option.
5. Click Create and Configure, and under the Appearance tab, select TinyMCE
6. In the Appearance tab, you can customize some of TinyMCE's settings to best meet your needs, including the Plugins, Toolbar, and Menubar.

You can then use TinyMCE to edit this text field in your content items. The following video also demonstrates the steps:

How TinyMCE replaces the Contentful rich text field

As mentioned in the proceeding section, Contentful's rich text fields use a custom JSON structure as their input and output format. When consuming this format via the Contentful APIs, you may need to convert it to HTML. This certainly provides a lot of publishing flexibility, but is extra work when integrating content into your website.

TinyMCE is built primarily to read and write HTML. Therefore, to support this custom JSON structure, we’d have to write converters to and from HTML and also be careful not to lose information in the process. So, we may have to restrict what markup we support, in order to fit within the definition of the JSON format.

For these reasons, it's simplest for TinyMCE to just store HTML in a standard Contentful Text field. When you consume the content from the Contentful API, you get the rich, clean HTML straight from the editor.

Development challenges for Contentful rich text extensions

Contentful's API for custom editors is fantastic to work with, and made many parts of the integration quite simple. However, all development work has its challenges and we encountered some minor ones during the creation of this integration. ‘

Contentful places custom editors within an <iframe> tag that can be specified as a URL via the src attribute, or as inline text using the srcdoc attribute. They also use iframe sandboxing techniques to improve security. We found that only the src option worked, due to how TinyMCE uses iframes within the editor.

TinyMCE is incredibly customizable, so we wanted to make sure that was still available to users of this integration. 

Contentful provides custom properties for a UI extension, and it was definitely challenging to fit a significant portion of TinyMCE's configuration into so little space! So, for now, we just allow configuration of plugins, toolbar buttons and menus (but not menu items). 

Note: If there’s anything more you’d like us to add, please let us know.

A TinyMCE integration for Contentful rich text editing

If you have any feedback on the TinyMCE Contentful integration, please let us know. The TinyMCE Roadmap provides a record of the future plans for TinyMCE, and you can register any improvements to the integration (or other suggestions) on the Roadmap.