Editor API enhancement

[azaozz]

The Visual and HTML editors together with all the supporting functions should be combined in an easy to use API on both PHP and JS sides.

On the JS side we can call the functions/methods in quicktags.js from a TinyMCE plugin that includes the editor switching, hiding the toolbar, filtering, etc. This would also make it a lot easier for plugins to use both editors in the same way as on the Write screen.

On the PHP side we can combine all supporting functions and put them in the same place.

To do:

• fix the blue theme to properly overwrite styles for the editors
• remove unused styles from wp-admin.css and the colors css
• move some of the JS that's outputted from PHP to editor.js so it can be cached
• more phpdoc

[scribu]

Now I see what you were getting at. :)

Related: #16695

[ptahdunbar]

Abstracting the js to use classes instead of ids so we can have multiple editors on one page would be the hawtness too :)

[WraithKenny]

On editor tab switch, we should use admin ajax to check for 'unfiltered_html', $allowedTags or $allowedPostTags using the php KSES functions, and perhaps use the php wpautop rather then a js version to save on maintaining two separate functions.

[azaozz]

Closed #18150 as duplicate as that case should be handled while refactoring the API.

[azaozz]

Replying to WraithKenny:

On editor tab switch, we should use admin ajax to check for 'unfiltered_html', $allowedTags or $allowedPostTags using the php KSES functions,

The way TinyMCE works we can set invalid_elements while initiating it. That covers HTML tags and attributes.

and perhaps use the php wpautop rather then a js version to save on maintaining two separate functions.

This will make switching from the HTML editor to TinyMCE quite slow, but something to test nevertheless. In any case maintaining wpautop in both languages (JS and PHP) is not a problem at all.

[azaozz]

Closed #18219 as duplicate.

[xazure]

Thanks for beating me to this. ;)

I did a quick search and came up with nothing. Guess I wasn't searching for the right thing.

[azaozz]

In [18498]:

Editor API enhancement, first run (still needs some work), see #17144

[ocean90]

A typo in wp-includes/deprecated.php * @deprecated 3.5 should be * @deprecated 3.3 for wp_default_editor.

[dd32]

As noted by tonyjansen in IRC, this causes non-script_debug installs to have missing toolbar buttons. url("../js/tinymce/themes/advanced/img/icons.gif") doesn't resolve correctly when using load-styles.php/load-scripts.php.

[nacin]

Some issues I see:

The HTML/CSS doesn't look backwards compatible in terms of class names or IDs. I don't think it would be difficult to retain this.

the_editor() should not be deprecated. It should simply wrap WP_Editor.

the_editor() appears twice in the code. trunk is probably fatal erroring.

Not sure I get the internal linking refactoring, or why wp_link_query() isn't still a function that, if appropriate, calls WP_Editor/$wp_editor.

I really wish we saw a patch and explanations before these major patches land. This has bit us before and I sense a lot of backwards incompatibility issues will arise.

[azaozz]

Replying to dd32:

Patch coming up.

Replying to nacin:

The HTML/CSS doesn't look backwards compatible in terms of class names or IDs. I don't think it would be difficult to retain this.

The old HTML didn't allow multiple editors on the same page, retaining the IDs would mean we still ban that.

the_editor() should not be deprecated. It should simply wrap WP_Editor.

Most of the functionality of the old the_editor() is in $wp_editor->editor(). We can have it as a separate function (again) but don't see the point since wp_tiny_mce() is now gone.

the_editor() appears twice in the code. trunk is probably fatal erroring.

Not seeing that (and trunk doesn't fatal error).

Not sure I get the internal linking refactoring, or why wp_link_query() isn't still a function that, if appropriate, calls WP_Editor/$wp_editor.

There's no refactoring. Only moved the JS and CSS out of the TinyMCE directory as they are used for the HTML editor too.

I really wish we saw a patch and explanations before these major patches land. This has bit us before and I sense a lot of backwards incompatibility issues will arise.

Was planning to put a patch up first, but it became too big for that :)

