TinyMCE customization

TinyMCE customization#

This chapter is a developer reference manual for customizing TinyMCE.

Customize Format menu#

There are several options to customize TinyMCE's Format ‣ Formats menu.

The first two options use TinyMCE's formats JSON configuration. They are less complicated to implement than the third option.

Add-on GenericSetup configuration file#

This option is best for system administrators and developers who write their own add-ons to ease reproducibility.

You can add a GenericSetup configuration file to your add-on, such as profiles/default/registry/tinymce.xml, with the JSON configuration of the custom format.

<registry>
  <records interface="plone.base.interfaces.controlpanel.ITinyMCESchema"
            prefix="plone">
    <value key="formats"
           purge="true"
        >{
        "myformat": {
            "block": "div",
            "classes": "my-css-classes"
        }
    }</value>
  </records>
</registry>

Important

The content of the formats record will overwrite the value in the Formats field in the TinyMCE control panel at Site Setup ‣ TinyMCE ‣ Default. If you want to preserve the default content, you must copy it into your XML.

Next, define where to place the new format inside the Format menu's submenus. You can add your custom format to one of the following menu items. These menu items in the TinyMCE editor correspond to field items in the TinyMCE control panel at Site Setup ‣ TinyMCE ‣ Default.

  • Header styles

  • Inline styles

  • Block styles

  • Alignment styles

  • Table styles

The syntax for each element in those fields is Title|format. The following example XML snippet adds your format to the Inline styles menu. Unlike the previous example, the example does not remove the default values, but appends to it.

<record field="inline_styles"
        interface="plone.base.interfaces.controlpanel.ITinyMCESchema"
        name="plone.inline_styles">
  <value>
    <element>My custom format|myformat</element>
  </value>
</record>

Edit the Formats option in the TinyMCE control panel#

This option is good for quick edits, but is not as reproducible as the GenericSetup option.

You can manually customize the Formats value through-the-web in the TinyMCE control panel.

  1. Navigate to Site Setup ‣ TinyMCE ‣ Default, or append @@tinymce-controlpanel to the root of your website in your browser's location bar.

  2. Scroll down to Formats, and edit the JSON configuration.

  3. Insert your custom format to one of the fields mentioned above.

  4. Click the Save button.

Inject formats with files named tinymce-formats.css#

This option is more complex to implement than the previous options. However it is the only option where you can add items to the Formats submenu as siblings to the Formats styles configurations.

In Plone 6, TinyMCE has a special logic that automatically reads registered files named tinymce-formats.css and adds the CSS classes defined in those files to TinyMCE's Format ‣ Formats menu by using the importcss_file_filter option.

To add custom formats, you can provide your own files.

  1. Name the file tinymce-formats.css.

  2. Register the file as a resource in your Plone site.

  3. Include the file in the TinyMCE control panel in the textarea input Choose the CSS used in WYSIWYG Editor Area.

    1. Navigate to Site Setup ‣ TinyMCE ‣ Default, or append @@tinymce-controlpanel to the root of your website in your browser's location bar.

    2. Scroll down to Choose the CSS used in WYSIWYG Editor Area.

CSS styles defined in this file will automatically be added to the top level of TinyMCE's Format ‣ Formats menu.

Remove imported formats#

Similar to adding formats, you can remove formats in a couple of ways.

Add-on GenericSetup configuration file#

Alternatively, you can use GenericSetup in your add-on.

<record field="content_css"
          interface="plone.base.interfaces.controlpanel.ITinyMCESchema"
          name="plone.content_css"
  >
    <value purge="true">
      <element>++theme++barceloneta/tinymce/tinymce-ui-content.css</element>
    </value>
  </record>

Configure the TinyMCE control panel#

