Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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.
This document will focus on explaining how to expand the Rich Text Editor with config.yaml.
Setting up 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.
Writing For config.yaml
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
Things to be aware of when using config.yaml
With config.yaml, developers can easily create plugins with very simple code, however there are a few things to keep in mind.
You must replace false with “~”
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.)
Overwriting, not adding
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
Expanding other editors through config.yaml
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: ~