[nacin]

The old HTML didn't allow multiple editors on the same page, retaining the IDs would mean we still ban that.

The first editor could retain the existing ID. Subsequent ones can be new IDs.

Most of the functionality of the old the_editor() is in $wp_editor->editor(). We can have it as a separate function (again) but don't see the point since wp_tiny_mce() is now gone.

The point is simple: Everyone uses it. It should stay and be a wrapper.

[nacin]

There's no need for a lot of those functions to become methods. Example: wp_link_query(), which never once interfaces with the rest of the object, nor does wp_fullscreen_html(), nor does wp_link_dialog().

All of these functions should still exist on their own. Optionally, they can wrap the $wp_editor->$method() version, but I don't find that necessary either.

[azaozz]

Replying to nacin:

The first editor could retain the existing ID. Subsequent ones can be new IDs.

The only changed IDs are on the switching buttons, the rest are new. Of course the quicktags toolbar ID is changed too but that's in #16695.

The point is simple: Everyone uses it. It should stay and be a wrapper.

You mean don't deprecate the_editor()? That would make two wrappers for the same thing :)
The arguments have changed (not in a breaking way), thinking by deprecating it we will draw attention to that.

There's no need for a lot of those functions to become methods... All of these functions should still exist on their own.

Added them in the class as it's only loaded (lazily) when needed and these functions are only used there. Can probably move wp_link_query() directly to admin-ajax.php as it can only be usefull from there. Don't see a point for wp_fullscreen_html() and wp_link_dialog() to be separate functions. Furthermore they will be loaded on each run of WP (on the front end) which is undesirable.

Actually we have quite a bit of code in wp-includes that is loaded on each run of WP but used once in a while (1 in 10,000?). Even some functions that cannot be run unless wp-admin is loaded. All this eats some resources which multiplied by many millions amount to a lot :)

[azaozz]

In [18503]:

Fix editor icons when no SCRIPT_DEBUG, see #17144

[azaozz]

test-wp-editor-class.zip is a small testing plugin for the new API. Unzip in wp-content/plugins and read through the code.

[ocean90]

Works good so far. Only send to editor is missing, it will be only added the editor id. You are working on it?

Also if it's planned to use the media buttons on frontend too, get_upload_iframe_src needs an update too.

$upload_iframe_src = add_query_arg('post_id', $uploading_iframe_ID,  'media-upload.php' );

// Add admin_url()
$upload_iframe_src = add_query_arg('post_id', $uploading_iframe_ID, admin_url( 'media-upload.php' ) );

If it works we can close #14311.

[azaozz]

In [18516]:

Fix send_to_editor() and Insert/Upload buttons URLs, see #17144

[azaozz]

Replying to ocean90:

Only send to editor is missing...

Expecting this to change soon-ish when we tweak the UI for the new uploader, but can as well fix it for now :)

[SergeyBiryukov]

17144.i18n.patch​ restores TinyMCE i18n, missing from [18498].

[ocean90]

Two points:

• editor-buttons.css includes not only buttons styles, also for the editor, can we rename it to (wp-)editor.css?
• If can_richedit is true, tinymce is false and media_buttons is false too, the wp-editor-tools row is shown, but empty, because of this we need to hack into ​user_can_richedit(). Patch attached.

[azaozz]

In [18518]:

Fix i18n for wp_editor, props SergeyBiryukov, see #17144

[azaozz]

In [18519]:

WP_Editor: don't show empty div if no editor-buttons and media-buttons are shown, props ocean90, see #17144

[azaozz]

Replying to ocean90:

• editor-buttons.css includes not only buttons styles, also for the editor, can we rename it to (wp-)editor.css?

Actually that was the first name I used. Changed it as it implies css for use inside the (visual) editor which is not the case. These styles are for "around the editor" :)

[scribu]

