Customizing the TinyMCE within Rich Text Editor in JIRA


Level of experience	ADVANCED
Time estimate	0:15
Atlassian application	JIRA 7.3+

Feature overview

If you've read these two tutorials: Tutorial - Writing plugin for Rich Text Editor in JIRA and Tutorial - Customizing Rich Text Editor in JIRA, you'll know how to add new functionality to the Rich Text Editor. After reading this tutorial, you'll know how to customize settings in underlying TinyMCE editor. Let's assume you want to allow typing markdown-like headings. The end result:

Let's dive into the details.

Creating a file with the customization logic

Listing of markdown-headings.js

1
2
require(["jira/editor/customizer"], function (EditorCustomizer) {
    EditorCustomizer.customizeSettings(function (tinymceSettings, tinymce, SchemaBuilder) {
        if (tinymceSettings.plugins.indexOf('textpattern') === -1) {
            tinymceSettings.plugins.push('textpattern');
        }

        tinymceSettings.textpattern_patterns = tinymceSettings.textpattern_patterns || [];

        Array.prototype.push.apply(tinymceSettings.textpattern_patterns, [
            {start: '#', format: 'h1'},
            {start: '##', format: 'h2'},
            {start: '###', format: 'h3'}
        ]);
    });
});

What's going on in the code?

Firstly, there is require of jira/editor/customizer which allows us to modify TinyMCE settings by using customizeSettings method.
Given callback function (tinymceSettings, tinymce, SchemaBuilder) { ... } will be called before TinyMCE editor instance is initialised.
There are three parameters that we can use:
- tinymceSettings object which is used for initialising TinyMCE editor instance: tinymce.init(tinymceSettings);
  (for more details take a look at the TinyMCE documentation)
- tinymce TinyMCE main object which we can use for example to add new TinyMCE plugin
  (some examples are provided in this part of TinyMCE documentation)
- SchemaBuilder Rich Text Editor controls TinyMCE schema-related settings such as schema, valid_elements, valid_children or custom_elements because only the subset of HTML is supported by Wiki Markup format which is used as a storage format in JIRA. That parameter has been covered in depth on the following page: Tutorial - Customizing Rich Text Editor in JIRA.
Inside the callback body, we're adding textpattern TinyMCE plugin, if it doesn't already exists, and we're configuring that plugin, according to it specification.

Loading the file into editor context

Listing of atlassian-plugin.xml

1
2
<web-resource key="customizations" name="JIRA Editor Reference Plugin Customizations">
    <context>jira.rich.editor</context>

    <resource type="download" name="js/markdown-headings.js" location="js/markdown-headings.js"/>
</web-resource>

And that's it!