WordPress.org

Make WordPress Core

Changeset 39738


Ignore:
Timestamp:
01/06/2017 02:13:44 PM (19 months ago)
Author:
SergeyBiryukov
Message:

Docs: Add documentation for wp-admin/js/editor.js.

Props terwdan, ireneyoast.
Fixes #38933.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/js/editor.js

    r38594 r39738  
    11
    22( function( $ ) {
     3    /**
     4     * @summary Creates the tinyMCE editors.
     5     *
     6     * Creates the tinyMCE editor and binds all events used for switching
     7     * from visual to text mode.
     8     *
     9     * @since 4.3.0
     10     *
     11     * @class
     12     */
    313    function SwitchEditors() {
    414        var tinymce, $$,
    515            exports = {};
    616
     17        /**
     18         * @summary Initializes the event binding for switching editors.
     19         *
     20         * @since 4.3.0
     21         *
     22         * @returns {void}
     23         */
    724        function init() {
    825            if ( ! tinymce && window.tinymce ) {
     
    1027                $$ = tinymce.$;
    1128
     29                /**
     30                 * @summary Handles onclick events for the editor buttons.
     31                 *
     32                 * @since 4.3.0
     33                 *
     34                 * Handles an onclick event on the document.
     35                 * Switches the editor between visual and text,
     36                 * if the clicked element has the 'wp-switch-editor' class.
     37                 * If the class name is switch-html switches to the HTML editor,
     38                 * if the class name is switch-tmce
     39                 * switches to the TMCE editor.
     40                 *
     41                 * @returns {void}
     42                 */
    1243                $$( document ).on( 'click', function( event ) {
    1344                    var id, mode,
     
    2354        }
    2455
     56        /**
     57         * @summary Retrieves the height of the toolbar based on the container the
     58         * editor is placed in.
     59         *
     60         * @since 3.9.0
     61         *
     62         * @param {Object} editor The tinyMCE editor.
     63         * @returns {number} If the height is between 10 and 200 return the height,
     64         * else return 30.
     65         */
    2566        function getToolbarHeight( editor ) {
    2667            var node = $$( '.mce-toolbar-grp', editor.getContainer() )[0],
     
    3475        }
    3576
     77        /**
     78         * @summary Switches the editor between visual and text.
     79         *
     80         * @since 4.3.0
     81         *
     82         * @memberof switchEditors
     83         *
     84         * @param {string} id The id of the editor you want to change the editor mode for.
     85         * If no id is given, it defaults to content.
     86         * @param {string} mode The mode you want to switch to.
     87         * If an undefined mode is given, it defaults to toggle.
     88         *
     89         * @returns {void}
     90         */
    3691        function switchEditor( id, mode ) {
    3792            id = id || 'content';
     
    4499                textarea = $textarea[0];
    45100
     101            // Toggle the mode between visual and textual representation.
    46102            if ( 'toggle' === mode ) {
    47103                if ( editor && ! editor.isHidden() ) {
     
    52108            }
    53109
     110
     111            // If the mode is tmce or tinymce, show the editor.
    54112            if ( 'tmce' === mode || 'tinymce' === mode ) {
     113
     114                /*
     115                 * If the editor isn't hidden we are already in tmce mode
     116                 * and we don't need to switch.
     117                 * Return false to stop event bubbling.
     118                 */
    55119                if ( editor && ! editor.isHidden() ) {
    56120                    return false;
    57121                }
    58122
     123                // Close the QuickTags toolbars if they are visible.
    59124                if ( typeof( window.QTags ) !== 'undefined' ) {
    60125                    window.QTags.closeAllTags( id );
     
    66131                    editor.show();
    67132
    68                     // No point resizing the iframe in iOS
     133                    // Don't resize the iframe in iOS.
    69134                    if ( ! tinymce.Env.iOS && editorHeight ) {
    70135                        toolbarHeight = getToolbarHeight( editor );
    71136                        editorHeight = editorHeight - toolbarHeight + 14;
    72137
    73                         // height cannot be under 50 or over 5000
     138                        // Height must be between 50 and 5000.
    74139                        if ( editorHeight > 50 && editorHeight < 5000 ) {
    75140                            editor.theme.resizeTo( null, editorHeight );
     
    84149                window.setUserSetting( 'editor', 'tinymce' );
    85150
     151            // Hide the editor if mode is html.
    86152            } else if ( 'html' === mode ) {
     153
     154                /*
     155                 * If the editor is hidden we are already in html mode and
     156                 * we don't need to switch.
     157                 * Return false to stop event bubbling.
     158                 */
    87159                if ( editor && editor.isHidden() ) {
    88160                    return false;
     
    90162
    91163                if ( editor ) {
     164
     165                    // Don't resize the iframe in iOS.
    92166                    if ( ! tinymce.Env.iOS ) {
    93167                        iframe = editor.iframeElement;
     
    98172                            editorHeight = editorHeight + toolbarHeight - 14;
    99173
    100                             // height cannot be under 50 or over 5000
     174                            // Height must be between 50 and 5000.
    101175                            if ( editorHeight > 50 && editorHeight < 5000 ) {
    102176                                textarea.style.height = editorHeight + 'px';
     
    107181                    editor.hide();
    108182                } else {
    109                     // The TinyMCE instance doesn't exist, show the textarea
     183                    // The TinyMCE instance doesn't exist, show the textarea.
    110184                    $textarea.css({ 'display': '', 'visibility': '' });
    111185                }
     
    117191        }
    118192
    119         // Replace paragraphs with double line breaks
     193        /**
     194         * @summary Replaces all paragraphs with double line breaks.
     195         *
     196         * Replaces all paragraphs with double line breaks. Taking into account
     197         * the elements where the <p> should be preserved.
     198         * Unifies all whitespaces.
     199         * Adds indenting with tabs to li, dt and dd elements.
     200         * Trims whitespaces from beginning and end of the html input.
     201         *
     202         * @since 4.3.0
     203         *
     204         * @memberof switchEditors
     205         *
     206         * @param {string} html The content from the editor.
     207         * @return {string} The formatted html string.
     208         */
    120209        function removep( html ) {
    121210            var blocklist = 'blockquote|ul|ol|li|dl|dt|dd|table|thead|tbody|tfoot|tr|th|td|h[1-6]|fieldset',
     
    130219            }
    131220
    132             // Preserve script and style tags.
     221            /*
     222             * Protect script and style tags by replacing them with <wp-preserve>.
     223             * Push matches into the preserve array.
     224             */
    133225            if ( html.indexOf( '<script' ) !== -1 || html.indexOf( '<style' ) !== -1 ) {
    134226                html = html.replace( /<(script|style)[^>]*>[\s\S]*?<\/\1>/g, function( match ) {
     
    138230            }
    139231
    140             // Protect pre tags.
     232            /*
     233             * Protect pre tags by replacing all newlines and
     234             * <br> tags with <wp-line-break>.
     235             */
    141236            if ( html.indexOf( '<pre' ) !== -1 ) {
    142237                preserve_linebreaks = true;
     
    148243            }
    149244
    150             // keep <br> tags inside captions and remove line breaks
     245            /*
     246             * Keep <br> tags inside captions and remove line breaks by replacing
     247             * them with <wp-temp-br>.
     248             */
    151249            if ( html.indexOf( '[caption' ) !== -1 ) {
    152250                preserve_br = true;
     
    156254            }
    157255
    158             // Pretty it up for the source editor
     256            // Format the text to be readable in the source editor.
    159257            html = html.replace( new RegExp( '\\s*</(' + blocklist1 + ')>\\s*', 'g' ), '</$1>\n' );
    160258            html = html.replace( new RegExp( '\\s*<((?:' + blocklist1 + ')(?: [^>]*)?)>', 'g' ), '\n<$1>' );
     
    163261            html = html.replace( /(<p [^>]+>.*?)<\/p>/g, '$1</p#>' );
    164262
    165             // Separate <div> containing <p>
     263            // If the content of a container starts with a paragraph, replace the <p> tag with 2 newlines.
    166264            html = html.replace( /<div( [^>]*)?>\s*<p>/gi, '<div$1>\n\n' );
    167265
    168             // Remove <p> and <br />
     266            // Remove <p> and </p> tags.
    169267            html = html.replace( /\s*<p>/gi, '' );
    170268            html = html.replace( /\s*<\/p>\s*/gi, '\n\n' );
     269
     270            // Remove white spaces between newlines. u00a0 is a no breaking space.
    171271            html = html.replace( /\n[\s\u00a0]+\n/g, '\n\n' );
     272
     273            // Remove <br> tags.
    172274            html = html.replace( /\s*<br ?\/?>\s*/gi, '\n' );
    173275
    174             // Fix some block element newline issues
     276            /*
     277             * Fix some block element newline issues.
     278             * Replace white spaces with newlines in combination with <div> tags.
     279             */
    175280            html = html.replace( /\s*<div/g, '\n<div' );
    176281            html = html.replace( /<\/div>\s*/g, '</div>\n' );
     282
     283            // Replace white spaces with newlines in combination with [caption] shortcodes.
    177284            html = html.replace( /\s*\[caption([^\[]+)\[\/caption\]\s*/gi, '\n\n[caption$1[/caption]\n\n' );
     285
     286            /*
     287             * Limit the newlines in combination with [caption]'s to a maximum of
     288             * two consecutive occurrences.
     289             * .
     290             */
    178291            html = html.replace( /caption\]\n\n+\[caption/g, 'caption]\n\n[caption' );
    179292
     293            /*
     294             * Replace white spaces with newlines in combination with
     295             * all elements listed in blocklist2.
     296             */
    180297            html = html.replace( new RegExp('\\s*<((?:' + blocklist2 + ')(?: [^>]*)?)\\s*>', 'g' ), '\n<$1>' );
    181298            html = html.replace( new RegExp('\\s*</(' + blocklist2 + ')>\\s*', 'g' ), '</$1>\n' );
     299
     300            // Add indentation by adding a tab in front of <li>, <dt> and <dd> tags.
    182301            html = html.replace( /<((li|dt|dd)[^>]*)>/g, ' \t<$1>' );
    183302
     303            // Replace white spaces with newlines in combination with <select> and <option> tags.
    184304            if ( html.indexOf( '<option' ) !== -1 ) {
    185305                html = html.replace( /\s*<option/g, '\n<option' );
     
    187307            }
    188308
     309            // Replace white spaces with 2 newlines in combination with <hr> tags.
    189310            if ( html.indexOf( '<hr' ) !== -1 ) {
    190311                html = html.replace( /\s*<hr( [^>]*)?>\s*/g, '\n\n<hr$1>\n\n' );
    191312            }
    192313
     314            // Remove newlines in <object> tags.
    193315            if ( html.indexOf( '<object' ) !== -1 ) {
    194316                html = html.replace( /<object[\s\S]+?<\/object>/g, function( a ) {
     
    197319            }
    198320
    199             // Unmark special paragraph closing tags
     321            // Unmark special paragraph closing tags.
    200322            html = html.replace( /<\/p#>/g, '</p>\n' );
     323
     324
     325            // Add a new line before <p> tags when there is content inside the paragraph
    201326            html = html.replace( /\s*(<p [^>]+>[\s\S]*?<\/p>)/g, '\n$1' );
    202327
    203             // Trim whitespace
     328            /*
     329             * Remove whitespaces at the start and end of a string.
     330             * u00a0 is a no breaking space.
     331             */
    204332            html = html.replace( /^\s+/, '' );
    205333            html = html.replace( /[\s\u00a0]+$/, '' );
    206334
    207             // put back the line breaks in pre|script
     335            // Replace <wp-line-break> tags with a newline.
    208336            if ( preserve_linebreaks ) {
    209337                html = html.replace( /<wp-line-break>/g, '\n' );
    210338            }
    211339
    212             // and the <br> tags in captions
     340            // Restore the <wp-temp-br> with <br> tags.
    213341            if ( preserve_br ) {
    214342                html = html.replace( /<wp-temp-br([^>]*)>/g, '<br$1>' );
    215343            }
    216344
    217             // Put back preserved tags.
     345            // Restore preserved tags.
    218346            if ( preserve.length ) {
    219347                html = html.replace( /<wp-preserve>/g, function() {
     
    225353        }
    226354
    227         // Similar to `wpautop()` in formatting.php
     355        /**
     356         * @summary Adds paragraph tags to the text.
     357         *
     358         * Adds paragraph tags to the text taking into account block level elements.
     359         * Normalizes the whitespaces and newlines.
     360         *
     361         * Similar to `wpautop()` in formatting.php.
     362         *
     363         * @since 4.3.0
     364         *
     365         * @memberof switchEditors
     366         *
     367         * @param {string} text The text input.
     368         * @returns {string} The formatted text.
     369         */
    228370        function autop( text ) {
    229371            var preserve_linebreaks = false,
    230372                preserve_br = false,
     373
     374                // A list containing all block level elements.
    231375                blocklist = 'table|thead|tfoot|caption|col|colgroup|tbody|tr|td|th|div|dl|dd|dt|ul|ol|li|pre' +
    232376                    '|form|map|area|blockquote|address|math|style|p|h[1-6]|hr|fieldset|legend|section' +
    233377                    '|article|aside|hgroup|header|footer|nav|figure|figcaption|details|menu|summary';
    234378
    235             // Normalize line breaks
     379            // Normalize line breaks.
    236380            text = text.replace( /\r\n|\r/g, '\n' );
    237381
     382            // If there are no newlines, return the text.
    238383            if ( text.indexOf( '\n' ) === -1 ) {
    239384                return text;
     
    241386
    242387            if ( text.indexOf( '<object' ) !== -1 ) {
     388
     389                // If there are multiple newlines in an <object>, remove them.
    243390                text = text.replace( /<object[\s\S]+?<\/object>/g, function( a ) {
    244391                    return a.replace( /\n+/g, '' );
     
    246393            }
    247394
     395            // Replace all new lines and tabs with spaces inside tags.
    248396            text = text.replace( /<[^<>]+>/g, function( a ) {
    249397                return a.replace( /[\n\t ]+/g, ' ' );
    250398            });
    251399
    252             // Protect pre|script tags
     400            // Protect <pre> and <script> tags by replacing them with <wp-line-break>.
    253401            if ( text.indexOf( '<pre' ) !== -1 || text.indexOf( '<script' ) !== -1 ) {
    254402                preserve_linebreaks = true;
     
    258406            }
    259407
    260             // keep <br> tags inside captions and convert line breaks
     408            // Keep <br> tags inside captions.
    261409            if ( text.indexOf( '[caption' ) !== -1 ) {
    262410                preserve_br = true;
     411
     412                // Replace all white spaces and <br> tags with <wp-temp-br>.
    263413                text = text.replace( /\[caption[\s\S]+?\[\/caption\]/g, function( a ) {
    264                     // keep existing <br>
     414
     415                    // Protect <br> tags by converting them to <wp-temp-br> tags.
    265416                    a = a.replace( /<br([^>]*)>/g, '<wp-temp-br$1>' );
    266                     // no line breaks inside HTML tags
     417
     418                    // Replace all new lines and tabs with spaces inside HTML tags.
    267419                    a = a.replace( /<[^<>]+>/g, function( b ) {
     420
     421                        // Replace newlines and tabs with a space.
    268422                        return b.replace( /[\n\t ]+/, ' ' );
    269423                    });
    270                     // convert remaining line breaks to <br>
     424
     425                    // Convert remaining line breaks to <wp-temp-br />.
    271426                    return a.replace( /\s*\n\s*/g, '<wp-temp-br />' );
    272427                });
    273428            }
    274429
     430            // Append 2 newlines at the end of the text.
    275431            text = text + '\n\n';
     432
     433            /*
     434             * Replace a <br> tag followed by 1 or more spaces
     435             * and another <br> tag with 2 newlines.
     436             */
    276437            text = text.replace( /<br \/>\s*<br \/>/gi, '\n\n' );
     438
     439            /*
     440             * Replace a block level element open tag with 2 newlines
     441             * followed by the captured block level element.
     442             */
    277443            text = text.replace( new RegExp( '(<(?:' + blocklist + ')(?: [^>]*)?>)', 'gi' ), '\n\n$1' );
     444
     445            /*
     446             * Replace a block level element closing tag with the captured
     447             * block level element followed by 2 newlines.
     448             */
    278449            text = text.replace( new RegExp( '(</(?:' + blocklist + ')>)', 'gi' ), '$1\n\n' );
    279             text = text.replace( /<hr( [^>]*)?>/gi, '<hr$1>\n\n' ); // hr is self closing block element
    280             text = text.replace( /\s*<option/gi, '<option' ); // No <p> or <br> around <option>
     450
     451            // Add 2 newlines to a <hr> tag. <hr> is a self closing block element.
     452            text = text.replace( /<hr( [^>]*)?>/gi, '<hr$1>\n\n' );
     453
     454            // Remove the spaces before an <option> tag.
     455            text = text.replace( /\s*<option/gi, '<option' );
     456
     457            // Remove the spaces after an <option> closing tag.
    281458            text = text.replace( /<\/option>\s*/gi, '</option>' );
     459
     460            // Remove the spaces between two newlines.
    282461            text = text.replace( /\n\s*\n+/g, '\n\n' );
     462
     463            // Convert 2 newlines to a paragraph and a single newline.
    283464            text = text.replace( /([\s\S]+?)\n\n/g, '<p>$1</p>\n' );
     465
     466            // Remove empty paragraphs.
    284467            text = text.replace( /<p>\s*?<\/p>/gi, '');
     468
     469            // Remove spaces and <p> tags around block level elements.
    285470            text = text.replace( new RegExp( '<p>\\s*(</?(?:' + blocklist + ')(?: [^>]*)?>)\\s*</p>', 'gi' ), '$1' );
     471
     472            // Remove <p> tags around li elements.
    286473            text = text.replace( /<p>(<li.+?)<\/p>/gi, '$1');
     474
     475            // Remove spaces and <p> tags from blockquotes.
    287476            text = text.replace( /<p>\s*<blockquote([^>]*)>/gi, '<blockquote$1><p>');
     477
     478            // Place the <blockquote> outside of the paragraph.
    288479            text = text.replace( /<\/blockquote>\s*<\/p>/gi, '</p></blockquote>');
     480
     481            // Remove spaces at the start and <p> tags from block level elements.
    289482            text = text.replace( new RegExp( '<p>\\s*(</?(?:' + blocklist + ')(?: [^>]*)?>)', 'gi' ), '$1' );
     483
     484            // Remove spaces at the end and <p> tags from block level elements.
    290485            text = text.replace( new RegExp( '(</?(?:' + blocklist + ')(?: [^>]*)?>)\\s*</p>', 'gi' ), '$1' );
    291486
    292             // Remove redundant spaces and line breaks after existing <br /> tags
     487            // Remove spaces and newlines after a <br> tag.
    293488            text = text.replace( /(<br[^>]*>)\s*\n/gi, '$1' );
    294489
    295             // Create <br /> from the remaining line breaks
     490            // Replace spaces followed by a newline with a <br> tag followed by a new line.
    296491            text = text.replace( /\s*\n/g, '<br />\n');
    297492
     493            // Remove <br> tag that follows a block element directly, ignoring spaces.
    298494            text = text.replace( new RegExp( '(</?(?:' + blocklist + ')[^>]*>)\\s*<br />', 'gi' ), '$1' );
     495
     496            /*
     497             * Remove a br tag preceding white spaces followed by a
     498             * <p>, <li>, <div>, <dl>, <dd>, <dt>, <th>, <pre>, <td>, <ul>, or <ol> tag.
     499             */
    299500            text = text.replace( /<br \/>(\s*<\/?(?:p|li|div|dl|dd|dt|th|pre|td|ul|ol)>)/gi, '$1' );
     501
     502            // Remove white spaces, <p> and <br> tags in captions.
    300503            text = text.replace( /(?:<p>|<br ?\/?>)*\s*\[caption([^\[]+)\[\/caption\]\s*(?:<\/p>|<br ?\/?>)*/gi, '[caption$1[/caption]' );
    301504
     505            /**
     506             * @summary Makes sure there is a paragraph open tag for a close tag.
     507             *
     508             * @since 2.9.0
     509             *
     510             * Makes sure there is a paragraph open tag when there is a paragraph close tag
     511             * in a div, th, td, form, fieldset or dd element.
     512             * @param {string} a The complete match.
     513             * @param {string} b The first capture group.
     514             * @param {string} c The second capture group.
     515             * @returns {string} The string in paragraph tags.
     516             */
    302517            text = text.replace( /(<(?:div|th|td|form|fieldset|dd)[^>]*>)(.*?)<\/p>/g, function( a, b, c ) {
     518
     519                /*
     520                 * Check if the matched group has a p open tag in it. If so, we don't need to
     521                 * enclose it with a paragraph.
     522                 */
    303523                if ( c.match( /<p( [^>]*)?>/ ) ) {
    304524                    return a;
    305525                }
    306526
     527                /*
     528                 * If there is no p open tag in the matched string,
     529                 * add it and return the string including p tags.
     530                 */
    307531                return b + '<p>' + c + '</p>';
    308532            });
    309533
    310             // put back the line breaks in pre|script
     534            // Restore the line breaks in <pre> and <script> tags.
    311535            if ( preserve_linebreaks ) {
    312536                text = text.replace( /<wp-line-break>/g, '\n' );
    313537            }
    314538
     539            // Restore the <br> tags in captions.
    315540            if ( preserve_br ) {
    316541                text = text.replace( /<wp-temp-br([^>]*)>/g, '<br$1>' );
     
    320545        }
    321546
    322         // Add old events
     547        /**
     548         * @summary Modifies the data when a switch is made from HTML to text.
     549         *
     550         * Modifies the data when a switch is made.
     551         * Remove the <p> tags from text.
     552         * Returns the modified text.
     553         * Adds a trigger on beforePreWpautop and afterPreWpautop.
     554         *
     555         * @since 2.5.0
     556         *
     557         * @memberof switchEditors
     558         *
     559         * @param {String} html The content from the visual editor.
     560         * @returns {String} the modified text.
     561         */
    323562        function pre_wpautop( html ) {
    324563            var obj = { o: exports, data: html, unfiltered: html };
     
    337576        }
    338577
     578        /**
     579         * @summary Modifies the data when a switch is made from text to HTML.
     580         *
     581         * Modifies the data when a switch is made. Runs autop to add p tags from text.
     582         * Returns the modified text. Adds a trigger on beforeWpautop and afterWpautop.
     583         *
     584         * @since 2.5.0
     585         *
     586         * @memberof switchEditors
     587         *
     588         * @param {String} text The content from the text editor.
     589         * @returns {String} the modified text.
     590         */
    339591        function wpautop( text ) {
    340592            var obj = { o: exports, data: text, unfiltered: text };
     
    353605        }
    354606
     607        // Bind the init function to be run when the document is loaded.
    355608        if ( $ ) {
    356609            $( document ).ready( init );
    357610        } else if ( document.addEventListener ) {
     611
     612            // Use the addEventListener to bind the init event on document load.
    358613            document.addEventListener( 'DOMContentLoaded', init, false );
    359614            window.addEventListener( 'load', init, false );
     615
    360616        } else if ( window.attachEvent ) {
     617
     618            // Use the addEvent to bind the init event on document load.
    361619            window.attachEvent( 'onload', init );
    362620            document.attachEvent( 'onreadystatechange', function() {
     
    367625        }
    368626
     627        /*
     628         * Make sure the window.wp object exists so autop and removep
     629         * can be bound to it.
     630         */
    369631        window.wp = window.wp || {};
    370632        window.wp.editor = window.wp.editor || {};
     
    383645    }
    384646
     647    /**
     648     * @namespace {SwitchEditors} switchEditors
     649     * Expose the switch editors to be used globally.
     650     */
    385651    window.switchEditors = new SwitchEditors();
    386652}( window.jQuery ));
Note: See TracChangeset for help on using the changeset viewer.