Speaking of media buttons: ​http://core.trac.wordpress.org/ticket/17578#comment:4

[SergeyBiryukov]

17144.quickpress.patch​ contains some fixes for QuickPress:

• Media buttons need padding after [18498] (see the screenshot)
• They have ID's like id="-add_image" instead of id="content-add_image"
• The labels are 1px lower after [18460]

[azaozz]

Replying to SergeyBiryukov:

17144.quickpress.patch​ contains some fixes for QuickPress:

Yes, editor-buttons.css is not loaded on the dashboard (for now). As only the media buttons are used there perhaps we should add these styles to the admin css. However I expect this to change soon as the new uploader #18206 progresses. This also will be affected by #18314.

[azaozz]

Replying to scribu:

Speaking of media buttons: ​http://core.trac.wordpress.org/ticket/17578#comment:4

Yes, I expect this will be changed when we look at the UI around the new uploader.

[ocean90]

Related: #18348

[azaozz]

There were some small changes in quicktags.js, updated the test plugin to reflect them.

[andrewryno]

I changed around SergeyBiryukov's patch for QuickPress since it was broken in [18498]. Since the media buttons show up on the post page and the dashboard, I moved the CSS to wp-admin.css so it's not duplicated across files.

[azaozz]

In [18553]:

Fix (temporarily?) the spacing between the uploader buttons on the dashboard, props SergeyBiryukov and andrewryno, see #17144

[SergeyBiryukov]

QuickPress media buttons still have IDs like id="-add_image" instead of id="content-add_image". Shouldn't we pass 'content' to do_action( 'media_buttons' )? That was a part of 17144.quickpress.patch​ too.

[azaozz]

Replying to SergeyBiryukov:

Shouldn't we pass 'content' to do_action( 'media_buttons' )...

I expect the button(s) to change in the next 2-3 weeks but you're right, we should make them fully compatible at this stage too.

[azaozz]

In [18555]:

Fix HTML IDs on the uploader buttons on the dashboard, props SergeyBiryukov, see #17144

[andrewryno]

Oops, meant to merge that in with my patch. I made mine before I saw yours so tried to match them up.

[azaozz]

17144-the_editor.patch removes wp_editor() and restores the_editor().

[azaozz]

Been thinking whether the deprecation of the_editor() is warranted (the patch above "undeprecates" it). It seems it's on the borderline: on one hand the changes to the API are too great not to deprecate it. Actually we didn't have a workable API before, just a bunch of PHP and JS functions that needed some hacks to get them working.

On the other hand the_editor() can still be used similarly to how it was used before, but with the new API it will also enqueue all JS and CSS needed for a working multi-instance editor.

I've also been working on a compatibility class (to be used by plugins) that brings the new API to WP 3.0 - 3.2. It should land in the plugins directory in couple of weeks.

In that terms it seems the scales tip in favor of deprecating the old functions.

[azaozz]

In [18570]:

Fix Press This editors, see #17144

[azaozz]

In [18574]:

Another fix for Press This, see #17144

[nacin]

Replying to azaozz:

In [18574]:

Another fix for Press This, see #17144

While this prevents the fatal error, we should go ahead and convert all array references to a post object. Building an array makes sense if you want to wp_insert_post(), but if we have a post object available, we should use it. (Especially if they one day become decorated.)

[azaozz]

Replying to nacin:

While this prevents the fatal error, we should go ahead and convert all array references to a post object.

Converted the post object to array as it takes values from the $_POST and when doing wp_update_post() it expects arrays to be slashed (like the $_POST is) but objects to be slash-free.

Agree that Press This needs a (far) more serious update, even better - refactoring.

[WraithKenny]

There seems to be a check for a wpautop (boolean) in editor.dev.js that determines whether to call the wpautop() javascript method, but that check isn't present in wp-fullscreen.dev.js. Is this meant to allow plugins to save pee'd content?

[WraithKenny]

