WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#34866 closed defect (bug) (fixed)

Improve documentation for format_for_editor()

Reported by: swissspidy Owned by: swissspidy
Milestone: 4.5 Priority: normal
Severity: normal Version:
Component: Editor Keywords: good-first-bug has-patch commit
Focuses: docs Cc:

Description

format_for_editor() has an optional $default_editor parameter that I think is either passed 'html' or 'text'. It's totally not documented and could need some love.

See also the the_editor_content filter where format_for_editor() is applied to. $default_editor needs to be documented there as well.

See the PHP documentation standards for formatting details.

Attachments (2)

34866.patch (1.5 KB) - added by AramZS 5 years ago.
First pass at making documentation consistent with current behavior.
34866.2.patch (1.7 KB) - added by swissspidy 5 years ago.

Download all attachments as: .zip

Change History (7)

#1 @AramZS
5 years ago

Making a note here that the default value is not guaranteed to this function, but is depending on either the parent's call or the user's settings. This is what I think I've found, and it is sort of confusing.

_WP_Editors()::parse_settings() enforces the defaults passed to format_for_editor() and specifies an empty default.

_WP_Editors()::editor() uses wp_default_editor() to set and empty value for $default_editor to either 'tinymce' or 'html' depending on user permissions and then the settings for the user via get_user_setting('editor', 'tinymce');. The allowed values there are 'tinymce', 'html' and 'test' and that is filtered by apply_filters( 'wp_default_editor', $r );

If nothing is passed, the default is called. If anything other than 'html' is set by either method, WordPress will change the value to tinymce.

Theoretically, at this point, format_for_editor should be hooked to the_editor_content where it will receive both the content that gets filtered and the $default_editor value (not assured, but likely one of the two above options). The back-compat code seems to indicate that is the case:

		// Back-compat for the `htmledit_pre` and `richedit_pre` filters
		if ( 'html' === $default_editor && has_filter( 'htmledit_pre' ) ) {
			// TODO: needs _deprecated_filter(), use _deprecated_function() as substitute for now
			_deprecated_function( 'add_filter( htmledit_pre )', '4.3.0', 'add_filter( format_for_editor )' );
			$content = apply_filters( 'htmledit_pre', $content );
		} elseif ( 'tinymce' === $default_editor && has_filter( 'richedit_pre' ) ) {
			_deprecated_function( 'add_filter( richedit_pre )', '4.3.0', 'add_filter( format_for_editor )' );
			$content = apply_filters( 'richedit_pre', $content );
		}

Notably format_for_editor is only hooked to the the_editor_content filter in a situation where the user is allowed to use TinyMCE. Which can be the case for either html or tinymce. But, if, let's say, the user can only see the_editor_content in HTML mode (because, for example, TinyMCE is disallowed), the filter is never added:

		if ( self::$this_tinymce ) {
			add_filter( 'the_editor_content', 'format_for_editor', 10, 2 );
		}

Which means that $default_editor will (in practice) only ever take html or tinymce. Developers who turn off TinyMCE (even if they're using some other wysiwyg) and users without permission to use it will never see the format_for_editor filter fire. The only other case where this would apply would be if some plugin or theme is calling this function themselves and feeding in a different value? Is that an intended use? I don't know if this should matter for documenting, but I thought I'd note here that this might not be the intended execution, as indicated by the rest of the code. It's also weird, because it means that you can only filter the_editor_content if tinymce is enabled, though it can effect both html and tinymce modes.

Last edited 5 years ago by AramZS (previous) (diff)

@AramZS
5 years ago

First pass at making documentation consistent with current behavior.

#2 @AramZS
5 years ago

  • Keywords has-patch added; needs-patch removed

I've patched this to make the inline documentation significantly clearer. However, I'm not entirely sure the filters here are working as expected, but that would be a whole other ticket.

@swissspidy
5 years ago

#3 @swissspidy
5 years ago

  • Milestone changed from Awaiting Review to 4.5

34866.2.patch is an updated patch, unifying and properly aligning the docs.

#4 @swissspidy
5 years ago

  • Keywords commit added

#5 @swissspidy
5 years ago

  • Owner set to swissspidy
  • Resolution set to fixed
  • Status changed from new to closed

In 35904:

Docs: Improve documentation for format_for_editor() and the 'the_editor_content' filter it is hooked to.

Props AramZS for initial patch.
Fixes #34866.

Note: See TracTickets for help on using tickets.