From ee3052fdbe4f972ac6b38fbf5a60dd1edb88700f Mon Sep 17 00:00:00 2001 From: Andrew Ozz Date: Mon, 16 Jan 2017 00:49:41 +0000 Subject: [PATCH] Docs: some improvements/fixes for editor.js. See #38933. Built from https://develop.svn.wordpress.org/trunk@39911 git-svn-id: http://core.svn.wordpress.org/trunk@39848 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/js/editor.js | 273 +++++++++------------------------------- wp-includes/version.php | 2 +- 2 files changed, 63 insertions(+), 212 deletions(-) diff --git a/wp-admin/js/editor.js b/wp-admin/js/editor.js index 002cf4a11f..17d296276d 100644 --- a/wp-admin/js/editor.js +++ b/wp-admin/js/editor.js @@ -1,43 +1,24 @@ ( function( $ ) { /** - * @summary Creates the tinyMCE editors. + * @summary Utility functions for the editor. * - * Creates the tinyMCE editor and binds all events used for switching - * from visual to text mode. - * - * @since 4.3.0 - * - * @class + * @since 2.5.0 */ function SwitchEditors() { var tinymce, $$, exports = {}; - /** - * @summary Initializes the event binding for switching editors. - * - * @since 4.3.0 - * - * @returns {void} - */ function init() { if ( ! tinymce && window.tinymce ) { tinymce = window.tinymce; $$ = tinymce.$; /** - * @summary Handles onclick events for the editor buttons. + * @summary Handles onclick events for the Visual/Text tabs. * * @since 4.3.0 * - * Handles an onclick event on the document. - * Switches the editor between visual and text, - * if the clicked element has the 'wp-switch-editor' class. - * If the class name is switch-html switches to the HTML editor, - * if the class name is switch-tmce - * switches to the TMCE editor. - * * @returns {void} */ $$( document ).on( 'click', function( event ) { @@ -54,12 +35,11 @@ } /** - * @summary Retrieves the height of the toolbar based on the container the - * editor is placed in. + * @summary Returns the height of the editor toolbar(s) in px. * * @since 3.9.0 * - * @param {Object} editor The tinyMCE editor. + * @param {Object} editor The TinyMCE editor. * @returns {number} If the height is between 10 and 200 return the height, * else return 30. */ @@ -75,17 +55,14 @@ } /** - * @summary Switches the editor between visual and text. + * @summary Switches the editor between Visual and Text mode. * - * @since 4.3.0 + * @since 2.5.0 * * @memberof switchEditors * - * @param {string} id The id of the editor you want to change the editor mode for. - * If no id is given, it defaults to content. - * @param {string} mode The mode you want to switch to. - * If an undefined mode is given, it defaults to toggle. - * + * @param {string} id The id of the editor you want to change the editor mode for. Default: `content`. + * @param {string} mode The mode you want to switch to. Default: `toggle`. * @returns {void} */ function switchEditor( id, mode ) { @@ -98,7 +75,6 @@ $textarea = $$( '#' + id ), textarea = $textarea[0]; - // Toggle the mode between visual and textual representation. if ( 'toggle' === mode ) { if ( editor && ! editor.isHidden() ) { mode = 'html'; @@ -107,20 +83,13 @@ } } - - // If the mode is tmce or tinymce, show the editor. if ( 'tmce' === mode || 'tinymce' === mode ) { - - /* - * If the editor isn't hidden we are already in tmce mode - * and we don't need to switch. - * Return false to stop event bubbling. - */ + // If the editor is visible we are already in `tinymce` mode. if ( editor && ! editor.isHidden() ) { return false; } - // Close the QuickTags toolbars if they are visible. + // Insert closing tags for any open tags in QuickTags. if ( typeof( window.QTags ) !== 'undefined' ) { window.QTags.closeAllTags( id ); } @@ -130,12 +99,12 @@ if ( editor ) { editor.show(); - // Don't resize the iframe in iOS. + // No point to resize the iframe in iOS. if ( ! tinymce.Env.iOS && editorHeight ) { toolbarHeight = getToolbarHeight( editor ); editorHeight = editorHeight - toolbarHeight + 14; - // Height must be between 50 and 5000. + // Sane limit for the editor height. if ( editorHeight > 50 && editorHeight < 5000 ) { editor.theme.resizeTo( null, editorHeight ); } @@ -148,21 +117,14 @@ $textarea.attr( 'aria-hidden', true ); window.setUserSetting( 'editor', 'tinymce' ); - // Hide the editor if mode is html. } else if ( 'html' === mode ) { - - /* - * If the editor is hidden we are already in html mode and - * we don't need to switch. - * Return false to stop event bubbling. - */ + // If the editor is hidden (Quicktags is shown) we don't need to switch. if ( editor && editor.isHidden() ) { return false; } if ( editor ) { - - // Don't resize the iframe in iOS. + // Don't resize the textarea in iOS. The iframe is forced to 100% height there, we shouldn't match it. if ( ! tinymce.Env.iOS ) { iframe = editor.iframeElement; editorHeight = iframe ? parseInt( iframe.style.height, 10 ) : 0; @@ -171,7 +133,7 @@ toolbarHeight = getToolbarHeight( editor ); editorHeight = editorHeight + toolbarHeight - 14; - // Height must be between 50 and 5000. + // Sane limit for the textarea height. if ( editorHeight > 50 && editorHeight < 5000 ) { textarea.style.height = editorHeight + 'px'; } @@ -180,7 +142,7 @@ editor.hide(); } else { - // The TinyMCE instance doesn't exist, show the textarea. + // There is probably a JS error on the page. The TinyMCE editor instance doesn't exist. Show the textarea. $textarea.css({ 'display': '', 'visibility': '' }); } @@ -191,20 +153,18 @@ } /** - * @summary Replaces all paragraphs with double line breaks. + * @summary Replaces

tags with two line breaks. "Opposite" of wpautop(). * - * Replaces all paragraphs with double line breaks. Taking into account - * the elements where the

should be preserved. - * Unifies all whitespaces. - * Adds indenting with tabs to li, dt and dd elements. - * Trims whitespaces from beginning and end of the html input. + * Replaces

tags with two line breaks except where the

has attributes. + * Unifies whitespace. + * Indents

  • ,
    and
    for better readability. * - * @since 4.3.0 + * @since 2.5.0 * * @memberof switchEditors * * @param {string} html The content from the editor. - * @return {string} The formatted html string. + * @return {string} The content with stripped paragraph tags. */ function removep( html ) { var blocklist = 'blockquote|ul|ol|li|dl|dt|dd|table|thead|tbody|tfoot|tr|th|td|h[1-6]|fieldset', @@ -218,10 +178,7 @@ return ''; } - /* - * Protect script and style tags by replacing them with . - * Push matches into the preserve array. - */ + // Protect script and style tags. if ( html.indexOf( ']*>[\s\S]*?<\/\1>/g, function( match ) { preserve.push( match ); @@ -229,10 +186,7 @@ } ); } - /* - * Protect pre tags by replacing all newlines and - *
    tags with . - */ + // Protect pre tags. if ( html.indexOf( ']*>[\s\S]+?<\/pre>/g, function( a ) { @@ -242,10 +196,7 @@ }); } - /* - * Keep
    tags inside captions and remove line breaks by replacing - * them with . - */ + // Remove line breaks but keep
    tags inside image captions. if ( html.indexOf( '[caption' ) !== -1 ) { preserve_br = true; html = html.replace( /\[caption[\s\S]+?\[\/caption\]/g, function( a ) { @@ -253,65 +204,53 @@ }); } - // Format the text to be readable in the source editor. + // Normalize white space characters before and after block tags. html = html.replace( new RegExp( '\\s*\\s*', 'g' ), '\n' ); html = html.replace( new RegExp( '\\s*<((?:' + blocklist1 + ')(?: [^>]*)?)>', 'g' ), '\n<$1>' ); // Mark

    if it has any attributes. html = html.replace( /(

    ]+>.*?)<\/p>/g, '$1' ); - // If the content of a container starts with a paragraph, replace the

    tag with 2 newlines. + // Preserve the first

    inside a

    . html = html.replace( /]*)?>\s*

    /gi, '\n\n' ); - // Remove

    and

    tags. + // Remove paragraph tags. html = html.replace( /\s*

    /gi, '' ); html = html.replace( /\s*<\/p>\s*/gi, '\n\n' ); - // Remove white spaces between newlines. u00a0 is a no breaking space. + // Normalize white space chars and remove multiple line breaks. html = html.replace( /\n[\s\u00a0]+\n/g, '\n\n' ); - // Remove
    tags. + // Rrplace
    tags with a line break. html = html.replace( /\s*
    \s*/gi, '\n' ); - /* - * Fix some block element newline issues. - * Replace white spaces with newlines in combination with

    tags. - */ + // Fix line breaks around
    . html = html.replace( /\s*
    \s*/g, '
    \n' ); - // Replace white spaces with newlines in combination with [caption] shortcodes. + // Fix line breaks around caption shortcodes. html = html.replace( /\s*\[caption([^\[]+)\[\/caption\]\s*/gi, '\n\n[caption$1[/caption]\n\n' ); - - /* - * Limit the newlines in combination with [caption]'s to a maximum of - * two consecutive occurrences. - * . - */ html = html.replace( /caption\]\n\n+\[caption/g, 'caption]\n\n[caption' ); - /* - * Replace white spaces with newlines in combination with - * all elements listed in blocklist2. - */ + // Pad block elements tags with a line break. html = html.replace( new RegExp('\\s*<((?:' + blocklist2 + ')(?: [^>]*)?)\\s*>', 'g' ), '\n<$1>' ); html = html.replace( new RegExp('\\s*\\s*', 'g' ), '\n' ); - // Add indentation by adding a tab in front of
  • ,
    and
    tags. + // Indent
  • ,
    and
    tags. html = html.replace( /<((li|dt|dd)[^>]*)>/g, ' \t<$1>' ); - // Replace white spaces with newlines in combination with and