Editor API changes in 4.8

A new editor API was added in #35760. It makes it possible to dynamically instantiate the editor from JS. There are two parts to it:

  • All editor related scripts and stylesheets have to be enqueued from PHP by using wp_enqueue_editor().
  • Initialization is left for the script that is adding the editor instance. It requires the textarea that will become the Text editor tab to be already created and not hidden in the DOM. Filtering of the settings is done on adding the editor instance from JS.

There are three new methods added to the wp.editor namespace:

  • wp.editor.initialize()
  • wp.editor.remove()
  • wp.editor.getContent()

(See wp-admin/js/editor.js for more info.)

The default WordPress settings are passed to the initialize() method automatically, and can be overridden by passing a settings object on initialization, similarly to using wp_editor() in PHP.

In addition there are several custom jQuery events that are fired at different stages during initialization:

  • wp-before-tinymce-init is fired before initialization and can be used to set or change any editor setting. It passes the settings object.
  • tinymce-editor-setup is fired after initialization has started but before the UI is constructed. It passes the editor instance object.
  • tinymce-editor-init is fired when the TinyMCE instance is ready (same as the init event in TinyMCE).

Here’s an example of how to add few of the default TinyMCE buttons to the toolbar:

jQuery( document ).on( 'tinymce-editor-setup', function( event, editor ) {
	editor.settings.toolbar1 += ',alignleft,aligncenter,alignright';
});

Here is another example of how to add a custom button:

jQuery( document ).on( 'tinymce-editor-setup', function( event, editor ) {
	editor.settings.toolbar1 += ',mybutton';

	editor.addButton( 'mybutton', {
		text: 'My button2',
		icon: false,
		onclick: function () {
			editor.insertContent("It's my button!");
		}
	});
});

For more information please see the TinyMCE documentation.

Update: there were four “private event hacks” in the default imageplugin left over from the initial TinyMCE 4.0 implementation back in WordPress 3.9. These hacks were also removed as that plugin has changed significantly in the latest TinyMCE version.

#4-8, #editor, #tinymce

Dev Chat Summary: May 10th (4.8 week 2)

This post summarizes the dev chat meeting from May 10th (agendaSlack archive).

4.8 Timing

  • Reminder of Beta 1 on Friday, the complete 4.8 schedule is on Make/Core
  • At this point we’re not trying to get anything in 4.8 besides the core media widgets, dashboard news upgrade, and the next version of TinyMCE (4.6.0)
  • Merge deadline goal to have the target features today (Wednesday, May 10th), and things generally closing on Friday, May 12th
  • Friday 8 PM UTC as pencils down and the beta packaging process / release to happen
  • We’ll schedule a post hoc debrief on our workflows to be more like Chrome, with frequent, major, auto-updates

4.8 Bug Scrubs

4.8 Dev Notes / Field Guide

  • Target to post Dev Notes shortly so they can be combined, published in, and communicated with the Field Guide when the Release Candidate ships around May 25th
  • Updated listing of Dev Notes needed and those responsible:
  • Per the Releasing Major Versions page, we should aim for Dev Notes around Beta 1 so let’s call that sometime next week as current focus is on actually getting to commit for Beta 1 this week

Customize, Editor, and REST API Updates

  • Customize: A general heads up to theme authors to please test the core medias widgets for compatibility issues. The sooner issues are identified the better to get them resolved before 4.8 ships.
  • Editor: They hope to tag a first pre-alpha release of the plugin this week, so keep your radars scanning for that notification to jump in to test and provide feedback there. If you’re curious how they’re building out the foundation of Gutenberg, then read “Editor: How Little Blocks Work“.
  • REST API: They would greatly appreciate any and all feedback on #38323, especially those of you familiar with meta. This isn’t crucial for 4.8, is crucial for many use cases and any help getting this into an upcoming release would be great.

#4-8, #core-customize, #core-editor, #core-restapi, #dev-chat, #media-widgets, #summary, #tinymce

Editor changes in 4.7

There are a few noteworthy changes to the editor in WordPress 4.7.

Some of the toolbar buttons have been rearranged to make them easier to access and to encourage proper use of the HTML elements they insert.  The headings drop down is now moved to the top row, and the strike-through and horizontal rule button are moved down. This also reflects their usage.

The underline and justify buttons have been removed from the bottom row. Underlining is a bad practice as readers can confuse it with links (bad accessibility), and it does not insert a semantic element. Justifying has uneven browser implementation, and in many cases is bad for readability. Keyboard shortcuts for both will keep working.