When loading the post edit screen in HTML Mode, then launching Fullscreen, "tinyMCE.settings is undefined" Line 346 in fullscreen.dev.js

Also, (avoiding the above by loading page in Visual then switch to HTML) when launching Fullscreen in HTML Mode, then switching to Visual Mode in fullscreen, switchEditors.wpautop seems to be called twice. (test with firebug console: jQuery('body').live('beforeWpautop', function(){console.log('called: switchEditors.wpautop')});)

[SergeyBiryukov]

In [18498], tiny_mce_version filter was removed, but phpdoc was left. Should we reinstate the filter or remove phpdoc? 17144.tiny_mce_version.patch​ does the latter.

[azaozz]

Replying to SergeyBiryukov:

That filter has been redundant for couple of years now. However it used to be required for all external TinyMCE plugins that were loaded by WP. Thinking we still need to have some explanation on how to achieve the scripts and styles refresh when loading external plugins. Perhaps it would be better to add this to the codex and only leave a link to it at the place the filter used to be.

[azaozz]

Replying to WraithKenny:

There seems to be a check for a wpautop (boolean) in editor.dev.js that determines whether to call the wpautop() javascript method, but that check isn't present in wp-fullscreen.dev.js.

The DFW mode can only be used on the new/edit post pages as it requires some specific html, layout, css, etc. At one point WP_Editor used to switch automatically to either DFW or the default fullscreen depending where it was loaded, perhaps will have to put that back.

[azaozz]

In [18609]:

Fix TimyMCE init when launching DFW and respect wpautop setting there, see #17144

[azaozz]

In [18626]:

Fix styling of the editors for the blue theme, props saracannon, see #17144

[Ipstenu]

There's a weird consistency thing.

When you're using DFW, the Add Media button is on the bar with B/I/U etc.

When you're not, it's ABOVE them. Perhaps we should consider adding it to the main toolbar? And just have the one 'Add Media' button and not the trio?

[trepmal]

Here's my (reduced) plugin:

add_action('admin_menu', function () {
	add_menu_page('wp_editor', 'wp_editor', 'read', 'wp_editor', function () {
		echo '<div class="wrap"><h2>wp_editor()</h2>';

		$content = '';
		$id = 'editor-test';

		$settings = array(
			'quicktags' => array(
				'buttons' => 'em', // quicktags.dev.js:573  Uncaught TypeError: Cannot read property 'callback' of undefined
			),
			//'tinymce' => false
		);

		wp_editor($content, $id, $settings);

		echo '</div>';

	});
});

I can customize the available quicktags, but if I don't include 'close'

...
'buttons' => 'em,close'
...

I get a javascript error when I try to switch back to Visual mode.

I don't have the JS skills to write an awesome patch, so I have a really small patch that could probably be done better.

Alternatively, I have a patch for the WP_Editor class that simply forces 'close' to always be present in the quicktags when tinymce is true.

[trepmal]

use close button if available

[trepmal]

require 'close' quicktag

[azaozz]

Replying to trepmal:

This should be fixed in [18727]. Made the "close all tags" function separate from the button callback.

[Ipstenu]

Brian Gardner found a weird bug that I can reproduce, and I'm 99% sure it's falling under this.

1) In your profile, check the box to 'Disable Visual Editor while posting'
2) Go into a post and try to use the link button in HTML view (which is the only view you have)
3) Fail.

However... if that box is not checked, everything's fine!

I was able to repro this locally on a clean build and on my live site.

[ocean90]

Ipstenu, yes, I can reproduce it too and also fullscreen isn't working.

[trepmal]

Adding to that, HTML view link button also fails on a new instance of the editor when Visual isn't available

add_action('admin_menu', function () {
	add_menu_page('wp_editor', 'wp_editor', 'read', 'wp_editor', function () {
		echo '<div class="wrap"><h2>wp_editor()</h2>';
		$settings = array(
			'tinymce' => false
		);
		wp_editor('', 'editor-test', $settings);
		echo '</div>';
	});
});

