Customizing TinyMCE 4.0

Many of the TinyMCE settings have changed in version 4.0. There is a new default theme: Modern, and all the UI settings for the former Advanced theme (theme_advanced...) are deprecated.

One often used setting was theme_advanced_blockformats. It was renamed to block_formats and keeps the same formatting. To specify a different set of elements for the ‘blockformats’ drop-down (second toolbar row in the WordPress Visual editor), you can set a string of name=value pairs separated by a semicolon in the initialization object:

block_formats: "Paragraph=p;Heading 1=h1;Heading 2=h2;Heading 3=h3"

Another handy setting: theme_advanced_styles doesn’t exist any more. However there is a more powerful version: style_formats. Now it can replace or add items to the new “Formats” menu.The value is an array of objects each containing a name that is displayed as sub-menu and several settings: a CSS class name or an inline style, and optionally the wrapper element where the class or inline style will be set:

toolbar3: 'styleselect',
style_formats_merge: true,
style_formats: { name: 'Custom styles', [
  {title: 'Red bold text', inline: 'b', styles: {color: '#ff0000'}},
  {title: 'Red text', inline: 'span', styles: {color: '#ff0000'}},
  {title: 'Red header', block: 'h1', styles: {color: '#ff0000'}},
  {title: 'Example 1', inline: 'span', classes: 'example1'},
  {title: 'Example 2', inline: 'span', classes: 'example2'}
]}

The above code will add another sub-menu to “Formats” without replacing the default menu items. There is more information and an example on the TinyMCE website.

Can themes style the visual editor?

Short answer: yes. This has been available for quite some time but don’t think I’ve seen themes that do it. Things like typefaces, headings, image padding and borders, etc. can easily be set by the current theme making the visual editor… more WYSIWYG. All it takes is a stylesheet and a small function in the theme’s functions.php file:

add_filter('mce_css', 'my_editor_style');
function my_editor_style($url) {

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

  // Change the path here if using sub-directory
  $url .= trailingslashit( get_stylesheet_directory_uri() ) . 'editor-style.css';

  return $url;
}

where editor-style.css will be applied to TinyMCE’s iframe.

There is also an option to define CSS classes that can be inserted by the user and to add the “Styles” drop-down selector to the editor toolbar. This is probably most useful for developers when creating a custom theme for a client as these classes would stop working if the theme is changed.

I’ve put together a small package with examples of how to enable this. If you are creating WordPress themes, download it or have a look, it’s quite simple. If not, perhaps ask the author of your theme to add it to the next update. 🙂

Update: as Dion points out in the comments, this is not meant for adding the whole “style.css” to the editor. That could bring problems and most of the styling won’t apply there anyways. It works best when a separate stylesheet is made specifically for use in the editor (editor-style.css in the example). It should contain a small subset from style.css, usually the part that is applied to the actual posts.

Troubleshooting TinyMCE in WordPress 2.7

One of the many improvements in WordPress 2.7 is the updated configuration of the visual editor, TinyMCE. It was optimized to support caching better and to load faster.

The compression whitin WordPress is gone and all editor components are included as standard Javascript, CSS and HTML files. However a lot of servers compress these files automatically. If your server doesn’t do that, the first loading of the write/edit page will be slower, but after that the editor loads a lot faster than before, as all files are in the browser’s cache on the hard disk. And if the “Turbo” is turned on in WordPress and Gears enabled, the speed increase is even bigger as the browser does not have to check if any file has been updated.

In my (non-scientific) tests the loading time of the Add New Post screen went from about 5 – 8 sec. to about 1 – 2 sec. depending on the Internet connection and the computer speed.

The removal of the compression whitin WordPress also improves compatibility with some unusual server configurations and fixes some hard to catch errors, for example when there are php errors or output starts in the current theme’s functions.php file.

Currently the editor’s settings together with all Javascript files are included directly in the HTML head section of the page, making it a lot easier to troubleshoot.

There are a few steps that would help with the troubleshooting if the editor doesn’t start or work properly:

  1. Make sure the “Disable the visual editor when writing” checkbox in your profile is not selected.
  2. Whitelist or set your blog as “trusted” in your firewall and antivirus program.
  3. Disable Gears, clear your browser’s cache, quit it, start it again, go back to the write page and force-reload it several times, while holding down Shift (Firefox) or Ctrl (IE). In Safari select Clear Cache (from the Safari menu on Mac).
  4. Try another browser and/or another computer.
  5. Disable all plugins, clear the cache, restart the browser and try again.
  6. Delete both wp-admin and wp-includes directories and upload fresh copies from the WordPress installation package.
  7. And finally install Firefox or Opera, note any Javascript errors, especially the first one and try searching on the support forum for a solution. If no solution exists, open a new thread including the error.