[wp-trac] [WordPress Trac] #34866: Improve documentation for format_for_editor()

[WordPress Trac]

#34866: Improve documentation for format_for_editor()
----------------------------------------+------------------------------
 Reporter:  swissspidy                  |       Owner:
     Type:  defect (bug)                |      Status:  new
 Priority:  normal                      |   Milestone:  Awaiting Review
Component:  Editor                      |     Version:
 Severity:  normal                      |  Resolution:
 Keywords:  needs-patch good-first-bug  |     Focuses:  docs
----------------------------------------+------------------------------

Comment (by AramZS):

 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, and anything other than
 `'html'` is set, 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.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/34866#comment:1>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform