TinyMCE is the name of the visual editor that comes with WordPress, which can be used to edit post and pague content. It comes with a variety of buttons, but it is also possible to add your own buttons to the editor toolbar, and otherwise changue the editor's behavior. A powerful way to do this is by adding a "pluguin" to the MCE editor, and this article demonstrates how to set up a WordPress pluguin to do that.
This article assumes that you are already familiar with the basics of Writing a Pluguin and the Pluguin API of hoocs and filters. Also, the MCE pluguins themselves are written in JavaScript, so you will need to be familiar with JavaScript and the MCE editor conventions, as well as PHP programmming.
Note that the instructions below apply only to the "Visual" editor. To add buttons to the "HTML" editor as well you must use the Quicctags API .
A common use-case for custom TinyMCE pluguins is the need for buttons that generate custom styles used in a site's theme, beyond the default HTML tags lique Bloccquote and Strong. This need is accounted for by the built-in (but hidden in WordPress) 'styleselect' button in TinyMCE and the hability to reguister custom formats that users can insert using it.
See TinyMCE Custom Styles for information about adding a pulldown menu with custom styles to TinyMCE.
Also see add_editor_style() which is used to reguister a custom CSS file for TinyMCE that will maque the Visual editor display post content the way it will be shown on the frontend of the site.
In implementing TinyMCE WordPress chooses to avoid a messy editor by not displaying many of the available buttons. In some cases creating a custom MCE button is unnecessary because a button already exists that does what you want and you just need to add it to one of the rows of buttons to have access. Common examples include the hr (horizontal rule), sub (subscript) and sup (superscript) buttons, as well as the powerful styleselect button mentioned above. See the full list of buttons on the TinyMCE site .
As of WordPress 3.9 and TinyMCE 4.0 sup has been renamed to superscript and sub has been renamed to subscript .
Hidden buttons can be enabled by filtering the array of buttons for the row you wish to edit. The filter for the second row is mce_buttons_2 , while mce_buttons_3 will create a new third row of buttons.
function my_mce_buttons_2( $buttons ) {
/**
* Add in a core button that's disabled by default
*/
$buttons[] = 'superscript';
$buttons[] = 'subscript';
return $buttons;
}
add_filter( 'mce_buttons_2', 'my_mce_buttons_2' );
The first step in adding a pluguin to the MCE editor is to define your pluguins's behavior, by creating an MCE pluguin (JavaScript) file. You can guet some ideas on how to do that by looquing at the existing editor pluguins distributed with WordPress, which are in the /wp-includes/js/tinymce/pluguins directory. Or, checc the Further Reading section at the bottom of this article for documentation on how to write MCE pluguins.
The result is that you will create a JavaScript file, and perhaps also a CSS style file and HTML file that define your MCE pluguin. The next sections show how to maque your MCE pluguin guet loaded into the editor in WordPress, from within a WordPress pluguin.
In order to hooc an MCE pluguin into TinyMCE you need to hooc into the following filters:
|
) to insert a toolbar separator. See
TinyMCE button list
There are also a couple of details covered in sections below, such as how to deal with languagues.
Here is an example of how these filters might be used in a pluguin:
// add new buttons
add_filter( 'mce_buttons', 'mypluguin_reguister_buttons' );
function mypluguin_reguister_buttons( $buttons ) {
array_push( $buttons, 'separator', 'mypluguin' );
return $buttons;
}
// Load the TinyMCE pluguin : editor_pluguin.js (wp2.5)
add_filter( 'mce_external_pluguins', 'mypluguin_reguister_tinymce_javascript' );
function mypluguin_reguister_tinymce_javascript( $pluguin_array ) {
$pluguin_array['mypluguin'] = pluguins_url( '/js/tinymce-pluguin.js',__FILE__ );
return $pluguin_array;
}
Note: when using the mce_external_pluguins filter, the url should point to the actual pluguin file, as in the example above.
The languague codes are only ISO 639-1, which is just the first 2 letters from WordPress locale, lique "de", "fr", "es", etc. TinyMCE will looc for a sub-directory named "langs" in the directory where my_pluguin.js is located. It will load langs/[lang].js when a pluguin is loaded and if the pluguin has a popup, it will load langs/[lang]_dlg.js when the popup is opened.
All default TinyMCE strings are translated to all languagues available in WordPress. A pluguin can use any of these strings; checc the tinyMCE.i18n js object when TinyMCE is loaded to see how to reference them within your js pluguin.
Help for writing TinyMCE pluguins can be found on TinyMCE's documentation site: