Adding Custom Styles in WordPress TinyMCE Editor

If you are creating a WordPress theme to power a website that will be updated by individuals without any knowledge of HTML, you can add custom styles to the visual TinyMCE editor and ensure that elements are properly formatted.

As a web designer or developer, you can create custom styles for various elements in the content of a WordPress website. These styles can be easily added by editing the HTML. What if the end-user or author of the website is not familiar with HTML? What if the author forgot which element was required for the desired style?

Adding custom styles to the WYSIWYG editor (TinyMCE) interface will allow the user to style an element with appropriate custom CSS without having to remember any code. Simply select the element or text and apply the relevant format using the style dropdown menu available in the visual editor. It is fairly easy to add a ‘Styles’ dropdown to the ‘Kitchen Sink’ in WordPress. Adding custom styles to the visual editor in WordPress is perfect for adding elements such as warning messages, buttons and testimonials.

Note: Below we’ll be creating variations of some open source code called TinyMCE Kit from the WordPress plugin repository which is released under the GPL v.2 license.

Quick Fix

Adding custom styles to the TinyMCE editor in WordPress is a fairly easy process. Below is a simple plug-in that adds custom styles mentioned in an array class to the visual editor in the ‘Styles’ drop-down. The CSS styles are placed in a file in the plug-in folder. This CSS stylesheet is called in the visual editor as well as the front-end of the website.

The code has been commented to make it easy to understand. In the first part, we make use of a TinyMCE function to add the custom stylesheet to the visual editor so that all styles are visible there. The next part adds the ‘Styles’ drop-down, which is populated in the subsequent step. The ‘Styles’ dropdown ('styleselect') is added to the second row of buttons (theme_advanced_buttons2_add) at the beginning of the row (_before). This drop-down is then populated with custom styles, which are added through the $classes array instead of writing directly in the format prescribed in the TinyMCE documentation. In the final part, the custom stylesheet is added to the front-end using the wp_enqueue_scripts function.

<?php
/*
Plugin Name: Custom Quick Styles
Plugin URI: http://www.speckygeek.com
Description: Add custom styles in your posts and pages content using TinyMCE WYSIWYG editor. The plugin adds a Styles dropdown menu in the visual post editor.
Based on TinyMCE Kit plug-in for WordPress

http://plugins.svn.wordpress.org/tinymce-advanced/branches/tinymce-kit/tinymce-kit.php

*/
/**
 * Apply styles to the visual editor
 */  
add_filter('mce_css', 'tuts_mcekit_editor_style');
function tuts_mcekit_editor_style($url) {

    if ( !empty($url) )
        $url .= ',';

    // Retrieves the plugin directory URL and adds editor stylesheet
    // Change the path here if using different directories
    $url .= trailingslashit( plugin_dir_url(__FILE__) ) . '/editor-styles.css';

    return $url;
}

/**
 * Add "Styles" drop-down
 */  
function tuts_mcekit_editor_buttons($buttons) {
    array_unshift($buttons, 'styleselect');
    return $buttons;
}

add_filter('mce_buttons_2', 'tuts_mcekit_editor_buttons');

/**
 * Add "Styles" drop-down content or classes
 */  
function tuts_mcekit_editor_settings($settings) {
    if (!empty($settings['theme_advanced_styles']))
        $settings['theme_advanced_styles'] .= ';';    
    else
        $settings['theme_advanced_styles'] = '';

    /**
     * Add styles in $classes array.
     * The format for this setting is "Name to display=class-name;".
     * More info: http://wiki.moxiecode.com/index.php/TinyMCE:Configuration/theme_advanced_styles
     *
     * To be allow translation of the class names, these can be set in a PHP array (to keep them
     * readable) and then converted to TinyMCE's format. You will need to replace 'textdomain' with
     * your theme's textdomain.
     */
    $classes = array(
        __('Warning','textdomain') => 'warning',
        __('Notice','textdomain') => 'notice',
        __('Download','textdomain') => 'download',
        __('Testimonial','textdomain') => 'testimonial box',
    );

    $class_settings = '';
    foreach ( $classes as $name => $value )
        $class_settings .= "{$name}={$value};";

    $settings['theme_advanced_styles'] .= trim($class_settings, '; ');
    return $settings;
} 

add_filter('tiny_mce_before_init', 'tuts_mcekit_editor_settings');

/*
 * Add custom stylesheet to the website front-end with hook 'wp_enqueue_scripts'
 * Enqueue the custom stylesheet in the front-end
 */
add_action('wp_enqueue_scripts', 'tuts_mcekit_editor_enqueue');
function tuts_mcekit_editor_enqueue() {
  $StyleUrl = plugin_dir_url(__FILE__).'editor-styles.css';
  wp_enqueue_style( 'myCustomStyles', $StyleUrl );
}
?>

Elaborate Styling

The above solution for adding custom styles to the WordPress visual editor is quick, but it has some limitations. The above code will not limit a style to a specific HTML element. It will also not apply a class to an existing block element.

We can remove these limitations and make our custom styles drop-down more powerful by putting the styles in arrays using TinyMCE syntax to define the formats. After this, we encode the styles as JSON and then add them to the TinyMCE settings. The rest of the plug-in codes remain unchanged.

In TinyMCE, each format has a set of parameters that you can specify. (Source: TinyMCE – formats)

• inline – Name of the inline element to produce for example “span”. The current text selection will be wrapped in this inline element.
• block – Name of the block element to produce for example “h1″. Existing block elements within the selection gets replaced with the new block element.
• selector – CSS 3 selector pattern to find elements within the selection by. This can be used to apply classes to specific elements or complex things like odd rows in a table.
• classes – Space separated list of classes to apply the the selected elements or the new inline/block element.
• styles – Name/value object with CSS style items to apply such as color etc.
• attributes – Name/value object with attributes to apply to the selected elements or the new inline/block element.
• exact – Disables the merge similar styles feature when used. This is needed for some CSS inheritance issues such as text-decoration for underline/strikethough.
• wrapper – State that tells that the current format is a container format for block elements. For example a div wrapper or blockquote.

Here is the modified plug-in for adding custom styles to the WordPress visual editor.

<?php
/*
Plugin Name: Custom Styles
Plugin URI: http://www.speckygeek.com
Description: Add custom styles in your posts and pages content using TinyMCE WYSIWYG editor. The plugin adds a Styles dropdown menu in the visual post editor.
Based on TinyMCE Kit plug-in for WordPress

http://plugins.svn.wordpress.org/tinymce-advanced/branches/tinymce-kit/tinymce-kit.php

*/
/**
 * Apply styles to the visual editor
 */  
add_filter('mce_css', 'tuts_mcekit_editor_style');
function tuts_mcekit_editor_style($url) {

    if ( !empty($url) )
        $url .= ',';

    // Retrieves the plugin directory URL
    // Change the path here if using different directories
    $url .= trailingslashit( plugin_dir_url(__FILE__) ) . '/editor-styles.css';

    return $url;
}

/**
 * Add "Styles" drop-down
 */ 
add_filter( 'mce_buttons_2', 'tuts_mce_editor_buttons' );

function tuts_mce_editor_buttons( $buttons ) {
    array_unshift( $buttons, 'styleselect' );
    return $buttons;
}

/**
 * Add styles/classes to the "Styles" drop-down
 */ 
add_filter( 'tiny_mce_before_init', 'tuts_mce_before_init' );

function tuts_mce_before_init( $settings ) {

    $style_formats = array(
        array(
            'title' => 'Download Link',
            'selector' => 'a',
            'classes' => 'download'
            ),
        array(
            'title' => 'Testimonial',
            'selector' => 'p',
            'classes' => 'testimonial',
        ),
        array(
            'title' => 'Warning Box',
            'block' => 'div',
            'classes' => 'warning box',
            'wrapper' => true
        ),
        array(
            'title' => 'Red Uppercase Text',
            'inline' => 'span',
            'styles' => array(
                'color' => '#ff0000',
                'fontWeight' => 'bold',
                'textTransform' => 'uppercase'
            )
        )
    );

    $settings['style_formats'] = json_encode( $style_formats );

    return $settings;

}

/* Learn TinyMCE style format options at http://www.tinymce.com/wiki.php/Configuration:formats */

/*
 * Add custom stylesheet to the website front-end with hook 'wp_enqueue_scripts'
 */
add_action('wp_enqueue_scripts', 'tuts_mcekit_editor_enqueue');

/*
 * Enqueue stylesheet, if it exists.
 */
function tuts_mcekit_editor_enqueue() {
  $StyleUrl = plugin_dir_url(__FILE__).'editor-styles.css'; // Customstyle.css is relative to the current file
  wp_enqueue_style( 'myCustomStyles', $StyleUrl );
}
?>

So you have an plug-in to add custom styles in the WordPress visual editor. To add your own styles, you need to replace the existing style formats array with your own. Of course, you will have to add the styles to the stylesheet in the plug-in directory as well. If you need to use any image as background, you can create an image folder and reference the background image from there.

If you wish to use this in your theme, just add the plug-in code to the theme’s functions.php. Make sure to replace plugin_dir_url(__FILE__) with get_stylesheet_directory_uri() and reference the appropriate stylesheet from the theme folder.

Conclusion

Creative use of custom styles in the visual editor will make formatting the articles/posts and pages easier and a lot more fun. It will also make it easy for your clients to manage their websites and add life to it by including visually exciting content. By adding theme options, you can extend this plug-in so that the user can create their own custom styles for use in the visual editor.

All the best! Let us know in the comments how you would use this code and how you would extend it in your own usage.