13 KiB

Raw Blame History

title: Rich-text editing (WYSIWYG) summary: SilverStripe's use and configuration of TinyMCE html editor.

Rich-text editing (WYSIWYG)

Editing and formatting content is the bread and butter of every content management system, which is why SilverStripe has a tight integration with our preferred editor library, TinyMCE.

On top of the base functionality, we use our own insertion dialogs to ensure you can effectively select and upload files. In addition to the markup managed by TinyMCE, we use shortcodes to store information about inserted images or media elements.

The framework comes with a [api:HTMLEditorField] form field class which encapsulates most of the required functionality. It is usually added through the [api:DataObject::getCMSFields()] method:

mysite/code/MyObject.php

:::php
<?php

class MyObject extends DataObject {
	
	private static $db = array(
		'Content' => 'HTMLText'
	);
	
	public function getCMSFields() {
		return new FieldList(
			new HTMLEditorField('Content')
		);
	}
}

Specify which configuration to use

By default, a config named 'cms' is used in any new [api:HTMLEditorField].

If you have created your own [api:HtmlEditorConfig] and would like to use it, you can call HtmlEditorConfig::set_active('myConfig') and all subsequently created [api:HTMLEditorField] will use the configuration with the name 'myConfig'.

You can also specify which [api:HtmlEditorConfig] to use on a per field basis via the construct argument. This is particularly useful if you need different configurations for multiple [api:HTMLEditorField] on the same page or form.

:::php
class MyObject extends DataObject {
	private static $db = array(
		'Content' => 'HTMLText',
		'OtherContent' => 'HTMLText'
	);
	
	public function getCMSFields() {
		return new FieldList(array(
			new HTMLEditorField('Content'),
			new HTMLEditorField('OtherContent', 'Other content', $this->OtherContent, 'myConfig')
		));
	}
}

In the above example, the 'Content' field will use the default 'cms' config while 'OtherContent' will be using 'myConfig'.

Configuration

To keep the JavaScript editor configuration manageable and extensible, we've wrapped it in a PHP class called [api:HtmlEditorConfig]. The class comes with its own defaults, which are extended through the Configuration API in the framework (and the cms module in case you've got that installed).

There can be multiple configs, which should always be created / accessed using [api:HtmlEditorConfig::get()]. You can then set the currently active config using set_active().

Currently the order in which the `_config.php` files are executed depends on the module directory names. Execution order is alphabetical, so if you set a TinyMCE option in the `aardvark/_config.php`, this will be overridden in `framework/admin/_config.php` and your modification will disappear.

Adding and removing capabilities

In its simplest form, the configuration of the editor includes adding and removing buttons and plugins.

You can add plugins to the editor using the Framework's [api:HtmlEditorConfig::enablePlugins()] method. This will transparently generate the relevant underlying TinyMCE code.

mysite/_config.php :::php HtmlEditorConfig::get('cms')->enablePlugins('media');

This utilities the TinyMCE's `PluginManager::load` function under the hood (check the [TinyMCE documentation on plugin loading](http://www.tinymce.com/wiki.php/API3:method.tinymce.AddOnManager.load) for details).

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:

mysite/_config.php :::php HtmlEditorConfig::get('cms')->insertButtonsAfter('charmap', 'ssmacron');

Buttons can also be removed:

mysite/_config.php :::php HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr');

Internally [api:HtmlEditorConfig] uses the TinyMCE's `theme_advanced_buttons` option to configure these. See the [TinyMCE documentation of this option](http://www.tinymce.com/wiki.php/Configuration:theme_advanced_buttons_1_n) for more details.

Setting options

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

One example of the usage of this capability is to redefine the TinyMCE's whitelist of HTML tags - the tags that will not be stripped from the HTML source by the editor.

mysite/_config.php :::php // Add start and type attributes for

, add

13 KiB Raw Blame History