2014-12-08 21:03:02 +01:00
title: Rich-text editing (WYSIWYG)
summary: SilverStripe's use and configuration of TinyMCE html editor.
2012-02-14 00:49:34 +01:00
2014-12-08 21:03:02 +01:00
# Rich-text editing (WYSIWYG)
2012-02-14 00:49:34 +01:00
2014-10-22 12:47:56 +02:00
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 ](http://tinymce.com ).
2012-02-14 00:49:34 +01:00
2014-10-22 12:47:56 +02:00
On top of the base functionality, we use our own insertion dialogs to ensure you can effectively select and upload
2016-01-14 11:59:53 +01:00
files. In addition to the markup managed by TinyMCE, we use [shortcodes ](/developer_guides/extending/shortcodes ) to store
2014-10-22 12:47:56 +02:00
information about inserted images or media elements.
2012-02-14 00:49:34 +01:00
2017-07-03 03:22:12 +02:00
The framework comes with a [HTMLEditorField ](api:SilverStripe\Forms\HTMLEditor\HTMLEditorField ) form field class which encapsulates most of the required
functionality. It is usually added through the [DataObject::getCMSFields() ](api:SilverStripe\ORM\DataObject::getCMSFields( )) method:
2012-02-14 00:49:34 +01:00
2014-10-22 12:47:56 +02:00
**mysite/code/MyObject.php**
2017-08-03 02:51:32 +02:00
```php
2017-08-03 05:35:09 +02:00
2012-02-14 00:49:34 +01:00
class MyObject extends DataObject {
2014-10-22 12:47:56 +02:00
2017-08-03 05:35:09 +02:00
private static $db = [
2014-10-22 12:47:56 +02:00
'Content' => 'HTMLText'
2017-08-03 05:35:09 +02:00
];
2013-01-24 01:43:54 +01:00
2012-02-14 00:49:34 +01:00
public function getCMSFields() {
2014-10-22 12:47:56 +02:00
return new FieldList(
new HTMLEditorField('Content')
);
2012-02-14 00:49:34 +01:00
}
}
2017-08-03 05:35:09 +02:00
2017-08-03 02:51:32 +02:00
```
2012-02-14 00:49:34 +01:00
2015-06-09 02:01:21 +02:00
### Specify which configuration to use
2017-07-03 03:22:12 +02:00
By default, a config named 'cms' is used in any new [HTMLEditorField ](api:SilverStripe\Forms\HTMLEditor\HTMLEditorField ).
2015-06-09 02:01:21 +02:00
2017-07-03 03:22:12 +02:00
If you have created your own [HtmlEditorConfig ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig ) and would like to use it,
you can call `HtmlEditorConfig::set_active('myConfig')` and all subsequently created [HTMLEditorField ](api:SilverStripe\Forms\HTMLEditor\HTMLEditorField )
2015-06-09 02:01:21 +02:00
will use the configuration with the name 'myConfig'.
2017-07-03 03:22:12 +02:00
You can also specify which [HtmlEditorConfig ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig ) to use on a per field basis via the construct argument.
This is particularly useful if you need different configurations for multiple [HTMLEditorField ](api:SilverStripe\Forms\HTMLEditor\HTMLEditorField ) on the same page or form.
2015-06-09 02:01:21 +02:00
2017-08-03 02:51:32 +02:00
```php
2015-06-09 02:01:21 +02:00
class MyObject extends DataObject {
2017-08-03 05:35:09 +02:00
private static $db = [
2015-06-09 02:01:21 +02:00
'Content' => 'HTMLText',
'OtherContent' => 'HTMLText'
2017-08-03 05:35:09 +02:00
];
2015-06-09 02:01:21 +02:00
public function getCMSFields() {
2017-08-03 05:35:09 +02:00
return new FieldList([
2015-06-09 02:01:21 +02:00
new HTMLEditorField('Content'),
new HTMLEditorField('OtherContent', 'Other content', $this->OtherContent, 'myConfig')
2017-08-03 05:35:09 +02:00
]);
2015-06-09 02:01:21 +02:00
}
}
2017-08-03 05:35:09 +02:00
2017-08-03 02:51:32 +02:00
```
2015-06-09 02:01:21 +02:00
In the above example, the 'Content' field will use the default 'cms' config while 'OtherContent' will be using 'myConfig'.
2012-02-14 00:49:34 +01:00
## Configuration
2014-10-22 12:47:56 +02:00
To keep the JavaScript editor configuration manageable and extensible, we've wrapped it in a PHP class called
2017-07-03 03:22:12 +02:00
[HtmlEditorConfig ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig ). The class comes with its own defaults, which are extended through the [Configuration API ](../../configuration )
2013-03-27 12:06:57 +01:00
in the framework (and the `cms` module in case you've got that installed).
2014-10-22 12:47:56 +02:00
2017-07-03 03:22:12 +02:00
There can be multiple configs, which should always be created / accessed using [HtmlEditorConfig::get() ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig::get( )). You can
2014-10-22 12:47:56 +02:00
then set the currently active config using `set_active()` .
< div class = "info" markdown = "1" >
< / div >
2012-02-14 00:49:34 +01:00
2013-01-23 21:53:33 +01:00
< div class = "notice" markdown = '1' >
2014-10-22 12:47:56 +02:00
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.
2013-01-23 21:53:33 +01:00
< / div >
2014-10-22 12:47:56 +02:00
## Adding and removing capabilities
2013-01-23 21:53:33 +01:00
In its simplest form, the configuration of the editor includes adding and removing buttons and plugins.
2017-07-03 03:22:12 +02:00
You can add plugins to the editor using the Framework's [HtmlEditorConfig::enablePlugins() ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig::enablePlugins( )) method. This will
2013-01-23 21:53:33 +01:00
transparently generate the relevant underlying TinyMCE code.
2012-02-14 00:49:34 +01:00
2014-10-22 12:47:56 +02:00
**mysite/_config.php**
2017-08-03 02:51:32 +02:00
```php
2012-02-14 00:49:34 +01:00
HtmlEditorConfig::get('cms')->enablePlugins('media');
2017-08-03 02:51:32 +02:00
```
2012-02-14 00:49:34 +01:00
2014-10-22 12:47:56 +02:00
< div class = "notice" markdown = "1" >
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).
< / div >
2013-01-23 21:53:33 +01:00
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:
2014-10-22 12:47:56 +02:00
**mysite/_config.php**
2017-08-03 02:51:32 +02:00
```php
2013-01-23 21:53:33 +01:00
HtmlEditorConfig::get('cms')->insertButtonsAfter('charmap', 'ssmacron');
2017-08-03 02:51:32 +02:00
```
2013-01-23 21:53:33 +01:00
Buttons can also be removed:
2012-02-14 00:49:34 +01:00
2014-10-22 12:47:56 +02:00
**mysite/_config.php**
2017-08-03 02:51:32 +02:00
```php
2012-02-14 00:49:34 +01:00
HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr');
2017-08-03 02:51:32 +02:00
```
2012-02-14 00:49:34 +01:00
2014-10-22 12:47:56 +02:00
< div class = "notice" markdown = "1" >
2017-07-03 03:22:12 +02:00
Internally [HtmlEditorConfig ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig ) uses the TinyMCE's `theme_advanced_buttons` option to configure these. See the
2014-10-22 12:47:56 +02:00
[TinyMCE documentation of this option ](http://www.tinymce.com/wiki.php/Configuration:theme_advanced_buttons_1_n )
2013-01-23 21:53:33 +01:00
for more details.
2014-10-22 12:47:56 +02:00
< / div >
2013-01-23 21:53:33 +01:00
### Setting options
TinyMCE behaviour can be affected through its [configuration options ](http://www.tinymce.com/wiki.php/Configuration ).
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](http://www.tinymce.com/wiki.php/Configuration:extended_valid_elements) - the tags that will not be stripped
from the HTML source by the editor.
2014-10-22 12:47:56 +02:00
**mysite/_config.php**
2017-08-03 02:51:32 +02:00
```php
2013-01-23 21:53:33 +01:00
// Add start and type attributes for < ol > , add < object > and < embed > with all attributes.
HtmlEditorConfig::get('cms')->setOption(
'extended_valid_elements',
'img[class|src|alt|title|hspace|vspace|width|height|align|onmouseover|onmouseout|name|usemap],' .
'iframe[src|name|width|height|title|align|allowfullscreen|frameborder|marginwidth|marginheight|scrolling],' .
'object[classid|codebase|width|height|data|type],' .
'embed[src|type|pluginspage|width|height|autoplay],' .
'param[name|value],' .
'map[class|name|id],' .
'area[shape|coords|href|target|alt],' .
'ol[start|type]'
);
2017-08-03 02:51:32 +02:00
```
2013-01-23 21:53:33 +01:00
2014-10-22 12:47:56 +02:00
< div class = "notice" markdown = "1" >
The default setting for the CMS's `extended_valid_elements` we are overriding here can be found in
2013-01-23 21:53:33 +01:00
`framework/admin/_config.php` .
2014-10-22 12:47:56 +02:00
< / div >
2013-01-23 21:53:33 +01:00
2014-10-22 12:47:56 +02:00
## Writing custom plugins
2013-01-23 21:53:33 +01:00
2016-05-27 03:08:22 +02:00
It is also possible to add custom plugins to TinyMCE, for example toolbar buttons.
2017-07-03 03:22:12 +02:00
You can enable them through [HtmlEditorConfig::enablePlugins() ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig::enablePlugins( )):
2013-01-23 21:53:33 +01:00
2014-10-22 12:47:56 +02:00
**mysite/_config.php**
2017-08-03 02:51:32 +02:00
```php
2017-08-03 05:35:09 +02:00
HtmlEditorConfig::get('cms')->enablePlugins(['myplugin' => '../../../mysite/javascript/myplugin/editor_plugin.js']);
2017-08-03 02:51:32 +02:00
```
2013-01-23 21:53:33 +01:00
2016-05-27 03:08:22 +02:00
You can learn how to [create a plugin ](http://www.tinymce.com/wiki.php/Creating_a_plugin ) from the TinyMCE documentation.
2013-01-23 21:53:33 +01:00
2014-12-08 21:03:02 +01:00
## Image and media insertion
2012-06-08 18:30:31 +02:00
2017-07-03 03:22:12 +02:00
The [HtmlEditorField ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorField ) API also handles inserting images and media files into the managed HTML content. It can be
used both for referencing files on the webserver filesystem (through the [File ](api:SilverStripe\Assets\File ) and [Image ](api:SilverStripe\Assets\Image ) APIs), as well
2014-10-22 12:47:56 +02:00
as hotlinking files from the web.
2013-04-16 14:01:04 +02:00
2016-01-14 11:59:53 +01:00
We use [shortcodes ](/developer_guides/extending/shortcodes ) to store information about inserted images or media elements. The
2017-07-03 03:22:12 +02:00
[ShortcodeParser ](api:SilverStripe\View\Parsers\ShortcodeParser ) API post-processes the HTML content on rendering, and replaces the shortcodes accordingly. It also
2014-10-22 12:47:56 +02:00
takes care of care of placing the shortcode replacements relative to its surrounding markup (e.g. left/right alignment).
2012-06-08 18:30:31 +02:00
## oEmbed: Embedding media through external services
2014-10-22 12:47:56 +02:00
The ["oEmbed" standard ](http://www.oembed.com/ ) 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.
2012-06-08 18:30:31 +02:00
2017-07-03 03:22:12 +02:00
oEmbed powers the "Insert from web" feature available through [HtmlEditorField ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorField ). Internally, it makes HTTP
2014-10-22 12:47:56 +02:00
queries to a list of external services if it finds a matching URL. These services are described in the
`Oembed.providers` configuration. Since these requests are performed on page rendering, they typically have a long
cache time (multiple days).
< div class = "info" markdown = "1" >
To refresh a oEmbed cache, append `?flush=1` to a URL.
< / div >
2012-06-08 18:30:31 +02:00
To disable oEmbed usage, set the `Oembed.enabled` configuration property to "false".
2015-11-12 22:51:13 +01:00
## Limiting oembed URLs
HtmlEditorField can have whitelists set on both the scheme (default http & https) and domains allowed when
inserting files for use with oembed.
2017-07-03 03:22:12 +02:00
This is performed through the config variables [RemoteFileFormFactory::$fileurl_scheme_whitelist ](api:SilverStripe\AssetAdmin\Forms\RemoteFileFormFactory::$fileurl_scheme_whitelist ) and
[RemoteFileFormFactory::$fileurl_domain_whitelist ](api:SilverStripe\AssetAdmin\Forms\RemoteFileFormFactory::$fileurl_domain_whitelist ).
2015-11-12 22:51:13 +01:00
Setting these configuration variables to empty arrays will disable the whitelist. Setting them to an array of
lower case strings will require the scheme or domain respectively to exactly match one of those strings (no
wildcards are currently supported).
2013-04-16 14:01:04 +02:00
### Doctypes
2014-10-22 12:47:56 +02:00
Since TinyMCE generates markup, it needs to know which doctype your documents will be rendered in. You can set this
through the [element_format ](http://www.tinymce.com/wiki.php/Configuration:element_format ) configuration variable. It
defaults to the stricter 'xhtml' setting, for example rendering self closing tags like `<br/>` instead of `<br>` .
2013-04-16 14:01:04 +02:00
In case you want to adhere to HTML4 instead, use the following configuration:
2017-08-03 02:51:32 +02:00
```php
2013-04-16 14:01:04 +02:00
HtmlEditorConfig::get('cms')->setOption('element_format', 'html');
2017-08-03 02:51:32 +02:00
```
2013-04-16 14:01:04 +02:00
2014-10-22 12:47:56 +02:00
By default, TinyMCE and SilverStripe will generate valid HTML5 markup, but it will strip out HTML5 tags like
`<article>` or `<figure>` . If you plan to use those, add them to the
[valid_elements ](http://www.tinymce.com/wiki.php/Configuration:valid_elements ) configuration setting.
2013-04-16 14:01:04 +02:00
2017-07-03 03:22:12 +02:00
Also, the [HTMLValue ](api:SilverStripe\View\Parsers\HTMLValue ) API underpinning the HTML processing parses the markup into a temporary object tree
2014-10-22 12:47:56 +02:00
which can be traversed and modified before saving. The built-in parser only supports HTML4 and XHTML syntax. In order
to successfully process HTML5 tags, please use the
2013-04-16 14:01:04 +02:00
['silverstripe/html5' module ](https://github.com/silverstripe/silverstripe-html5 ).
2012-02-14 00:49:34 +01:00
## Recipes
2014-12-08 21:03:02 +01:00
### Customising the "Insert" panels
2012-02-14 00:49:34 +01:00
In the standard installation, you can insert links (internal/external/anchor/email),
images as well as flash media files. The forms used for preparing the new content element
are rendered by SilverStripe, but there's some JavaScript involved to transfer
back and forth between a content representation the editor can understand, present and save.
Example: Remove field for "image captions"
2017-08-03 02:51:32 +02:00
```php
2012-02-14 00:49:34 +01:00
// File: mysite/code/MyToolbarExtension.php
class MyToolbarExtension extends Extension {
public function updateFieldsForImage(& $fields, $url, $file) {
2015-05-24 03:35:53 +02:00
$fields->removeByName('CaptionText');
2012-02-14 00:49:34 +01:00
}
}
2017-08-03 02:51:32 +02:00
```
```php
2012-02-14 00:49:34 +01:00
// File: mysite/_config.php
2017-07-03 03:22:12 +02:00
ModalController::add_extension('MyToolbarExtension');
2017-08-03 02:51:32 +02:00
```
2012-02-14 00:49:34 +01:00
Adding functionality is a bit more advanced, you'll most likely
need to add some fields to the PHP forms, as well as write some
JavaScript to ensure the values from those fields make it into the content
elements (and back out in case an existing element gets edited).
2017-07-03 03:22:12 +02:00
There's lots of extension points in the [ModalController ](api:SilverStripe\Admin\ModalController ) class
2012-02-14 00:49:34 +01:00
to get you started.
### Security groups with their own editor configuration
Different groups of authors can be assigned their own config,
e.g. a more restricted rule set for content reviewers (see the "Security" )
2017-07-03 03:22:12 +02:00
The config is available on each user record through [Member::getHtmlEditorConfigForCMS() ](api:SilverStripe\Security\Member::getHtmlEditorConfigForCMS( )).
The group assignment is done through the "Security" interface for each [Group ](api:SilverStripe\Security\Group ) record.
2012-02-14 00:49:34 +01:00
Note: The dropdown is only available if more than one config exists.
### Using the editor outside of the CMS
Each interface can have multiple fields of this type, each with their own toolbar to set formatting
and insert HTML elements. They do share one common set of dialogs for inserting links and other media though,
2017-07-03 03:22:12 +02:00
encapsulated in the [ModalController ](api:SilverStripe\Admin\ModalController ) class.
2014-12-08 21:03:02 +01:00
In the CMS, those dialogs are automatically instantiate, but in your own interfaces outside
of the CMS you have to take care of instantiate yourself:
2012-02-14 00:49:34 +01:00
2017-08-03 02:51:32 +02:00
```php
2012-02-14 00:49:34 +01:00
// File: mysite/code/MyController.php
class MyObjectController extends Controller {
2017-05-25 03:43:13 +02:00
public function Modals() {
return ModalController::create($this, "Modals");
2012-02-14 00:49:34 +01:00
}
}
2017-08-03 02:51:32 +02:00
```
2012-02-14 00:49:34 +01:00
Note: The dialogs rely on CMS-access, e.g. for uploading and browsing files,
so this is considered advanced usage of the field.
2017-08-03 02:51:32 +02:00
```php
2012-02-14 00:49:34 +01:00
// File: mysite/_config.php
HtmlEditorConfig::get('cms')->disablePlugins('ssbuttons');
2012-05-22 06:45:36 +02:00
HtmlEditorConfig::get('cms')->removeButtons('sslink', 'ssmedia');
HtmlEditorConfig::get('cms')->addButtonsToLine(2, 'link', 'media');
2017-08-03 02:51:32 +02:00
```
2012-02-14 00:49:34 +01:00
### Developing a wrapper to use a different WYSIWYG editors with HTMLEditorField
WYSIWYG editors are complex beasts, so replacing it completely is a difficult task.
The framework provides a wrapper implementation for the basic required functionality,
mainly around selecting and inserting content into the editor view.
Have a look in `HtmlEditorField.js` and the `ss.editorWrapper` object to get you started
2017-07-03 03:22:12 +02:00
on your own editor wrapper. Note that the [HtmlEditorConfig ](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig ) is currently hardwired to support TinyMCE,
2012-02-14 00:49:34 +01:00
so its up to you to either convert existing configuration as applicable,
or start your own configuration.
2013-08-03 16:15:52 +02:00
### Integrating a Spellchecker for TinyMCE
The TinyMCE editor uses spellchecking integrated into the browser if possible
([docs](http://www.tinymce.com/wiki.php/Plugin3x:spellchecker)).
Most modern browsers support it, although Internet Explorer only has limited
support in IE10. Alternatively, you can use the PSpell PHP module for server side checks.
Assuming you have the module installed, here's how you enable its use in `mysite/_config.php` :
2017-08-03 02:51:32 +02:00
```php
2013-10-23 19:59:07 +02:00
HtmlEditorConfig::get('cms')->enablePlugins('spellchecker', 'contextmenu');
2013-08-03 16:15:52 +02:00
HtmlEditorConfig::get('cms')->addButtonsToLine(2, 'spellchecker');
HtmlEditorConfig::get('cms')->setOption(
'spellchecker_rpc_url',
THIRDPARTY_DIR . '/tinymce-spellchecker/rpc.php'
);
HtmlEditorConfig::get('cms')->setOption('browser_spellcheck', false);
2017-08-03 02:51:32 +02:00
```
2013-08-03 16:15:52 +02:00
Now change the default spellchecker in `framework/thirdparty/tinymce-spellchecker/config.php` :
2017-08-03 02:51:32 +02:00
```php
2013-08-03 16:15:52 +02:00
// ...
$config['general.engine'] = 'PSpell';
2017-08-03 02:51:32 +02:00
```