WordPress:TinyMCE Custom Buttons

Introduction

TinyMCE is the name of the visual editor that comes with WordPress, which can be used to edit post and page content. It comes with a variety of buttons, but it is also possible to add your own buttons to the editor toolbar, and otherwise change the editor's behavior. This is done by adding a "plugin" to the MCE editor, and this article demonstrates how to set up a WordPress plugin to do that.

This article assumes that you are already familiar with the basics of WordPress:Writing a Plugin and the WordPress:Plugin API of hooks and filters. Also, the MCE plugins themselves are written in JavaScript, so you will need to be familiar with JavaScript and the MCE editor conventions, as well as PHP programming.

Note: TinyMCE was upgraded from version 2 in WordPress 2.1 to 2.3, to version 3 in WordPress 2.5. So, the techniques for adding buttons have changed accordingly; see below.

Creating an MCE Editor Plugin

The first step in adding a plugin to the MCE editor is to define your plugins's behavior, by creating an MCE plugin (JavaScript) file. You can get some ideas on how to do that by looking at the existing editor plugins distributed with WordPress, which are in the /wp-includes/js/tinymce/plugins directory. Or, check the Further Reading section at the bottom of this article for documentation on how to write MCE plugins.

The result is that you will create a JavaScript file, and perhaps also a CSS style file and HTML file that define your MCE plugin. The next sections show how to make your MCE plugin get loaded into the editor in WordPress, from within a WordPress plugin.

Loading a TinyMCE 2 Plugin (Wordpress 2.1.x - 2.3.x)

In order to hook an MCE plugin into TinyMCE 2 (which is the MCE version present in WordPress 2.1 through 2.3), you need to hook into several filters and actions:

mce_plugins
mce_css
mce_buttons
tinymce_before_init

Here is an example of how to hook into these filters and actions:

function &my_plugin(&$plugins) {
  $plugins[] = "-my_plugin"; // the leading "-" means it's an external plugin
   return $plugins;
}
 
function my_plugin_css($css) {
  return $css . "," . MY_WEB_PREFIX . "/tinymce/my_plugin/content.css";
}
 
function &my_plugin_button(&$buttons) {
  $buttons[] = "separator";
  $buttons[] = "my_plugin";
  return $buttons;
}
 
function my_plugin_load() {
  echo "tinyMCE.loadPlugin('my_plugin', '" . MY_WEB_PREFIX . "/tinymce/my_plugin');\n";
}
 
add_filter("mce_plugins", "my_plugin");
add_filter("mce_css", "my_plugin_css");
add_filter("mce_buttons", "my_plugin_button");
add_action("tinymce_before_init", "my_plugin_load");

Loading a TinyMCE 3 Plugin (Wordpress 2.5)

In order to hook an MCE plugin into TinyMCE 3 (which is the MCE version present in WordPress 2.5), you need to hook into the following filters:

mce_buttons: passes in/out a php array with the button names; "|" can be used as separator.
mce_external_plugins: passes in/out an associative php array 'plugin_name' => 'plugin_url'. The url should be absolute and on the same domain as your WordPress installation.

There are also a couple of details covered in sections below, such as how to deal with languages.

Here is an example of how to use these filters:

function myplugin_addbuttons() {
   // Don't bother doing this stuff if the current user lacks permissions
   if ( ! current_user_can('edit_posts') && ! current_user_can('edit_pages') )
     return;
 
   // Add only in Rich Editor mode
   if ( get_user_option('rich_editing') == 'true') {
     add_filter("mce_external_plugins", "add_myplugin_tinymce_plugin");
     add_filter('mce_buttons', 'register_myplugin_button');
   }
}
 
function register_myplugin_button($buttons) {
   array_push($buttons, "separator", "myplugin");
   return $buttons;
}
 
// Load the TinyMCE plugin : editor_plugin.js (wp2.5)
function add_myplugin_tinymce_plugin($plugin_array) {
   $plugin_array['myplugin'] = URLPATH.'tinymce/editor_plugin.js';
   return $plugin_array;
}
 
// init process for button control
add_action('init', 'myplugin_addbuttons');

Note: when using the mce_external_plugins filter, the url should point to the actual plugin file, as in the example above. For TinyMCE 2.x it points to the directory containing the file.

Loading language files

In TinyMCE 3, the language codes are only ISO 639-1, which is just the first 2 letters from WordPress locale, like "de", "fr", "es", etc. TinyMCE will look for a sub-directory named "langs" in the directory where my_plugin.js is located. It will load langs/[lang].js when a plugin is loaded and if the plugin has a popup, it will load langs/[lang]_dlg.js when the popup is opened.

All default TinyMCE strings are translated to all languages available in WordPress. A plugin can use any of these strings; check the tinyMCE.i18n js object when TinyMCE is loaded to see how to reference them within your js plugin.

Other changes for TinyMCE 3

The action "mce_options" is still supported, but deprecated. The action "tinymce_before_init" is replaced by a filter "tiny_mce_before_init". It passes an associative php array with all TinyMCE settings, including the output from the other filters and can be used in place of mce_options.

The zipped file containing TinyMCE plus all default plugins is cached on disk to save some memory/server resources. This cache is invalidated by any change to the init array or by changing the ver=[number] argument when calling tiny_mce_config.

The filter "tiny_mce_version" passes the version number as a string. It can easily be changed several times by different plugins. All of these will work:

function my_refresh_mce($ver) {
  $ver += 3; // or $ver .= 3; or ++$ver; etc.
  return $ver;
}
add_filter('tiny_mce_version', 'my_refresh_mce');

The compression, caching and number of different cached files to keep can be changed with tiny_mce_before_init, examples:

function my_change_mce_settings( $init_array ) {
    $init_array['disk_cache'] = false; // disable caching
    $init_array['compress'] = false; // disable gzip compression
    $init_array['old_cache_max'] = 3; // keep 3 different TinyMCE configurations cached (when switching between several configurations regularly)
}
 
add_filter( 'tiny_mce_before_init', 'my_change_mce_settings' );

WIKI使用导航

站长百科导航

站长专题