WordPress.org

Make WordPress Core

Ticket #41068: editor-expand.js.patch

File editor-expand.js.patch, 33.1 KB (added by jipmoors, 3 years ago)

Documented editor-expand.js

  • src/wp-admin/includes/class-wp-community-events.php

    diff --git src/wp-admin/includes/class-wp-community-events.php src/wp-admin/includes/class-wp-community-events.php
    index cfe12fd52c..211d37ea5e 100644
    class WP_Community_Events { 
    107107                } elseif ( 200 !== $response_code ) {
    108108                        $response_error = new WP_Error(
    109109                                'api-error',
    110                                 /* translators: %s is a numeric HTTP status code; e.g., 400, 403, 500, 504, etc. */
     110                                /* translators: %d: numeric HTTP status code, e.g. 400, 403, 500, 504, etc. */
    111111                                sprintf( __( 'Invalid API response code (%d)' ), $response_code )
    112112                        );
    113113                } elseif ( ! isset( $response_body['location'], $response_body['events'] ) ) {
  • src/wp-admin/js/editor-expand.js

    diff --git src/wp-admin/js/editor-expand.js src/wp-admin/js/editor-expand.js
    index cc3aac4fc5..3a5626c780 100644
     
    66                $adminBar = $( '#wpadminbar' ),
    77                $footer = $( '#wpfooter' );
    88
    9         /* Autoresize editor. */
     9        /**
     10         * @summary Handles the resizing of the editor.
     11         *
     12         * @since 4.0.0
     13         *
     14         * @returns {void}
     15         */
    1016        $( function() {
    1117                var $wrap = $( '#postdivrich' ),
    1218                        $contentWrap = $( '#wp-content-wrap' ),
     
    5359                                sideSortablesHeight: 0
    5460                        };
    5561
     62                /**
     63                 * @summary Resizes textarea based on scroll height and width.
     64                 *
     65                 * Resizes textarea based on scroll height and width. Doesn't shrink the
     66                 * editor size below the 300px auto resize minimum height.
     67                 *
     68                 * @since 4.6.1
     69                 *
     70                 * @returns {void}
     71                 */
    5672                var shrinkTextarea = window._.throttle( function() {
    5773                        var x = window.scrollX || document.documentElement.scrollLeft;
    5874                        var y = window.scrollY || document.documentElement.scrollTop;
     
    7389                        }
    7490                }, 300 );
    7591
     92                /**
     93                 * @summary Resizes the text editor depending on the old text length.
     94                 *
     95                 * If there is an mceEditor and it is hidden, it resizes the editor depending
     96                 * on the old text length. If the current length of the text is smaller than
     97                 * the old text length, it shrinks the text area. Otherwise it resizes the editor to
     98                 * the scroll height.
     99                 *
     100                 * @since 4.6.1
     101                 *
     102                 * @returns {void}
     103                 */
    76104                function textEditorResize() {
    77105                        var length = textEditor.value.length;
    78106
     
    94122                        oldTextLength = length;
    95123                }
    96124
     125                /**
     126                 * @summary Gets the height and widths of elements.
     127                 *
     128                 * Gets the heights of the window, the adminbar, the tools, the menu,
     129                 * the visualTop, the textTop, the bottom, the statusbar and sideSortables
     130                 * and stores these in the heights object. Defaults to 0.
     131                 * Gets the width of the window and stores this in the heights object.
     132                 *
     133                 * @since 4.0.0
     134                 *
     135                 * @returns {void}
     136                 */
    97137                function getHeights() {
    98138                        var windowWidth = $window.width();
    99139
     
    110150                                sideSortablesHeight: $sideSortables.height() || 0
    111151                        };
    112152
    113                         // Adjust for hidden
     153                        // Adjust for hidden menubar.
    114154                        if ( heights.menuBarHeight < 3 ) {
    115155                                heights.menuBarHeight = 0;
    116156                        }
    117157                }
    118158
    119159                // We need to wait for TinyMCE to initialize.
     160                /**
     161                 * @summary Binds all necessary functions for editor expand to the editor
     162                 * when the editor is initialized.
     163                 *
     164                 * @since 4.0.0
     165                 *
     166                 * @param {event} event The TinyMCE editor init event.
     167                 * @param {object} editor The editor to bind the vents on.
     168                 *
     169                 * @returns {void}
     170                 */
    120171                $document.on( 'tinymce-editor-init.editor-expand', function( event, editor ) {
     172                        // VK contains the type of key pressed. VK = virtual keyboard.
    121173                        var VK = window.tinymce.util.VK,
     174                                /**
     175                                 * @summary Hides any float panel with a hover state. Additionally hides tooltips.
     176                                 *
     177                                 * @returns {void}
     178                                 */
    122179                                hideFloatPanels = _.debounce( function() {
    123180                                        ! $( '.mce-floatpanel:hover' ).length && window.tinymce.ui.FloatPanel.hideAll();
    124181                                        $( '.mce-tooltip' ).hide();
     
    141198                        $statusBar = $contentWrap.find( '.mce-statusbar' );
    142199                        $menuBar = $contentWrap.find( '.mce-menubar' );
    143200
     201                        /**
     202                         * @summary Gets the offset of the editor.
     203                         *
     204                         * @returns {Number|Boolean} Returns the offset of the editor
     205                         * or false if there is no offset height.
     206                         */
    144207                        function mceGetCursorOffset() {
    145208                                var node = editor.selection.getNode(),
    146209                                        range, view, offset;
    147210
     211                                /*
     212                                 * If editor.wp.getView and the selection node from the editor selection
     213                                 * are defined, use this as a view for the offset.
     214                                 */
    148215                                if ( editor.wp && editor.wp.getView && ( view = editor.wp.getView( node ) ) ) {
    149216                                        offset = view.getBoundingClientRect();
    150217                                } else {
    151218                                        range = editor.selection.getRng();
    152219
     220                                        // Try to get the offset from a range.
    153221                                        try {
    154222                                                offset = range.getClientRects()[0];
    155223                                        } catch( er ) {}
    156224
     225                                        // Get the offset from the bounding client rectangle of the node.
    157226                                        if ( ! offset ) {
    158227                                                offset = node.getBoundingClientRect();
    159228                                        }
     
    162231                                return offset.height ? offset : false;
    163232                        }
    164233
    165                         // Make sure the cursor is always visible.
    166                         // This is not only necessary to keep the cursor between the toolbars,
    167                         // but also to scroll the window when the cursor moves out of the viewport to a wpview.
    168                         // Setting a buffer > 0 will prevent the browser default.
    169                         // Some browsers will scroll to the middle,
    170                         // others to the top/bottom of the *window* when moving the cursor out of the viewport.
     234                        /**
     235                         * @summary Filters the special keys that should not be used for scrolling.
     236                         *
     237                         * @since 4.0.0
     238                         *
     239                         * @param {event} event The event to get the key code from.
     240                         *
     241                         * @returns {void}
     242                         */
    171243                        function mceKeyup( event ) {
    172244                                var key = event.keyCode;
    173245
    174                                 // Bail on special keys.
     246                                // Bail on special keys. Key code 47 is a /
    175247                                if ( key <= 47 && ! ( key === VK.SPACEBAR || key === VK.ENTER || key === VK.DELETE || key === VK.BACKSPACE || key === VK.UP || key === VK.LEFT || key === VK.DOWN || key === VK.UP ) ) {
    176248                                        return;
    177                                 // OS keys, function keys, num lock, scroll lock
     249                                // OS keys, function keys, num lock, scroll lock. Key code 91-93 are OS keys. Key code 112-123 are F1 to F12. Key code 144 is num lock. Key code 145 is scroll lock.
    178250                                } else if ( ( key >= 91 && key <= 93 ) || ( key >= 112 && key <= 123 ) || key === 144 || key === 145 ) {
    179251                                        return;
    180252                                }
     
    182254                                mceScroll( key );
    183255                        }
    184256
     257                        /**
     258                         * @summary Makes sure the cursor is always visible in the editor.
     259                         *
     260                         * Makes sure the cursor is kept between the toolbars of the editor and scrolls
     261                         * the window when the cursor moves out of the viewport to a wpview.
     262                         * Setting a buffer > 0 will prevent the browser default.
     263                         * Some browsers will scroll to the middle,
     264                         * others to the top/bottom of the *window* when moving the cursor out of the viewport.
     265                         *
     266                         * @since 4.1.0
     267                         *
     268                         * @param {string} key The key code of the pressed key.
     269                         *
     270                         * @returns {void}
     271                         */
    185272                        function mceScroll( key ) {
    186273                                var offset = mceGetCursorOffset(),
    187274                                        buffer = 50,
    188275                                        cursorTop, cursorBottom, editorTop, editorBottom;
    189276
     277                                // Don't scroll if there is no offset.
    190278                                if ( ! offset ) {
    191279                                        return;
    192280                                }
    193281
     282                                // Determine the cursorTop based on the offset and the top of the editor iframe.
    194283                                cursorTop = offset.top + editor.iframeElement.getBoundingClientRect().top;
     284
     285                                // Determine the cursorBottom based on the cursorTop and offset height.
    195286                                cursorBottom = cursorTop + offset.height;
     287
     288                                // Subtract the buffer from the cursorTop.
    196289                                cursorTop = cursorTop - buffer;
     290
     291                                // Add the buffer to the cursorBottom.
    197292                                cursorBottom = cursorBottom + buffer;
    198293                                editorTop = heights.adminBarHeight + heights.toolsHeight + heights.menuBarHeight + heights.visualTopHeight;
     294
     295                                /*
     296                                 * Set the editorBottom based on the window Height, and add the bottomHeight and statusBarHeight if the
     297                                 * advanced editor is enabled.
     298                                 */
    199299                                editorBottom = heights.windowHeight - ( advanced ? heights.bottomHeight + heights.statusBarHeight : 0 );
    200300
    201                                 // Don't scroll if the node is taller than the visible part of the editor
     301                                // Don't scroll if the node is taller than the visible part of the editor.
    202302                                if ( editorBottom - editorTop < offset.height ) {
    203303                                        return;
    204304                                }
    205305
     306                                /*
     307                                 * If the cursorTop is smaller than the editorTop and the up, left
     308                                 * or backspace key is pressed, scroll the editor to the position defined
     309                                 * by the cursorTop, pageYOffset and editorTop.
     310                                 */
    206311                                if ( cursorTop < editorTop && ( key === VK.UP || key === VK.LEFT || key === VK.BACKSPACE ) ) {
    207312                                        window.scrollTo( window.pageXOffset, cursorTop + window.pageYOffset - editorTop );
     313
     314                                /*
     315                                 * If any other key is pressed or the cursorTop is bigger than the editorTop,
     316                                 * scroll the editor to the position defined by the cursorBottom,
     317                                 * pageYOffset and editorBottom.
     318                                 */
    208319                                } else if ( cursorBottom > editorBottom ) {
    209320                                        window.scrollTo( window.pageXOffset, cursorBottom + window.pageYOffset - editorBottom );
    210321                                }
    211322                        }
    212323
     324                        /**
     325                         * @summary If the editor is fullscreen, calls adjust.
     326                         *
     327                         * @since 4.1.0
     328                         *
     329                         * @param {event} event The FullscreenStateChanged event.
     330                         *
     331                         * @returns {void}
     332                         */
    213333                        function mceFullscreenToggled( event ) {
     334                                // event.state is true if the editor is fullscreen.
    214335                                if ( ! event.state ) {
    215336                                        adjust();
    216337                                }
    217338                        }
    218339
    219                         // Adjust when switching editor modes.
     340                        /**
     341                         * @summary Shows the editor when scrolled.
     342                         *
     343                         * Binds the hideFloatPanels function on the window scroll.mce-float-panels event.
     344                         * Executes the wpAutoResize on the active editor.
     345                         *
     346                         * @since 4.0.0
     347                         *
     348                         * @returns {void}
     349                         */
    220350                        function mceShow() {
    221351                                $window.on( 'scroll.mce-float-panels', hideFloatPanels );
    222352
     
    226356                                }, 300 );
    227357                        }
    228358
     359                        /**
     360                         * @summary Resizes the editor.
     361                         *
     362                         * Removes all functions from the window scroll.mce-float-panels event.
     363                         * Resizes the text editor and scrolls to a position based on the pageXOffset and adminBarHeight.
     364                         *
     365                         * @since 4.0.0
     366                         *
     367                         * @returns {void}
     368                         */
    229369                        function mceHide() {
    230370                                $window.off( 'scroll.mce-float-panels' );
    231371
     
    243383                                adjust();
    244384                        }
    245385
     386                        /**
     387                         * @summary Toggles advanced states.
     388                         *
     389                         * @since 4.1.0
     390                         *
     391                         * @returns {void}
     392                         */
    246393                        function toggleAdvanced() {
    247394                                advanced = ! advanced;
    248395                        }
    249396
     397                        /**
     398                         * @summary Binds events of the editor and window.
     399                         *
     400                         * @since 4.0.0
     401                         *
     402                         * @returns {void}
     403                         */
    250404                        mceBind = function() {
    251405                                editor.on( 'keyup', mceKeyup );
    252406                                editor.on( 'show', mceShow );
    253407                                editor.on( 'hide', mceHide );
    254408                                editor.on( 'wp-toolbar-toggle', toggleAdvanced );
     409
    255410                                // Adjust when the editor resizes.
    256411                                editor.on( 'setcontent wp-autoresize wp-toolbar-toggle', adjust );
     412
    257413                                // Don't hide the caret after undo/redo.
    258414                                editor.on( 'undo redo', mceScroll );
     415
    259416                                // Adjust when exiting TinyMCE's fullscreen mode.
    260417                                editor.on( 'FullscreenStateChanged', mceFullscreenToggled );
    261418
    262419                                $window.off( 'scroll.mce-float-panels' ).on( 'scroll.mce-float-panels', hideFloatPanels );
    263420                        };
    264421
     422                        /**
     423                         * @summary Unbinds the events of the editor and window.
     424                         *
     425                         * @since 4.0.0
     426                         *
     427                         * @returns {void}
     428                         */
    265429                        mceUnbind = function() {
    266430                                editor.off( 'keyup', mceKeyup );
    267431                                editor.off( 'show', mceShow );
     
    275439                        };
    276440
    277441                        if ( $wrap.hasClass( 'wp-editor-expand' ) ) {
    278                                 // Adjust "immediately"
     442
     443                                // Adjust "immediately".
    279444                                mceBind();
    280445                                initialResize( adjust );
    281446                        }
    282447                } );
    283448
    284                 // Adjust the toolbars based on the active editor mode.
     449                /**
     450                 * @summary Adjusts the toolbars heights and positions.
     451                 *
     452                 * Adjusts the toolbar heights and positions based on the scroll position on the page,
     453                 * the active editor mode and the heights of the editor, admin bar and side bar.
     454                 *
     455                 * @since 4.0.0
     456                 *
     457                 * @param {event} event The event that calls this function.
     458                 *
     459                 * @returns {void}
     460                 */
    285461                function adjust( event ) {
    286                         // Make sure we're not in fullscreen mode.
     462
     463                        // Makes sure we're not in fullscreen mode.
    287464                        if ( fullscreen && fullscreen.settings.visible ) {
    288465                                return;
    289466                        }
     
    299476                                $top, $editor, sidebarTop, footerTop, canPin,
    300477                                topPos, topHeight, editorPos, editorHeight;
    301478
    302                         // Refresh the heights
     479                        /*
     480                         * Refresh the heights if type isn't 'scroll'
     481                         * or heights.windowHeight isn't set.
     482                         */
    303483                        if ( resize || ! heights.windowHeight ) {
    304484                                getHeights();
    305485                        }
    306486
     487                        // Resize on resize event when the editor is in text mode.
    307488                        if ( ! visual && type === 'resize' ) {
    308489                                textEditorResize();
    309490                        }
     
    318499                                topHeight = heights.textTopHeight;
    319500                        }
    320501
    321                         // TinyMCE still initializing.
     502                        // Return if TinyMCE is still intializing.
    322503                        if ( ! visual && ! $top.length ) {
    323504                                return;
    324505                        }
     
    327508                        editorPos = $editor.offset().top;
    328509                        editorHeight = $editor.outerHeight();
    329510
    330                         // Should we pin?
     511                        /*
     512                         * If in visual mode, checks if the editorHeight is greater than the autoresizeMinHeight + topHeight.
     513                         * If not in visual mode, checks if the editorHeight is greater than the autoresizeMinHeight + 20.
     514                         */
    331515                        canPin = visual ? autoresizeMinHeight + topHeight : autoresizeMinHeight + 20; // 20px from textarea padding
    332516                        canPin = editorHeight > ( canPin + 5 );
    333517
     
    357541                                        $bottom.attr( 'style', '' );
    358542                                }
    359543                        } else {
    360                                 // Maybe pin the top.
     544                                // Check if the top is not already in a fixed position.
    361545                                if ( ( ! fixedTop || resize ) &&
    362                                         // Handle scrolling down.
    363546                                        ( windowPos >= ( topPos - heights.toolsHeight - heights.adminBarHeight ) &&
    364                                         // Handle scrolling up.
    365547                                        windowPos <= ( topPos - heights.toolsHeight - heights.adminBarHeight + editorHeight - buffer ) ) ) {
    366548                                        fixedTop = true;
    367549
     
    384566                                                top: heights.adminBarHeight + heights.toolsHeight + heights.menuBarHeight,
    385567                                                width: contentWrapWidth - ( borderWidth * 2 ) - ( visual ? 0 : ( $top.outerWidth() - $top.width() ) )
    386568                                        } );
    387                                 // Maybe unpin the top.
     569                                        // Check if the top is already in a fixed position.
    388570                                } else if ( fixedTop || resize ) {
    389                                         // Handle scrolling up.
    390571                                        if ( windowPos <= ( topPos - heights.toolsHeight - heights.adminBarHeight ) ) {
    391572                                                fixedTop = false;
    392573
     
    409590                                                        top: heights.menuBarHeight,
    410591                                                        width: contentWrapWidth - ( borderWidth * 2 ) - ( visual ? 0 : ( $top.outerWidth() - $top.width() ) )
    411592                                                } );
    412                                         // Handle scrolling down.
    413593                                        } else if ( windowPos >= ( topPos - heights.toolsHeight - heights.adminBarHeight + editorHeight - buffer ) ) {
    414594                                                fixedTop = false;
    415595
     
    435615                                        }
    436616                                }
    437617
    438                                 // Maybe adjust the bottom bar.
     618                                // Check if the bottom is not already in a fixed position.
    439619                                if ( ( ! fixedBottom || ( resize && advanced ) ) &&
    440                                                 // +[n] for the border around the .wp-editor-container.
     620                                                // Add borderWidth for the border around the .wp-editor-container.
    441621                                                ( windowPos + heights.windowHeight ) <= ( editorPos + editorHeight + heights.bottomHeight + heights.statusBarHeight + borderWidth ) ) {
    442622
    443623                                        if ( event && event.deltaHeight > 0 && event.deltaHeight < 100 ) {
     
    468648                                }
    469649                        }
    470650
    471                         // Sidebar pinning
    472                         if ( $postboxContainer.width() < 300 && heights.windowWidth > 600 && // sidebar position is changed with @media from CSS, make sure it is on the side
    473                                 $document.height() > ( $sideSortables.height() + postBodyTop + 120 ) && // the sidebar is not the tallest element
    474                                 heights.windowHeight < editorHeight ) { // the editor is taller than the viewport
     651                        // The postbox container is positioned with @media from CSS. Ensure it is pinned on the side.
     652                        if ( $postboxContainer.width() < 300 && heights.windowWidth > 600 &&
     653
     654                                // Check if the sidebar is not taller than the document height.
     655                                $document.height() > ( $sideSortables.height() + postBodyTop + 120 ) &&
     656
     657                                // Check if the editor is taller than the viewport.
     658                                heights.windowHeight < editorHeight ) {
    475659
    476660                                if ( ( heights.sideSortablesHeight + pinnedToolsTop + sidebarBottom ) > heights.windowHeight || fixedSideTop || fixedSideBottom ) {
    477                                         // Reset when scrolling to the top
     661
     662                                        // Reset the sideSortables style when scrolling to the top.
    478663                                        if ( windowPos + pinnedToolsTop <= postBodyTop ) {
    479664                                                $sideSortables.attr( 'style', '' );
    480665                                                fixedSideTop = fixedSideBottom = false;
    481666                                        } else {
     667
     668                                                // When scrolling down.
    482669                                                if ( windowPos > lastScrollPosition ) {
    483                                                         // Scrolling down
    484670                                                        if ( fixedSideTop ) {
    485                                                                 // let it scroll
     671
     672                                                                // Let it scroll.
    486673                                                                fixedSideTop = false;
    487674                                                                sidebarTop = $sideSortables.offset().top - heights.adminBarHeight;
    488675                                                                footerTop = $footer.offset().top;
    489676
    490                                                                 // don't get over the footer
     677                                                                // Don't get over the footer.
    491678                                                                if ( footerTop < sidebarTop + heights.sideSortablesHeight + sidebarBottom ) {
    492679                                                                        sidebarTop = footerTop - heights.sideSortablesHeight - 12;
    493680                                                                }
     
    498685                                                                        bottom: ''
    499686                                                                });
    500687                                                        } else if ( ! fixedSideBottom && heights.sideSortablesHeight + $sideSortables.offset().top + sidebarBottom < windowPos + heights.windowHeight ) {
    501                                                                 // pin the bottom
     688                                                                // Pin the bottom.
    502689                                                                fixedSideBottom = true;
    503690
    504691                                                                $sideSortables.css({
     
    507694                                                                        bottom: sidebarBottom
    508695                                                                });
    509696                                                        }
     697
     698                                                // When scrolling up.
    510699                                                } else if ( windowPos < lastScrollPosition ) {
    511                                                         // Scrolling up
    512700                                                        if ( fixedSideBottom ) {
    513                                                                 // let it scroll
     701                                                                // Let it scroll.
    514702                                                                fixedSideBottom = false;
    515703                                                                sidebarTop = $sideSortables.offset().top - sidebarBottom;
    516704                                                                footerTop = $footer.offset().top;
    517705
    518                                                                 // don't get over the footer
     706                                                                // Don't get over the footer.
    519707                                                                if ( footerTop < sidebarTop + heights.sideSortablesHeight + sidebarBottom ) {
    520708                                                                        sidebarTop = footerTop - heights.sideSortablesHeight - 12;
    521709                                                                }
     
    526714                                                                        bottom: ''
    527715                                                                });
    528716                                                        } else if ( ! fixedSideTop && $sideSortables.offset().top >= windowPos + pinnedToolsTop ) {
    529                                                                 // pin the top
     717                                                                // Pin the top.
    530718                                                                fixedSideTop = true;
    531719
    532720                                                                $sideSortables.css({
     
    538726                                                }
    539727                                        }
    540728                                } else {
    541                                         // if the sidebar container is smaller than the viewport, then pin/unpin the top when scrolling
     729                                        // If the sidebar container is smaller than the viewport, then pin/unpin the top when scrolling.
    542730                                        if ( windowPos >= ( postBodyTop - pinnedToolsTop ) ) {
    543731
    544732                                                $sideSortables.css( {
     
    575763                        }
    576764                }
    577765
     766                /**
     767                 * @summary Resizes the editor and adjusts the toolbars.
     768                 *
     769                 * @since 4.0.0
     770                 *
     771                 * @returns {void}
     772                 */
    578773                function fullscreenHide() {
    579774                        textEditorResize();
    580775                        adjust();
    581776                }
    582777
     778                /**
     779                 * @summary Runs the passed function with 500ms intervals.
     780                 *
     781                 * @since 4.0.0
     782                 *
     783                 * @param {function} callback The function to run in the timeout.
     784                 *
     785                 * @returns {void}
     786                 */
    583787                function initialResize( callback ) {
    584788                        for ( var i = 1; i < 6; i++ ) {
    585789                                setTimeout( callback, 500 * i );
    586790                        }
    587791                }
    588792
     793                /**
     794                 * @summary Runs adjust after 100ms.
     795                 *
     796                 * @since 4.0.0
     797                 *
     798                 * @returns {void}
     799                 */
    589800                function afterScroll() {
    590801                        clearTimeout( scrollTimer );
    591802                        scrollTimer = setTimeout( adjust, 100 );
    592803                }
    593804
     805                /**
     806                 * @summary Binds editor expand events on elements.
     807                 *
     808                 * @since 4.0.0
     809                 *
     810                 * @returns {void}
     811                 */
    594812                function on() {
    595                         // Scroll to the top when triggering this from JS.
    596                         // Ensures toolbars are pinned properly.
     813                        /*
     814                         * Scroll to the top when triggering this from JS.
     815                         * Ensure the toolbars are pinned properly.
     816                         */
    597817                        if ( window.pageYOffset && window.pageYOffset > pageYOffsetAtTop ) {
    598818                                window.scrollTo( window.pageXOffset, 0 );
    599819                        }
     
    606826                                afterScroll();
    607827                        } );
    608828
    609                         // Adjust when collapsing the menu, changing the columns, changing the body class.
     829                        /*
     830                         * Adjust when collapsing the menu, changing the columns
     831                         * or changing the body class.
     832                         */
    610833                        $document.on( 'wp-collapse-menu.editor-expand postboxes-columnchange.editor-expand editor-classchange.editor-expand', adjust )
    611834                                .on( 'postbox-toggled.editor-expand postbox-moved.editor-expand', function() {
    612835                                        if ( ! fixedSideTop && ! fixedSideBottom && window.pageYOffset > pinnedToolsTop ) {
     
    628851                        $textEditor.on( 'focus.editor-expand input.editor-expand propertychange.editor-expand', textEditorResize );
    629852                        mceBind();
    630853
    631                         // Adjust when entering/exiting fullscreen mode.
     854                        // Adjust when entering or exiting fullscreen mode.
    632855                        fullscreen && fullscreen.pubsub.subscribe( 'hidden', fullscreenHide );
    633856
    634857                        if ( mceEditor ) {
     
    649872                        $document.trigger( 'editor-expand-on' );
    650873                }
    651874
     875                /**
     876                 * @summary Unbinds editor expand events.
     877                 *
     878                 * @since 4.0.0
     879                 *
     880                 * @returns {void}
     881                 */
    652882                function off() {
    653883                        var height = parseInt( window.getUserSetting( 'ed_size', 300 ), 10 );
    654884
     
    658888                                height = 5000;
    659889                        }
    660890
    661                         // Scroll to the top when triggering this from JS.
    662                         // Ensures toolbars are reset properly.
     891                        /*
     892                         * Scroll to the top when triggering this from JS.
     893                         * Ensure the toolbars are reset properly.
     894                         */
    663895                        if ( window.pageYOffset && window.pageYOffset > pageYOffsetAtTop ) {
    664896                                window.scrollTo( window.pageXOffset, 0 );
    665897                        }
     
    671903                        $textEditor.off( '.editor-expand' );
    672904                        mceUnbind();
    673905
    674                         // Adjust when entering/exiting fullscreen mode.
     906                        // Adjust when entering or exiting fullscreen mode.
    675907                        fullscreen && fullscreen.pubsub.unsubscribe( 'hidden', fullscreenHide );
    676908
    677909                        // Reset all css
     
    694926                                }
    695927                        }
    696928
     929                        // If there is a height found in the user setting.
    697930                        if ( height ) {
    698931                                $textEditor.height( height );
    699932                        }
     
    701934                        $document.trigger( 'editor-expand-off' );
    702935                }
    703936
    704                 // Start on load
     937                // Start on load.
    705938                if ( $wrap.hasClass( 'wp-editor-expand' ) ) {
    706939                        on();
    707940
    708                         // Ideally we need to resize just after CSS has fully loaded and QuickTags is ready.
     941                        // Resize just after CSS has fully loaded and QuickTags is ready.
    709942                        if ( $contentWrap.hasClass( 'html-active' ) ) {
    710943                                initialResize( function() {
    711944                                        adjust();
     
    714947                        }
    715948                }
    716949
    717                 // Show the on/off checkbox
     950                // Show the on/off checkbox.
    718951                $( '#adv-settings .editor-expand' ).show();
    719952                $( '#editor-expand-toggle' ).on( 'change.editor-expand', function() {
    720953                        if ( $(this).prop( 'checked' ) ) {
     
    726959                        }
    727960                });
    728961
    729                 // Expose on() and off()
     962                // Expose on() and off().
    730963                window.editorExpand = {
    731964                        on: on,
    732965                        off: off
    733966                };
    734967        } );
    735968
    736         /* DFW. */
     969        /**
     970         * @summary Handles the distraction free writing of TinyMCE.
     971         *
     972         * @since 4.1.0
     973         *
     974         * @returns {void}
     975         */
    737976        $( function() {
    738977                var $body = $( document.body ),
    739978                        $wrap = $( '#wpcontent' ),
     
    7771016                        mouseY = event.pageY;
    7781017                } );
    7791018
     1019                /**
     1020                 * @summary Recalculates the bottom and right position of the editor in the DOM.
     1021                 *
     1022                 * @since 4.1.0
     1023                 *
     1024                 * @returns {void}
     1025                 */
    7801026                function recalcEditorRect() {
    7811027                        editorRect = $editor.offset();
    7821028                        editorRect.right = editorRect.left + $editor.outerWidth();
    7831029                        editorRect.bottom = editorRect.top + $editor.outerHeight();
    7841030                }
    7851031
     1032                /**
     1033                 * @summary Activates the distraction free writing mode.
     1034                 *
     1035                 * @since 4.1.0
     1036                 *
     1037                 * @returns {void}
     1038                 */
    7861039                function activate() {
    7871040                        if ( ! _isActive ) {
    7881041                                _isActive = true;
     
    7921045                        }
    7931046                }
    7941047
     1048                /**
     1049                 * @summary Deactivates the distraction free writing mode.
     1050                 *
     1051                 * @since 4.1.0
     1052                 *
     1053                 * @returns {void}
     1054                 */
    7951055                function deactivate() {
    7961056                        if ( _isActive ) {
    7971057                                off();
     
    8031063                        }
    8041064                }
    8051065
     1066                /**
     1067                 * @summary Returns _isActive.
     1068                 *
     1069                 * @since 4.1.0
     1070                 *
     1071                 * @returns {boolean} Returns true is _isActive is true.
     1072                 */
    8061073                function isActive() {
    8071074                        return _isActive;
    8081075                }
    8091076
     1077                /**
     1078                 * @summary Binds events on the editor for distraction free writing.
     1079                 *
     1080                 * @since 4.1.0
     1081                 *
     1082                 * @returns {void}
     1083                 */
    8101084                function on() {
    8111085                        if ( ! _isOn && _isActive ) {
    8121086                                _isOn = true;
     
    8231097                        }
    8241098                }
    8251099
     1100                /**
     1101                 * @summary Unbinds events on the editor for distraction free writing.
     1102                 *
     1103                 * @since 4.1.0
     1104                 *
     1105                 * @returns {void}
     1106                 */
    8261107                function off() {
    8271108                        if ( _isOn ) {
    8281109                                _isOn = false;
     
    8391120                        }
    8401121                }
    8411122
     1123                /**
     1124                 * @summary Binds or unbinds the editor expand events.
     1125                 *
     1126                 * @since 4.1.0
     1127                 *
     1128                 * @returns {void}
     1129                 */
    8421130                function toggle() {
    8431131                        if ( _isOn ) {
    8441132                                off();
     
    8471135                        }
    8481136                }
    8491137
     1138                /**
     1139                 * @summary Returns the value of _isOn.
     1140                 *
     1141                 * @since 4.1.0
     1142                 *
     1143                 * @returns {boolean} Returns true if _isOn is true.
     1144                 */
    8501145                function isOn() {
    8511146                        return _isOn;
    8521147                }
    8531148
     1149                /**
     1150                 * @summary Fades out all elements except for the editor.
     1151                 *
     1152                 * The fading is done based on key presses and mouse movements.
     1153                 * Also calls the fadeIn on certain key presses
     1154                 * or if the mouse leaves the editor.
     1155                 *
     1156                 * @since 4.1.0
     1157                 *
     1158                 * @param event The event that triggers this function.
     1159                 *
     1160                 * @returns {void}
     1161                 */
    8541162                function fadeOut( event ) {
    8551163                        var isMac,
    8561164                                key = event && event.keyCode;
     
    8591167                                isMac = ( window.navigator.platform.indexOf( 'Mac' ) > -1 );
    8601168                        }
    8611169
    862                         // fadeIn and return on Escape and keyboard shortcut Alt+Shift+W and Ctrl+Opt+W.
     1170                        // Fade in and returns on Escape and keyboard shortcut Alt+Shift+W and Ctrl+Opt+W.
    8631171                        if ( key === 27 || ( key === 87 && event.altKey && ( ( ! isMac && event.shiftKey ) || ( isMac && event.ctrlKey ) ) ) ) {
    8641172                                fadeIn( event );
    8651173                                return;
    8661174                        }
    8671175
     1176                        // Return if any of the following keys or combinations of keys is pressed.
    8681177                        if ( event && ( event.metaKey || ( event.ctrlKey && ! event.altKey ) || ( event.altKey && event.shiftKey ) || ( key && (
    8691178                                // Special keys ( tab, ctrl, alt, esc, arrow keys... )
    8701179                                ( key <= 47 && key !== 8 && key !== 13 && key !== 32 && key !== 46 ) ||
     
    8921201                                $editor.css( 'z-index', 9998 );
    8931202
    8941203                                $overlay
    895                                         // Always recalculate the editor area entering the overlay with the mouse.
     1204                                        // Always recalculate the editor area when entering the overlay with the mouse.
    8961205                                        .on( 'mouseenter.focus', function() {
    8971206                                                recalcEditorRect();
    8981207
     
    9591268                                                x = nx;
    9601269                                                y = ny;
    9611270                                        } )
    962                                         // When the overlay is touched, always fade in and cancel the event.
     1271
     1272                                        // When the overlay is touched, fade in and cancel the event.
    9631273                                        .on( 'touchstart.focus', function( event ) {
    9641274                                                event.preventDefault();
    9651275                                                fadeIn();
     
    9791289                        fadeOutSlug();
    9801290                }
    9811291
     1292                /**
     1293                 * @summary Fades all elements back in.
     1294                 *
     1295                 * @since 4.1.0
     1296                 *
     1297                 * @param event The event that triggers this function.
     1298                 *
     1299                 * @returns {void}
     1300                 */
    9821301                function fadeIn( event ) {
    9831302                        if ( faded ) {
    9841303                                faded = false;
     
    10181337                        fadeInSlug();
    10191338                }
    10201339
     1340                /**
     1341                 * @summary Fades in if the focused element based on it position.
     1342                 *
     1343                 * @since 4.1.0
     1344                 *
     1345                 * @returns {void}
     1346                 */
    10211347                function maybeFadeIn() {
    10221348                        setTimeout( function() {
    10231349                                var position = document.activeElement.compareDocumentPosition( $editor.get( 0 ) );
     
    10331359                        }, 0 );
    10341360                }
    10351361
     1362                /**
     1363                 * @summary Fades out the admin bar based on focus on the admin bar.
     1364                 *
     1365                 * @since 4.1.0
     1366                 *
     1367                 * @returns {void}
     1368                 */
    10361369                function fadeOutAdminBar() {
    10371370                        if ( ! fadedAdminBar && faded ) {
    10381371                                fadedAdminBar = true;
     
    10471380                        }
    10481381                }
    10491382
     1383                /**
     1384                 * @summary Fades in the admin bar.
     1385                 *
     1386                 * @since 4.1.0
     1387                 *
     1388                 * @returns {void}
     1389                 */
    10501390                function fadeInAdminBar() {
    10511391                        if ( fadedAdminBar ) {
    10521392                                fadedAdminBar = false;
     
    10551395                        }
    10561396                }
    10571397
     1398                /**
     1399                 * @summary Fades out the edit slug box.
     1400                 *
     1401                 * @since 4.1.0
     1402                 *
     1403                 * @returns {void}
     1404                 */
    10581405                function fadeOutSlug() {
    10591406                        if ( ! fadedSlug && faded && ! $slug.find( ':focus').length ) {
    10601407                                fadedSlug = true;
     
    10651412                        }
    10661413                }
    10671414
     1415                /**
     1416                 * @summary Fades in the edit slug box.
     1417                 *
     1418                 * @since 4.1.0
     1419                 *
     1420                 * @returns {void}
     1421                 */
    10681422                function fadeInSlug() {
    10691423                        if ( fadedSlug ) {
    10701424                                fadedSlug = false;
     
    10751429                        }
    10761430                }
    10771431
     1432                /**
     1433                 * @summary Triggers the toggle on Alt + Shift + W.
     1434                 *
     1435                 * Keycode 87 = w.
     1436                 *
     1437                 * @since 4.1.0
     1438                 *
     1439                 * @param {event} event The event to trigger the toggle.
     1440                 *
     1441                 * @returns {void}
     1442                 */
    10781443                function toggleViaKeyboard( event ) {
    10791444                        if ( event.altKey && event.shiftKey && 87 === event.keyCode ) {
    10801445                                toggle();
     
    10851450                        $content.on( 'keydown.focus-shortcut', toggleViaKeyboard );
    10861451                }
    10871452
     1453                /**
     1454                 * @summary Adds the distraction free writing button when setting up TinyMCE.
     1455                 *
     1456                 * @since 4.1.0
     1457                 *
     1458                 * @param {event} event The TinyMCE editor setup event.
     1459                 * @param {object} editor The editor to add the button to.
     1460                 *
     1461                 * @returns {void}
     1462                 */
    10881463                $document.on( 'tinymce-editor-setup.focus', function( event, editor ) {
    10891464                        editor.addButton( 'dfw', {
    10901465                                active: _isOn,
     
    11161491                        editor.addShortcut( 'access+w', '', 'wpToggleDFW' );
    11171492                } );
    11181493
     1494                /**
     1495                 * @summary Binds and unbinds events on the editor.
     1496                 *
     1497                 * @since 4.1.0
     1498                 *
     1499                 * @param {event} event The TinyMCE editor init event.
     1500                 * @param {object} editor The editor to bind events on.
     1501                 *
     1502                 * @returns {void}
     1503                 */
    11191504                $document.on( 'tinymce-editor-init.focus', function( event, editor ) {
    11201505                        var mceBind, mceUnbind;
    11211506
     
    11511536                                        mceBind();
    11521537                                }
    11531538
     1539                                // Bind and unbind based on the distraction free writing focus.
    11541540                                $document.on( 'dfw-on.focus', mceBind ).on( 'dfw-off.focus', mceUnbind );
    11551541
    1156                                 // Make sure the body focuses when clicking outside it.
     1542                                // Focuse the editor when it is the target of the click event.
    11571543                                editor.on( 'click', function( event ) {
    11581544                                        if ( event.target === editor.getDoc().documentElement ) {
    11591545                                                editor.focus();
     
    11621548                        }
    11631549                } );
    11641550
     1551                /**
     1552                 * @summary  Binds events on quicktags init.
     1553                 *
     1554                 * @since 4.1.0
     1555                 *
     1556                 * @param {event} event The quicktags init event.
     1557                 * @param {object} editor The editor to bind events on.
     1558                 *
     1559                 * @returns {void}
     1560                 */
    11651561                $document.on( 'quicktags-init', function( event, editor ) {
    11661562                        var $button;
    11671563
     1564                        // Bind the distraction free writing events if the distraction free writing button is available.
    11681565                        if ( editor.settings.buttons && ( ',' + editor.settings.buttons + ',' ).indexOf( ',dfw,' ) !== -1 ) {
    11691566                                $button = $( '#' + editor.name + '_dfw' );
    11701567
  • src/wp-content/themes/twentysixteen/inc/template-tags.php

    diff --git src/wp-content/themes/twentysixteen/inc/template-tags.php src/wp-content/themes/twentysixteen/inc/template-tags.php
    index eb87203062..fa1ad8efed 100644
    function twentysixteen_categorized_blog() { 
    213213                set_transient( 'twentysixteen_categories', $all_the_cool_cats );
    214214        }
    215215
    216         if ( $all_the_cool_cats > 1 ) {
     216        if ( $all_the_cool_cats > 1 || is_preview() ) {
    217217                // This blog has more than 1 category so twentysixteen_categorized_blog should return true.
    218218                return true;
    219219        } else {
  • src/wp-includes/class-wp-editor.php

    diff --git src/wp-includes/class-wp-editor.php src/wp-includes/class-wp-editor.php
    index 8879797914..73de84de2b 100644
    final class _WP_Editors { 
    144144         * @static
    145145         * @param string $content The initial content of the editor.
    146146         * @param string $editor_id ID for the textarea and TinyMCE and Quicktags instances (can contain only ASCII letters and numbers).
    147          * @param array $settings See the _parse_settings() method for description.
     147         * @param array $settings See _WP_Editors()::parse_settings() for description.
    148148         */
    149149        public static function editor( $content, $editor_id, $settings = array() ) {
    150150                $set = self::parse_settings( $editor_id, $settings );
  • src/wp-includes/functions.php

    diff --git src/wp-includes/functions.php src/wp-includes/functions.php
    index 966dcd8265..828f123491 100644
    function date_i18n( $dateformatstring, $unixtimestamp = false, $gmt = false ) { 
    158158 *
    159159 * @since 4.4.0
    160160 *
     161 * @global WP_Locale $wp_locale
     162 *
    161163 * @param string $date Formatted date string.
    162164 * @return string The date, declined if locale specifies it.
    163165 */
  • src/wp-includes/vars.php

    diff --git src/wp-includes/vars.php src/wp-includes/vars.php
    index 2e97c9a0ae..89b3532327 100644
    function wp_is_mobile() { 
    139139                $is_mobile = false;
    140140        }
    141141
    142         return $is_mobile;
     142        /**
     143         * Filters whether the request should be treated as coming from a mobile device or not.
     144         *
     145         * @since 4.9.0
     146         *
     147         * @param bool $is_mobile Whether the request is from a mobile device or not.
     148         */
     149        return apply_filters( 'wp_is_mobile', $is_mobile );
    143150}
  • src/wp-includes/wp-db.php

    diff --git src/wp-includes/wp-db.php src/wp-includes/wp-db.php
    index 74dedd5130..2c9cceabf7 100644
    class wpdb { 
    32683268         *
    32693269         * @param string $db_cap The feature to check for. Accepts 'collation',
    32703270         *                       'group_concat', 'subqueries', 'set_charset',
    3271          *                       or 'utf8mb4'.
     3271         *                       'utf8mb4', or 'utf8mb4_520'.
    32723272         * @return int|false Whether the database feature is supported, false otherwise.
    32733273         */
    32743274        public function has_cap( $db_cap ) {