The expansion of Movable Type’s Rich Text Editor with config.yaml
In Movable Type 5.2, there are two ways to expand the Rich Text Editor’s API functions.
One way was already explained in “The expansion of Movable Type’s Rich Text Editor” In short, by inserting MTML via plugin. Because Javascript and CSS can be used with this option, there are no limitations on what can be customized.
In the second method, custom changes can be specified in config.yaml. With the right settings in place, this method might be easier since custom changes can be specified without the use of Javascript or CSS.
This document will focus on explaining how to expand the Rich Text Editor with config.yaml.
Let’s first talk about how to set up the Rich Text Editor to work with config.yaml.
TinyMCE, the default Rich Text Editor of Movable Type 5.2, has several configurable elements, allowing the user to change certain functions within the editor. For example, the behavior of the edit button or the HTML of a published page or blog, among other things.
Now, let’s talk about writing for config.yaml.
As an example, let’s create a plugin that will transform any inserted object from a “p” element to a “div” element when a new line is entered.
In TinyMCE, there is a setting, “forced_root_block” that can change the “div” function value.
If the plugin is named ForceDIVForTinyMCE, the installation location will be set to plugins/ForceDIVForTinyMCE/config.yaml and the contents will look like this:
id: ForceDIVForTinyMCE
name: ForceDIVForTinyMCE
version: 1.00
editors:
tinymce:
config:
forced_root_block: div
The last 4 lines are essential if you want the plugin to work. The name of the Rich Text Editor you wish to expand should be specified under the editors key. The default setting for this is tinymce. Under the “editors” key is the config key. Any setting changes need to be written underneath the “config” key.
You do not need to create any other files aside from the config.yaml file in order to define the plugin function.
Let’s look at few more examples.
This example shows how to create a plugin that inserts a “p” element instead of a “br” element after pressing the “Enter” key.
id: EnterBrForTinyMCE
name: EnterBrForTinyMCE
version: 1.00
editors:
tinymce:
config:
force_br_newlines: true
force_p_newlines: ~
forced_root_block: ''
This example shows how to create a plugin that forces the use of HTML5 editing rules.
id: HTML5ForTinyMCE
name: HTML5ForTinyMCE
version: 1.00
editors:
tinymce:
config:
schema: html5
verify_html: true
valid_children: ''
This example shows how to create a plugin that changes an the URL of an image or link from an absolute path to a relative path.
id: RelativeURLForTinyMCE
name: RelativeURLForTinyMCE
version: 1.00
editors:
tinymce:
config:
relative_urls: ~
convert_urls: true
remove_script_host: true
With config.yaml, developers can easily create plugins with very simple code, however there are a few things to keep in mind.
The “false” value is used often in documents when you want to negate the effects of a certain setting.
Since the API of MovableType’s Rich Text Editor cannot properly assess the “false” value, it must be replaced by “~”.
(Strictly speaking, “false” and “~” are not always as easily interchangeable. Inside TinyMCE, however, the value is close enough that they are considered the same.)
Any values specified in config.yaml will not add to but overwrite any existing plugins.
For example, if you were to use the wordcount plugin below (included in TinyMCE), other plugins may not be read.
id: WordcountForTinyMCE
name: WordcountForTinyMCE
version: 1.00
editors:
tinymce:
config:
plugins: wordcount
Because of this issue, any and all necessary plugins need to be written out as shown in the example below:
id: WordcountForTinyMCE
name: WordcountForTinyMCE
version: 1.00
editors:
tinymce:
config:
plugins: lists,style,mt_inlinepopups,media,paste,mt_fullscreen,xhtmlxtras,mt,wordcount
Unfortunately, by using this method of calling out plugin functions in config.yaml, the plugins will end up overwriting themselves, which, in a worst case scenario, can result in only parts of the plugins going into effect instead of all of them.
In order to avoid this problem, we recommend using the method described in “The expansion of Movable Type’s Rich Text Editor” if you want to use plugins to customize type.
The TinyMCE Rich Text Editor is not the only editor capable of being expanded through the use of config.yaml, and this warning is mainly for those other editors. If you are customizing Movable Type’s TinyMCE via the user’s manual, you can ignore the warning below.
In the CKEditor, for example, there is an enterMode element. In the CKEditor’s official user manual, it states the enterMode can be customized through the value CKEDITOR.ENTER_BR.
However, CKEDITOR.ENTER_BR is a Javascript expression that cannot be read by Movable Type’s API. Consequently, if using this element inside config.yaml you must also set the value of CKEDITOR.ENTER_BR, to 2.
With the new API, Rich Text Editors other than TinyMCE can be used and expanded through config.yaml. In fact, both CKEditor and CodeMirror are supported and both editors can be expanded using the same methods used for TinyMCE.
This is an example of a CKEditor Plugin where a p element is inserted instead of a br element after pushing the “Enter” key.
id: EnterBrForCKEditor
name: EnterBrForCKEditor
version: 1.00
editors:
ckeditor:
config:
enterMode: 2
This is an example of a CodeMirror plugin that instructs the editor to ignore line wrapping.
id: NoLineWrappingForCodeMirror
name: NoLineWrappingForCodeMirror
version: 1.00
editors:
codemirror
config:
lineWrapping: ~