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 for standard HTML tags like Strong, Emphasis, Blockquote and Lists. In addition to these defaults, TinyMCE has an API that can be used to define custom styles that can be inserted into post content from the Visual editor.
The process involves activating a built-in but hidden "button" in TinyMCE called styleselect, then defining each style that you want to show in the Styleselect pulldown menu. This article assumes that you are already familiar with the basics of Writing a Plugin and the Plugin API of hooks and filters.
Note that the process for adding custom styles is separate from creating custom TinyMCE buttons and that this process will not make the Visual editor display post content with your custom styles, for that you must use add_editor_style().
Also note that the instructions below apply only to the Visual editor. To add buttons to the Text editor as well you must use the Quicktags API.
Whenever possible, style related code should be in the theme in which the styles are implemented. The most natural location is the [functions.php] file, though of course the filters could also be added in a plugin if desired.
Before any registered formats/styles will show, we need to activate the styleselect pulldown menu in the Visual editor. We do this by filtering the array of buttons loaded by TinyMCE. We use the mce_buttons_2 filter because that is the second row and it looks good there. You could instead use mce_buttons_3 which would add it to an empty third row.
// Callback function to insert 'styleselect' into the $buttons array
function my_mce_buttons_2( $buttons ) {
array_unshift( $buttons, 'styleselect' );
return $buttons;
}
// Register our callback to the appropriate filter
add_filter( 'mce_buttons_2', 'my_mce_buttons_2' );
Once styleselect is in place we can register our actual styles in two different ways. Both involve using the tiny_mce_before_init filter, which receives the full configuration parameters of TinyMCE and into which we'll inject our custom styles.
The more robust solution is to use the style_formats array within the TinyMCE configuration array. It allows you to register each format along with several configuration settings that define how the format will behave, for example whether it is a block or inline style, and whether it should change the outer block element or not.
// Callback function to filter the MCE settings
function my_mce_before_init_insert_formats( $init_array ) {
// Define the style_formats array
$style_formats = array(
// Each array child is a format with it's own settings
array(
'title' => '.translation',
'block' => 'blockquote',
'classes' => 'translation',
'wrapper' => true,
),
array(
'title' => '⇠.rtl',
'block' => 'blockquote',
'classes' => 'rtl',
'wrapper' => true,
),
array(
'title' => '.ltr⇢',
'block' => 'blockquote',
'classes' => 'ltr',
'wrapper' => true,
),
);
// Insert the array, JSON ENCODED, into 'style_formats'
$init_array['style_formats'] = wp_json_encode( $style_formats );
return $init_array;
}
// Attach callback to 'tiny_mce_before_init'
add_filter( 'tiny_mce_before_init', 'my_mce_before_init_insert_formats' );
More information about the format options is available on the TinyMCE formats documentation.
Note: The visual editor's behavior when using custom styles, especially depending on the settings outlined above, can be surprising and seemingly random. Please test carefully how the buttons work with your configuration and ensure your users understand what to expect.
The simplest possible way to add formats is to insert a string containing your styles in a special format to the theme_advanced_styles section of the TinyMCE configuration array. The format is $label=$cssclassname; so in the following example we'd be adding .translation, .contributors and .notes to styleselect:
Translation Class=translation;Contributors=contributors;Extra Notes=notes
Unlike the style_formats solution, this one does not allow you to set configuration options, so it should only be used for inline styles (the default).
Filter usage is very similar to above:
function my_mce_before_init( $init_array ) {
$init_array['theme_advanced_styles'] =
'.translation=translation;.contributors=contributors;.notes=notes;';
return $init_array;
}
add_filter( 'tiny_mce_before_init', 'my_mce_before_init' );
The code above will only enable the styleselect dropdown menu and add your styles inside it. By default the Visual editor won't know how to display your styles as a preview. Luckily you can provide a custom CSS stylesheet for the editor that includes your styles.
If you are adding custom styles to TinyMCE, always ensure they are accounted for in the editor CSS! See add_editor_style() for instructions on registering an editor CSS file.
Help for writing TinyMCE plugins can be found on TinyMCE's documentation site: