Blog

How to add Custom Editor Formats to WordPress Visual Editor

In this post you will learn how to add custom options to “Formats” drop-down in WordPress Visual Editor and what each of it’s parameters mean and how to configure editor styles to your theme.

 

Editor Styles vs Editor Formats

I think the WordPress documentation on these topics  is a bit confusing so let’s make it clearer. What are Editor StylesEditor Formats and WordPress Visual Editor.

WordPress Visual Editor: is the html editor that comes with WordPress, it’s an adapted version of TinyMCE Editor.

Editor Styles are the css styles we load into WordPress Visual Editor to make the content in the editor look like it would be in the real page, it gives the users a better experience editing posts and pages content.

WordPress Visual Editor without editor styles applied
This is how WordPress Visual Editor looks like without editor styles applied to it.

Editor Formats are custom styles you can apply to elements in your content selecting options in the Formats drop-down.

WordPress Visual Editor showing content with styles of Underskeleton Theme.
This is how WordPress Visual Editor looks like with editor styles loaded and the Formats drop-down opened.

 

Add Editor Styles to your theme

To configure editor styles to your theme you need to call the function add_editor_style() with the relative path to your editor-style.css or an array if you need to load more than one css file (see function’s documentation). If you call the function without any parameter, WordPress will look for a file called editor-style.css in the theme’s root directory.

You want to call the function hooking to the action admin_init so WordPress will load the editor styles only for the admin interface.

Add the code below to your theme’s functions.php file or change it at /inc/enqueue.php if you are using Underskeleton.

/**
 * Registers an editor stylesheet for the current theme.
 */
function underskeleton_add_editor_styles() {
 add_editor_style( 'css/editor-style.css' );
}
add_action( 'admin_init', 'underskeleton_add_editor_styles' );

IMPORTANT: As a best practice include only the necessary styles to properly show the content in your editor-style.css. Although, Underskeleton don’t follow this rule and also includes the theme.min.css with all it’s styles, this is about to change in the next release.

 

Enable Formats drop-down and add new options to it

Now that we have our editor styles configured and can see our themes style in the editor let’s enable the Formats drop-down and add our custom options to it.

Enable formats drop-down

Add the code below to your theme’s functions.php file or change it at /inc/editor-formats.php if you are using Underskeleton.

/*
* Enable Editor Formats drop-down
*/
function underskeleton_mce_buttons_2( $buttons ) {
 array_unshift($buttons, 'styleselect');
 return $buttons;
}
add_filter('mce_buttons_2', 'underskeleton_mce_buttons_2');

Now the WordPress Visual Editor should look like this with default formats from TinyMCE:

Add your own options to Formats drop-down

Before start creating your own formats, let’s take a look at the options we have:

Name Summary
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.

More information about the parameters and options you can use in your formats at TinyMCE Documentation.

Adding your own options

Add the code below to your theme’s functions.php file or change it at /inc/editor-formats.php if you are using Underskeleton.

/*
* Callback function to filter the MCE settings
*/
function underskeleton_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
  * Notice that each array has title, block or inline, classes, styles and wrapper arguments
  * Title is the label which will be visible in Formats menu
  * Block defines whether it is a span, div, selector, or inline style
  * Inline defines which element will be used to wrap the inline styles
  * Classes allows you to define CSS classes to be used
  * Styles allows you to define inline css properties to be used
  * Wrapper whether or not to add a new block-level element around any selected elements
  * Items allows you create a tree of options
  */
    array(
      'title' => __('Light Grey Block', 'underskeleton'),
      'block' => 'div',
      'classes' => 'light-grey-background block-spacing',
      'wrapper' => true,
    ),
    array(
      'title' => __('Button', 'underskeleton'),
      'inline' => 'a',
      'classes' => 'button',
    ),
    array(
      'title' => __('Red header', 'underskeleton'),
      'block' => 'h1',
      'styles' => array(
        'color'         => 'red', // or hex value #ff0000
        'fontWeight'    => 'bold',
        'textTransform' => 'uppercase'
      ),
    ),
  );  
  // Insert the array, JSON ENCODED, into 'style_formats'
  $init_array['style_formats'] = json_encode( $style_formats );
  
  return $init_array;
} 
add_filter( 'tiny_mce_before_init', 'underskeleton_mce_before_init_insert_formats' );

Result:

Enhance your formats drop-down with a tree of options

You can also create a tree of options to group similar options like different styles of buttons:

/*
* Callback function to filter the MCE settings
*/
function underskeleton_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
  * Notice that each array has title, block or inline, classes, styles and wrapper arguments
  * Title is the label which will be visible in Formats menu
  * Block defines whether it is a span, div, selector, or inline style
  * Inline defines which element will be used to wrap the inline styles
  * Classes allows you to define CSS classes to be used
  * Styles allows you to define inline css properties to be used
  * Wrapper whether or not to add a new block-level element around any selected elements
  */
    array(
      'title' => __('Light Grey Block', 'underskeleton'),
      'block' => 'div',
      'classes' => 'light-grey-background block-spacing',
      'wrapper' => true,
    ),
    array(
      'title' => __('Red header', 'underskeleton'),
      'block' => 'h1',
      'styles' => array(
        'color'         => 'red', // or hex value #ff0000
        'fontWeight'    => 'bold',
        'textTransform' => 'uppercase'
      ),
    ),
    array(
      'title' => __('Buttons', 'underskeleton'),
      'items' => array (
        array(
          'title' => __('Default Color', 'underskeleton'),
          'inline' => 'a',
          'classes' => 'button',
        ),
        array(
          'title' => __('Medium Size', 'underskeleton'),
          'inline' => 'a',
          'classes' => 'button secondary-background',
        ),
        array(
          'title' => __('Large Size', 'underskeleton'),
          'inline' => 'a',
          'classes' => 'button tertiary-background',
        ),
      ),
    ),
  );  
  // Insert the array, JSON ENCODED, into 'style_formats'
  $init_array['style_formats'] = json_encode( $style_formats );
  
  return $init_array;
} 
add_filter( 'tiny_mce_before_init', 'underskeleton_mce_before_init_insert_formats' );

Result:

 

Final solution: add editor formats to your theme

PHP

/*
* Enable Editor Formats drop-down
*/
function underskeleton_mce_buttons_2( $buttons ) {
 array_unshift($buttons, 'styleselect');
 return $buttons;
}
add_filter('mce_buttons_2', 'underskeleton_mce_buttons_2');



/*
* Callback function to filter the MCE settings
*/
function underskeleton_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
 * Notice that each array has title, block or inline, classes, styles and wrapper arguments
 * Title is the label which will be visible in Formats menu
 * Block defines whether it is a span, div, selector, or inline style
 * Inline defines which element will be used to wrap the inline styles
 * Classes allows you to define CSS classes to be used
 * Styles allows you to define inline css properties to be used
 * Wrapper whether or not to add a new block-level element around any selected elements
 */
 array(
 'title' => __('Light Grey Block', 'underskeleton'),
 'block' => 'div',
 'classes' => 'light-grey-background block-spacing',
 'wrapper' => true,
 ),
 array(
 'title' => __('Red header', 'underskeleton'),
 'block' => 'h1',
 'styles' => array(
 'color' => 'red', // or hex value #ff0000
 'fontWeight' => 'bold',
 'textTransform' => 'uppercase'
 ),
 ),
 array(
 'title' => __('Buttons', 'underskeleton'),
 'items' => array (
 array(
 'title' => __('Default Color', 'underskeleton'),
 'inline' => 'a',
 'classes' => 'button',
 ),
 array(
 'title' => __('Medium Size', 'underskeleton'),
 'inline' => 'a',
 'classes' => 'button secondary-background',
 ),
 array(
 'title' => __('Large Size', 'underskeleton'),
 'inline' => 'a',
 'classes' => 'button tertiary-background',
 ),
 ),
 ),
 ); 
 // Insert the array, JSON ENCODED, into 'style_formats'
 $init_array['style_formats'] = json_encode( $style_formats );
 
 return $init_array;
} 
add_filter( 'tiny_mce_before_init', 'underskeleton_mce_before_init_insert_formats' );

 

CSS

Don’t forget to add your formats CSS code to editor-style.css and your front-end css file.

// BLOCKS
.light-grey-background { background-color: #e1e1e1; }
.block-spacing { padding: 2rem; }
.primary-background { background-color: #d72d5c; }
.secondary-background { background-color: #155d4f; }
.tertiary-background { background-color: #f4da7a; }

// BUTTONS
.button {
 display: inline-block;
 padding: 0 30px;
 color: #155d4f;
 text-align: center;
 text-transform: uppercase;
 background-color: transparent;
 border-radius: 4px;
 border: 1px solid #bbb;
 cursor: pointer;
}

 

Conclusion

WordPress Visual Editor allows us to create new format options to give our theme’s users more flexibility to write and style great content on their website.

Underskeleton has built-in editor formats and many modifiers css classes you can use in your website or extend if creating your theme based on it.

Documentation on the options available in Underskeleton is coming soon.

References

  1. WordPress documentation on TinyMCE Custom Styles: https://codex.wordpress.org/TinyMCE_Custom_Styles
  2. TinyMCE documentation: https://www.tinymce.com/docs/configure/content-formatting/#formats