Configuring TinyMCE#

Adding and removing capabilities#

In its simplest form, TinyMCE configuration includes adding and removing buttons and plugins.

You can add plugins to the editor using the TinyMCEConfig::enablePlugins() method. This will transparently generate the relevant underlying TinyMCE code.

Copy// app/_config.php
use SilverStripe\Forms\HTMLEditor\HTMLEditorConfig;
use SilverStripe\TinyMCE\TinyMCEConfig;

$editorConfig = HTMLEditorConfig::get('cms');
if ($editorConfig instanceof TinyMCEConfig) {
    $editorConfig->enablePlugins('emoticons');
}

Plugins and advanced themes can provide additional buttons that can be added (or removed) through the configuration. Here is an example of adding a ssmacron button after the charmap button:

Copy// app/_config.php
use SilverStripe\TinyMCE\TinyMCEConfig;

TinyMCEConfig::get('cms')->insertButtonsAfter('charmap', 'ssmacron');

Buttons can also be removed:

Copy// app/_config.php
use SilverStripe\TinyMCE\TinyMCEConfig;

TinyMCEConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr');

Enabling custom plugins#

It is also possible to add custom plugins to TinyMCE, for example toolbar buttons. You can enable them through TinyMCEConfig::enablePlugins():

Copy// app/_config.php
use SilverStripe\TinyMCE\TinyMCEConfig;

TinyMCEConfig::get('cms')->enablePlugins(['myplugin' => 'app/javascript/myplugin/editor_plugin.js']);

You can learn how to create a plugin from the TinyMCE documentation.

Setting options#

TinyMCE behaviour can be affected through its configuration options. These options will be passed straight to the editor.

A default set of options has been defined in the TinyMCEConfig.default_options configuration property. Updating this configuration property will update the default options which are set for all TinyMCEConfig instances.

For example to disable resizing TinyMCE editors:

CopySilverStripe\TinyMCE\TinyMCEConfig:
  default_options:
    resize: false

You can also set options for a specific named config, either by setting HTMLEditorConfig.default_config_definitions via YAML configuration or by calling setOption in your _config.php file:

CopySilverStripe\Forms\HTMLEditor\HTMLEditorConfig:
  default_config_definitions:
    my-config:
      options:
        resize: false

Copy// app/_config.php
use SilverStripe\TinyMCE\TinyMCEConfig;

TinyMCEConfig::get('my-config')->setOption('resize', false);

[!HINT] Note that the setOption() method overrides any existing value for that option. For options that accept a string or array, if you only want to change some small part of the existing option value, you can call getOption(), modify the returned value, and then pass the result to setOption().

Image size pre-sets#

Silverstripe CMS will suggest pre-set image size in the HTML editor. Content authors can quickly switch between the pre-set size when interacting with images.

The default values are defined in TinyMCEConfig.image_size_presets. Developers can customise the pre-set sizes by altering their TinyMCEConfig.

You can alter the defaults for all TinyMCE editors with YAML configuration.

CopySilverStripe\TinyMCE\TinyMCEConfig:
  image_size_presets:
    - name: widesize
      i18n: SilverStripe\TinyMCE\TinyMCEConfig.WIDE_SIZE
      text: Wide size
      width: 900

You can edit the image size pre-sets for an individual configuration by calling setOption() on a TinyMCEConfig instance.

Remember that calling setOption() overrides the existing value, so you need to also include the default presets if you want those.

Copyuse SilverStripe\TinyMCE\TinyMCEConfig;

$presets = array_merge(
    [
        [
            'width' => 300,
            'text' => 'Small fit',
            'name' => 'smallfit',
            'default' => true,
        ],
    ],
    TinyMCEConfig::config()->get('image_size_presets')
);
TinyMCEConfig::get('cms')->setOption('image_size_presets', $presets);

Disable oEmbed#

The "oEmbed" standard is implemented by many media services around the web, allowing easy representation of files just by referencing a website URL. For example, a content author can insert a playable youtube video just by knowing its URL, as opposed to dealing with manual HTML code.

To disable oEmbed you will need to follow the below to remove the plugin from TinyMCE, as well as disabling the internal service via YAML:

Copyuse SilverStripe\TinyMCE\TinyMCEConfig;

TinyMCEConfig::get('cms')->disablePlugins('ssembed');

Copy---
Name: oembed-disable
---
SilverStripe\AssetAdmin\Forms\RemoteFileFormFactory:
  enabled: false

Doctypes#

Since TinyMCE generates markup, it needs to know which doctype your documents will be rendered in. You can set this through the element_format configuration variable.

In case you want to adhere to the stricter xhtml format (for example rendering self closing tags like <br/> instead of <br>), use the following configuration:

Copyuse SilverStripe\TinyMCE\TinyMCEConfig;

TinyMCEConfig::get('cms')->setOption('element_format', 'xhtml');