[azaozz]

In [18766]:

Fix wplink when TinyMCE is not loaded, fix image insertion when wpActiveEditor is not set, see #17144

[Ipstenu]

At revision 18777.

HTML DFW view, 'Add Image' fails to pop-up anything. You can click on the image link all you want and it does nothing.

Alt-shift-M brings up the external image interface.

[azaozz]

In [18778]:

Fix the uploader popup in DWF, reduce the height of the drop area, see #17144

[azaozz]

In [18799]:

Fix enqueueing of the right scripts when more than one instance of the editor, fix inserting images in full screen mode, see #17144

[azaozz]

In [18803]:

Use WP_Editor when editing or replying to comments, props ocean90, remove vendor specific selectors from editor-buttons.css, fixes #18348, see #17144

[ocean90]

r18799 brokes the send to editor function:

Uncaught ReferenceError: tinymce is not defined media-upload.dev.js:19

[azaozz]

In [18837]:

Fix editor detection when inserting image, see #17144

[ocean90]

Insert to post doesn't work for QuickPress. It doesn't add the HTML to the content.

[ocean90]

...and PressThis doesn't work too. Neither the image will be added to the library nor the HTML will be inserted.

[greenshady]

Is an $echo argument something that might be a possibility so we can return the HTML for the form? For an example idea, imagine creating a plugin that would filter the comment form and make the comment textarea a bit more fun.

Right now, the only issue I see with this might be:

do_action('media_buttons', $editor_id);

[azaozz]

Replying to greenshady:

Right now, the only issue I see with this might be:

do_action('media_buttons', $editor_id);

The output was actually set as a var before (wanted to add a filter for it), had to change it because of that action. For a moment was thinking to run it in a buffer but that's too hacky :)

[azaozz]

In [18920]:

Fix insetring images in Quick Press and Press This, see #17144

[azaozz]

In [18921]:

Actually the Press This styles changed in [18920] are not needed, see #17144

[GDragoN]

I have tested the new WP_Editor class in the meta box on the post edit page with this code:

$gdtt_editor = new WP_Editor();
$gdtt_editor->editor($value, $id, array("textarea_name" => $name));

And my editor loads and renders as you would expect it, but the the main post editor is broken. There is one JavaScript error reported in tiny_mce.js (it is compressed file even with SCRIPT_DEBUG, so the error is not very clear: q is not a constructor). Main post editor has HTML editor and it is working, but Visual editor is missing. When I add second custom editor, than that one is OK, but main post editor and my first editor are broken. So, only the last editor created is actually working.

Also, there are couple styling issues with added editors: visual editor background color was gray (as the meta box) and resize element was outside of the editor.

I was using trunk code from today (october 13, 2011, revision 18964).

[azaozz]

Replying to GDragoN:

Could you make sure there's nothing else trying to initialize the editors on the page. Or better: can you attach the html (removing any URLs, nonces, etc. if it's a live site) to the ticket.

Also you shouldn't instantiate the class again. It keeps pointers to what's already loaded. Use the wp_editor() function instead.

[GDragoN]

The only thing working on the website is my plugin that is attempting this, so nothing is influencing the rendering. I am busy at the moment, but I will make some extra experimenting tomorrow, and will post back if I find something that is maybe wrong, and I will attach the HTML generated.

[azaozz]

Replying to GDragoN:

Think that's happening because of the "new" WP_Editor. It looses the count of what's loaded. Perhaps we should turn it in a "true" singleton making sure it's instantiated only once.

[GDragoN]

Yeah, that might be good thing to do. And what you said about count it makes sense, because in my case only the last added editor works, previous ones are broken. I will try to see if I can reuse editor instance for the main editor first. I will have more on this tomorrow.

[GDragoN]

OK, I was curios about this, so I made changes to the code, and I am using wp_editor function call instead of creating new editor instance. And it works now.