Plone 6 Classic UI ships with the Barceloneta theme which includes two custom formats, highlight-inline and p.highlight-paragraph, in the TinyMCE Format ‣ Formats menu. You can remove these formats through the TinyMCE control panel.

  1. Navigate to Site Setup ‣ TinyMCE ‣ Default, or append @@tinymce-controlpanel to the root of your website in your browser's location bar.

  2. Scroll down to Choose the CSS used in WYSIWYG Editor Area.

  3. Remove the entry ++theme++barceloneta/tinymce/tinymce-formats.css.

  4. Click the Save button.

Once removed, the custom formats will no longer appear in the menu.

Configure <iframe> sandboxing#

Since version 7.0, TinyMCE adds the attribute sandbox="" to make the <iframe> elements sandboxed with all restrictions.

To customize this behavior, there are two options which you can add to the Other settings JSON configuration in the Advanced tab of the TinyMCE control panel.

If you want to deactivate sandboxing in general, use the following JSON configuration.

{
  "sandbox_iframes": false
}

You can also exclude certain URLs from being sandboxed as follows.

{
  "sandbox_iframes_exclusions": [
    "my.url.com"
  ]
}

See also

See sandbox_iframes_exclusions for TinyMCE's default settings.

Insert preconfigured HTML blocks#

You can add custom HTML blocks in TinyMCE. You can insert them in your content using the TinyMCE Insert Template menu option using the TinyMCE Template plugin.

This option is best for system administrators and developers who write their own add-ons to ease reproducibility.

You can add a GenericSetup configuration file to your add-on, such as profiles/default/registry/tinymce.xml, with the configuration of the HTML blocks. The following example adds three HTML files, each of which contains its custom HTML block.

<registry>
    <record name="plone.templates" interface="Products.CMFPlone.interfaces.controlpanel.ITinyMCESchema" field="templates">
    <field type="plone.registry.field.Text">
      <default></default>
      <description xmlns:ns0="http://xml.zope.org/namespaces/i18n" ns0:domain="plone" ns0:translate="help_tinymce_templates">Enter the list of templates in json format                 http://www.tinymce.com/wiki.php/Plugin:template</description>
      <required>False</required>
      <title xmlns:ns0="http://xml.zope.org/namespaces/i18n" ns0:domain="plone" ns0:translate="label_tinymce_templates">Templates</title>
    </field>
    <value>[
      {"title": "Image and Text", "url": "++theme++my.theme/tinymce-templates/bs-dark-hero.html"},
      {"title": "Image and Text", "url": "++theme++my.theme/tinymce-templates/bs-hero-left.html"},
      {"title": "Image and Text", "url": "++theme++my.theme/tinymce-templates/bs-pricing.html"},
      ]
    </value>
  </record>
</registry>

Tip

The file profiles/default/registry.xml can be split in several files in {file} the directory profiles/default/registry with arbitrary names ending in .xml. This makes it easier to maintain and reuse your registry files.

Use TinyMCE with a commercial license#

Added in version Plone: 6.2

If you own a commercial TinyMCE license, you can enter the key in the control panel Site Setup ‣ TinyMCE ‣ Advanced.

The TinyMCE 8 commercial license key will have a T8LK: prefix.

See more information in the TinyMCE licensing documentation.

If you have a TinyMCE license before version 8, read the important License key migration documentation.

Commercial license key manager plugin#

Since we can't provide the license key manager plugin out of the box, because this is only shipped with a paid TinyMCE package, you have to provide the plugin in your own add-on package.

See Setting up the Commercial License Key Manager for more information of how to get the plugin.

You have to provide the plugin file as a static resource and register it in Site Setup ‣ TinyMCE ‣ Plugins and Toolbar -> Custom plugins as shown.

licensekeymanager|++plone++path.to.licensekeymanager.resource.js

You can also provide this value in your add-on GenericSetup configuration, such as profiles/default/registry/tinymce.xml.

<records prefix="plone" interface="plone.base.interfaces.controlpanel.ITinyMCESchema">
  <value key="custom_plugins" purge="false">
    <element>licensekeymanager|++plone++path.to.licensekeymanager.resource.js</element>
  </value>
</records>
Contents