For more information see #27159 that also has links to the discussions in Slack.

Labels for keyboard shortcuts have been added to the tooltips for buttons and inside drop downs to make them easier to discover.

As always, feedback is welcome.

Ella and Andrew

#4-7, #dev-notes, #editor, #tinymce

Editor changes in 4.6

In WordPress 4.6 TinyMCE is upgraded from version 4.3.10 to 4.4.1. There are numerous bug fixes and several new features, most notably a new inline theme (changelog).

The wpview editor plugin (that is responsible for showing gallery, video, audio, and oEmbed previews) was updated to use the TinyMCE API for non-editable elements. This brought some small changes and improvements in the UI, for example “views” are draggable now. On the back-end the wp-mce-view-unbind event was removed as it doesn’t exist in the API. It was intended for cleanup/unloading but was never very reliable. If a plugin needs to unload instance dependent scripts, it can use mutation observer to monitor when the view node is deleted. See #36434 for more information.

wpview remains an experimental API, though with each iteration it is getting closer to being finalized. As an experimental API, breaking changes are expected. As always, please test your plugin now if it modifies or depends on the editor, especially if you use experimental features like wpview.

#4-6, #dev-notes, #editor, #media, #tinymce

Editor changes in WordPress 4.3

The editor initialization was updated. The main change is that the content for both Visual and Text editors is prepared/escaped the same. We used to run the content through the PHP wpautop() when the default editor was TinyMCE. This is no longer needed as we run the textarea content through the JavaScript wpautop() before initializing TinyMCE.

In that terms wp_richedit_pre() and wp_htmledit_pre() were deprecated together with the richedit_pre and htmledit_pre filters. They were replaced by format_for_editor() and the format_for_editor filter. For more information see #32425.

Another change is the complete removal of the code for the old Distraction Free Writing mode. This code was disabled and has been unused since WordPress 4.1. We left it in core so the authors of plugins that were using it would have plenty of time to update.

If this is essential for some plugins, the files from WordPress 4.2 can be reused. For more information see #30949.

If you are the author of a plugin that uses any of the deprecated functions or filters, please update it now. If your plugin uses wp_editor(), please test it in the latest beta.

As always, feedback is very welcome.

#4-3, #dev-notes, #editor, #tinymce

Plupload 2.x in WordPress 3.9

Plupload is the library that powers most of the file upload interfaces in WordPress, and in 3.9 we’ve updated the bundled library to version 2.1.1 (#25663). Here are some of things that have changed, which may affect WordPress plugins and themes.

If you’re using direct references to Plupload’s runtime .js files, such as plupload.html5.js, note that these files are now gone. The following script handles were removed: plupload-html5, plupload-flash, plupload-silverlight and plupload-html4. If you need to enqueue the Plupload library, just use the plupload handle.

If you’re constructing your own Plupload settings array vs. using wp_plupload_default_settings() and/or the _wpPluploadSettings object, note that some of the arguments have changed, most notably:

  • flash_swf_url should point to the new Moxie.swf file (See update)
  • Similarly, silverlight_xap_url should use the new Moxie.xap (See update)
  • The multiple_queues argument is no longer used
  • The max_file_size key has been moved to the filters array
  • The filters array now supports multiple keys, and the list of file types array has been moved to its mime_types key

To illustrate that with code:

$settings = array(
    // ...
    'flash_swf_url' => includes_url( 'js/plupload/plupload.flash.swf' ), // Unchanged
    'silverlight_xap_url' => includes_url( 'js/plupload/plupload.silverlight.xap' ), // Unchanged
    'filters' => array( 
        'max_file_size' => $max_upload_size . 'b', 
    ),
);

Plupload version 2.1.1 has also added some exciting new options and methods, which you can find in the updated documentation.

As a result of this update in WordPress 3.9 we were able to add drag and drop upload support directly to our TinyMCE editor (#19845), and we’ve also added a new boolean flag to wp_editor(), which you can use to enable drag and drop upload support in your own instance of the editor (#27465):

wp_editor( '', 'my-editor', array(
    // ...
    'drag_drop_upload' => true,
) );

If you run into any problems with this update in 3.9, please leave a comment on this post and we’ll be happy to help you out!

Update: I opened #27763 to address some of the compatibility issues around the update. We might be renaming the swf/xap files for backwards compatibility.

Update, April 13: The original swf/xap filenames were restored.

#3-9, #dev-notes, #editor, #tinymce

TinyMCE 4.0 requires text/css for editor style files

As of TinyMCE 4.0, the visual editor iframe now has an HTML5 document type (<!DOCTYPE html>). In this scenario, CSS files must be served with the text/css content type. A server will serve a *.css file with the proper content type, but if you’re using a PHP file for an editor style file, you need to be the one to do it. It’s as simple as leading with:

<?php
header( 'Content-Type: text/css; charset=UTF-8' );

So if you’re doing something particularly crazy with the editor and your styles aren’t loading in WordPress 3.9, you may just need a content type. Also, Chrome (and probably other browsers) throw a console warning when this happens.

(via #27288)

#3-9, #dev-notes, #editor, #tinymce

TinyMCE 4.0 is in core

This is a major upgrade for the WordPress editor. There are many changes in 4.0:

  • New UI and UI API.
  • New theme.
  • Revamped events system/API.
  • Better code quality, readability and build process.
  • Lots of (inline) documentation.
  • And generally many improvements everywhere.

All default TinyMCE plugins have been upgraded. The WordPress implementation custom plugins  were upgraded too. Looking in the plugin repository, there are a lot of WordPress plugins  that add a TinyMCE plugin. Because of all the API changes, most of these plugins would need an update too. If you are the author of such plugin, please test it in trunk now.

Generally there are three groups of TinyMCE plugins added by WordPress plugins:

  • Custom plugin created specifically for the WordPress plugin. If you’ve developed this kind of plugin, please see the 3.x to 4.0 migration guide and the 4.0 API documentation.
  • WordPress plugins that add third-party or default TinyMCE plugins would (of course) need to be updated to include the 4.0 version of the plugin. The PHP global $tinymce_version can be used to determine which plugin to load.
  • Mini-plugins that only add a button to the toolbar. This works pretty much the same. It is advisable to update to use the ‘dashicons’ icon font instead of image icon.

TinyMCE 4.0 includes a ‘compat3x’ plugin that should prevent all fatal errors caused by old plugins and adds compatibility for most of the 3.x API methods. If there are any editor related Javascript errors while running trunk, please open a trac ticket quoting the first error from the browser console.

#3-9, #dev-notes, #editor, #tinymce

WordPress 3.5 RC6 is out Please if you…

WordPress 3.5 RC6 is out. Please, if you can (and earlier the better), hammer on TinyMCE with the most ridiculous object and embed tags you can find, and anything HTML5. (Here’s a zip for the nightly build.)

What’s important in RC6? After a good first attempt last week (#22790), we took another stab (#22842) at fixing TinyMCE’s handling of, well, ridiculous object and embed tags. Our goal right now is to ensure that nothing breaks in 3.5 that worked in 3.4.2. So, go find your best embed spaghetti* and make sure nothing breaks.**

  • Very easy to test: Go to the “Text “tab, paste something in, head to the Visual tab, confirm things don’t look broken, head back to the “Text” tab, see if it looks mangled, head back to Visual, confirm things don’t look broken. Remember, we are looking for regressions, so also check 3.4.2 to see if it occurs there.

** Breaks means the embed disappears in whole or part, or there’s a JavaScript error, or your computer starts smoking. Whitespace and other HTML changes do/will happen (contents may settle during shipping). Of course, your content should never be damaged, as that’s just no fun.

What happened to the last two RCs? We generally try to do a “soft” or “silent” RC at the very end of a cycle. We’re confident we’ve gotten the testing it needs, but we’d like to enter a 24-hour period where there are no more changes to trunk. Having a cleaner version number provides for a good line in the sand, and can help in case some blocker bug report comes in. Of course this time, we’ve stuttered a few times. TinyMCE hell was RC4. A few final changes on Friday (after we decided to not release) resulted in RC5. And the second round of TinyMCE hell is RC6.

This also means our new target is Tuesday, December 11. We’ll again convene at 10 a.m. Eastern to see if the winds are blowing in our direction. (Even NASA needs good weather.)

And hey, on the bright side:

#3-5, #tinymce

Updated TinyMCE to 3.2.0 and removed the …

Updated TinyMCE to 3.2.0 and removed the compression, so it can be cached in Gears and the browser. Seems to speed up the loading of the Write/Edit page by up to 40% (tested on a typical shared hosting). Some more info.

#tinymce