But, I wanted to try DFW option for new full screen from WP 3.2 editor, and that one is giving this error:
Fatal error: Cannot redeclare replace_fullscreen() (previously declared in ...\wp-includes\class-wp-editor.php:368) in ...\wp-includes\class-wp-editor.php on line 368

So, at this moment extra editors can't have DFW full screen. I don't see other problems at the moment, works really well.

[azaozz]

Yes, DFW is a special case as it needs specific DOM components and CSS. We may eventually get it to work everywhere but it's not going to be very easy or clean.

[GDragoN]

Right now it is not a big deal. Editor works well and that is all that matters. If later, DFW gets sorted out, fine. This new editor model is a really important addition to the WP that will make a life of plugin developers like me much easier.

[azaozz]

In [18988]:

Add some more documentation and prevent fatal error if a plugin tries to use 'dfw' second time, see #17144

[azaozz]

This should be implemented now. Please open new tickets for any bugs.

[azaozz]

Updated test plugin

[azaozz]

In [19239]:

More phpdoc for wp_editor(), see #17144

[azaozz]

In [19316]:

Make switchEditors.go() fully back-compat, see #17144

[azaozz]

In [19319]:

mode == 'tmce'

mode == 'tinymce', see #17144

[azaozz]

In [19457]:

TinyMCE: add class to the editor body for the old fullscreen mode (still can be used by plugins), see #17144

[azaozz]

In [19533]:

Make sure editor-buttons.css is loaded even if tiny_mce.js is used directly and the wp_theme skin is selected in the settings, see #17144

[sushkov]

A bit too late to report this, but as a developer who was able to use the WordPress editor API (before 3.3) to build forms with full support for rich text editing, media-uploads, DFW and why not multiple instances of those, I feel very disappointed to port all that old code to the new wp_editor().

Basically what it was supposed to solve, all from above, it doesn't right now (that amazing DFW, and media-uploads didn't work for me straight, might be wrong with the last one).
So right now I'm forced to start using this new API call, with the hope that in future it will get some more love from devs, and will change again, in exchange of some old, internal calls/hooks that were working great!

Reading again the ticket statement, I don't see what problem you were trying to solve...
Anyway, I just hope it will get better with time.

[azaozz]

Replying to sushkov:

So right now I'm forced to start using this new API...

There's nothing forcing you to use the API. It is meant to output the same editor configuration as on the Edit/Write screen. Nothing more.

...in exchange of some old, internal calls/hooks that were working great!

Which hooks are you referring to?

...I don't see what problem you were trying to solve...

The API makes it a lot easier to use the main editor configuration. It is targeted at plugin devs that want to use it. If you don't want to use it, there's nothing stopping you. It's pretty simple to load tiny_mce.js or the pre-compressed wp-tinymce.php and create as many instances of it as you need. Then you're in full control. The same is true for Quicktags.

[sushkov]

Regarding the hooks:
​https://github.com/scholarpress/buddypress-courseware/blob/master/courses/courses.class.php#L397 (To load enqueues)
​https://github.com/scholarpress/buddypress-courseware/blob/master/groups/templates/edit_course.php#L13 (To render the editor, mind that now, wp_tiny_mce() gives a fatal error because it looks like deprecated.php is not loaded to properly inside the files that were containing it before)

What about DFW, the plugin uses hard-coded stuff like:
​https://github.com/WordPress/WordPress/blob/master/wp-includes/js/tinymce/plugins/wpfullscreen/editor_plugin.dev.js#L37

Where you can use something like:
ed = (tinyMCE.editors.length > 0) ? tinyMCE.editors[0] : tinymce.get('content');

Another problem is even DFW is passed as true the proper CSS is not loaded.

So back to my initial argument, I can't see the real benefit of wp_editor() changes, because as an older developer of wp-editor API I still have to hack around to get things done!
Another question is why would you decide to change code that was already working?!