WordPress.org

Make WordPress Core

Ticket #42679: common.diff

File common.diff, 29.8 KB (added by andizer, 3 years ago)
  • src/wp-admin/js/common.js

    diff --git src/wp-admin/js/common.js src/wp-admin/js/common.js
    index d8748f53a..2b735ebed 100644
     
    11/* global setUserSetting, ajaxurl, commonL10n, alert, confirm, pagenow */
    22var showNotice, adminMenu, columns, validateForm, screenMeta;
     3/**
     4 *  @summary Adds common WordPress functionality to the window.
     5 *
     6 *  @param {jQuery} $        jQuery object.
     7 *  @param {Object} window   The window object.
     8 *  @param {mixed} undefined Unused.
     9 */
    310( function( $, window, undefined ) {
    411        var $document = $( document ),
    512                $window = $( window ),
    613                $body = $( document.body );
    714
    8 // Removed in 3.3.
    9 // (perhaps) needed for back-compat
     15/**
     16 * @summary Removed in 3.3.0, needed for back-compatibility.
     17 *
     18 * @since 2.7.0
     19 * @deprecated 3.3.0
     20 */
    1021adminMenu = {
    1122        init : function() {},
    1223        fold : function() {},
    adminMenu = { 
    1526        favorites : function() {}
    1627};
    1728
    18 // show/hide/save table columns
     29// Show/hide/save table columns.
    1930columns = {
     31        /**
     32         * @summary Initializes the column toggles in the screen options.
     33         *
     34         * Binds an onClick event to the checkboxes to show or hide the table columns
     35         * based on their toggled state. And persists the toggled state.
     36         *
     37         * @since 2.7.0
     38         *
     39         * @returns {void}
     40         */
    2041        init : function() {
    2142                var that = this;
    2243                $('.hide-column-tog', '#adv-settings').click( function() {
    columns = { 
    2950                        columns.saveManageColumnsState();
    3051                });
    3152        },
    32 
     53        /**
     54         * @summary Saves the toggled state for the columns.
     55         *
     56         * Saves whether the columns should be shown or hidden on a page.
     57         *
     58         * @since 3.0.0
     59         *
     60         * @returns {void}
     61         */
    3362        saveManageColumnsState : function() {
    3463                var hidden = this.hidden();
    3564                $.post(ajaxurl, {
    columns = { 
    4069                });
    4170        },
    4271
     72        /**
     73         * @summary Makes a column visible and adjusts the column span for the table.
     74         *
     75         * @since 3.0.0
     76         * @param {string} column The column name.
     77         *
     78         * @returns {void}
     79         */
    4380        checked : function(column) {
    4481                $('.column-' + column).removeClass( 'hidden' );
    4582                this.colSpanChange(+1);
    4683        },
    4784
     85        /**
     86         * @summary Hides a column and adjusts the column span for the table.
     87         *
     88         * @since 3.0.0
     89         * @param {string} column The column name.
     90         *
     91         * @returns {void}
     92         */
    4893        unchecked : function(column) {
    4994                $('.column-' + column).addClass( 'hidden' );
    5095                this.colSpanChange(-1);
    5196        },
    5297
     98        /**
     99         * @summary Get all hidden columns.
     100         *
     101         * @since 3.0.0
     102         *
     103         * @returns {string} The hidden column names separated by a comma.
     104         */
    53105        hidden : function() {
    54106                return $( '.manage-column[id]' ).filter( ':hidden' ).map(function() {
    55107                        return this.id;
    56108                }).get().join( ',' );
    57109        },
    58110
     111        /**
     112         * @summary Gets the checked column toggles from the screen options.
     113         *
     114         * @since 3.0.0
     115         *
     116         * @returns {string} String containing the checked column names.
     117         */
    59118        useCheckboxesForHidden : function() {
    60119                this.hidden = function(){
    61120                        return $('.hide-column-tog').not(':checked').map(function() {
    columns = { 
    65124                };
    66125        },
    67126
     127        /**
     128         * @summary Adjusts the column span for the table.
     129         *
     130         * @since 3.1.0
     131         *
     132         * @param {int} diff The modifier for the column span.
     133         */
    68134        colSpanChange : function(diff) {
    69135                var $t = $('table').find('.colspanchange'), n;
    70136                if ( !$t.length )
    columns = { 
    75141};
    76142
    77143$document.ready(function(){columns.init();});
    78 
     144/**
     145 * @summary Validates that the required form fields are not empty.
     146 *
     147 * @since 2.9.0
     148 *
     149 * @param {jQuery} form The form to validate.
     150 *
     151 * @returns {boolean} Returns true if all required fields are not an empty string.
     152 */
    79153validateForm = function( form ) {
    80154        return !$( form )
    81155                .find( '.form-required' )
    validateForm = function( form ) { 
    87161};
    88162
    89163// stub for doing better warnings
     164/**
     165 * @summary Shows message pop-up notice or confirmation message.
     166 *
     167 * @since 2.7.0
     168 *
     169 * @type {{warn: showNotice.warn, note: showNotice.note}}
     170 *
     171 * @returns {void}
     172 */
    90173showNotice = {
     174        /**
     175         * @summary Shows a delete confirmation pop-up message.
     176         *
     177         * @since 2.7.0
     178         *
     179         * @returns {boolean} Returns true if the message is confirmed.
     180         */
    91181        warn : function() {
    92182                var msg = commonL10n.warnDelete || '';
    93183                if ( confirm(msg) ) {
    showNotice = { 
    97187                return false;
    98188        },
    99189
     190        /**
     191         * @summary Shows an alert message.
     192         *
     193         * @since 2.7.0
     194         *
     195         * @param text The text to display in the message.
     196         */
    100197        note : function(text) {
    101198                alert(text);
    102199        }
    103200};
    104201
     202/**
     203 * @summary Represents the functions for the meta screen options panel.
     204 *
     205 * @since 3.2.0
     206 *
     207 * @type {{element: null, toggles: null, page: null, init: screenMeta.init,
     208 *         toggleEvent: screenMeta.toggleEvent, open: screenMeta.open,
     209 *         close: screenMeta.close}}
     210 *
     211 * @returns {void}
     212 */
    105213screenMeta = {
    106214        element: null, // #screen-meta
    107215        toggles: null, // .screen-meta-toggle
    108216        page:    null, // #wpcontent
    109217
     218        /**
     219         * @summary Initializes the screen meta options panel.
     220         *
     221         * @since 3.2.0
     222         *
     223         * @returns {void}
     224         */
    110225        init: function() {
    111226                this.element = $('#screen-meta');
    112227                this.toggles = $( '#screen-meta-links' ).find( '.show-settings' );
    screenMeta = { 
    115230                this.toggles.click( this.toggleEvent );
    116231        },
    117232
     233        /**
     234         * @summary Toggles the screen meta options panel.
     235         *
     236         * @since 3.2.0
     237         *
     238         * @returns {void}
     239         */
    118240        toggleEvent: function() {
    119241                var panel = $( '#' + $( this ).attr( 'aria-controls' ) );
    120242
    screenMeta = { 
    127249                        screenMeta.open( panel, $(this) );
    128250        },
    129251
     252        /**
     253         * @summary Opens the screen meta options panel.
     254         *
     255         * @since 3.2.0
     256         *
     257         * @param {jQuery} panel  The screen meta options panel div.
     258         * @param {jQuery} button The toggle button.
     259         *
     260         * @returns {void}
     261         */
    130262        open: function( panel, button ) {
    131263
    132264                $( '#screen-meta-links' ).find( '.screen-meta-toggle' ).not( button.parent() ).css( 'visibility', 'hidden' );
    133265
    134266                panel.parent().show();
     267                /**
     268                 * @summary Sets the focus to the meta options panel and adds the necessary CSS classes.
     269                 *
     270                 * @since 3.2.0
     271                 *
     272                 * @returns {void}
     273                 */
    135274                panel.slideDown( 'fast', function() {
    136275                        panel.focus();
    137276                        button.addClass( 'screen-meta-active' ).attr( 'aria-expanded', true );
    screenMeta = { 
    140279                $document.trigger( 'screen:options:open' );
    141280        },
    142281
     282        /**
     283         * @summary Closes the screen meta options panel.
     284         *
     285         * @since 3.2.0
     286         *
     287         * @param {jQuery} panel  The screen meta options panel div.
     288         * @param {jQuery} button The toggle button.
     289         *
     290         * @returns {void}
     291         */
    143292        close: function( panel, button ) {
     293                /**
     294                 * @summary Hides the screen meta options panel.
     295                 *
     296                 * @since 3.2.0
     297                 *
     298                 * @returns {void}
     299                 */
    144300                panel.slideUp( 'fast', function() {
    145301                        button.removeClass( 'screen-meta-active' ).attr( 'aria-expanded', false );
    146302                        $('.screen-meta-toggle').css('visibility', '');
    screenMeta = { 
    152308};
    153309
    154310/**
    155  * Help tabs.
     311 * @summary Initializes the help tabs in the help panel.
     312 *
     313 * @param {Event} e The event object.
     314 *
     315 * @returns {void}
    156316 */
    157317$('.contextual-help-tabs').delegate('a', 'click', function(e) {
    158318        var link = $(this),
    $document.ready( function() { 
    330490                $headerEnd = $( '.wp-header-end' );
    331491
    332492
    333         // when the menu is folded, make the fly-out submenu header clickable
     493        /**
     494         * @summary Makes the fly-out submenu header clickable, when the menu is folded.
     495         *
     496         * @param {Event} e The event object.
     497         *
     498         * @returns {void}
     499         */
    334500        $adminmenu.on('click.wp-submenu-head', '.wp-submenu-head', function(e){
    335501                $(e.target).parent().siblings('a').get(0).click();
    336502        });
    337503
     504        /**
     505         * @summary Collapses the admin menu.
     506         *
     507         * @returns {void}
     508         */
    338509        $( '#collapse-button' ).on( 'click.collapse-menu', function() {
    339510                var viewportWidth = getViewportWidth() || 961;
    340511
    $document.ready( function() { 
    367538                $document.trigger( 'wp-collapse-menu', { state: menuState } );
    368539        });
    369540
    370         // Handle the `aria-haspopup` attribute on the current menu item when it has a sub-menu.
     541        /**
     542         * @summary Handles the `aria-haspopup` attribute on the current menu item when it has a submenu.
     543         *
     544         * @since 4.4.0
     545         *
     546         * @returns {void}
     547         */
    371548        function currentMenuItemHasPopup() {
    372549                var $current = $( 'a.wp-has-current-submenu' );
    373550
    $document.ready( function() { 
    383560        $document.on( 'wp-menu-state-set wp-collapse-menu wp-responsive-activate wp-responsive-deactivate', currentMenuItemHasPopup );
    384561
    385562        /**
    386          * Ensure an admin submenu is within the visual viewport.
     563         * @summary Ensures an admin submenu is within the visual viewport.
    387564         *
    388565         * @since 4.1.0
    389566         *
    390567         * @param {jQuery} $menuItem The parent menu item containing the submenu.
     568         *
     569         * @returns {void}
    391570         */
    392571        function adjustSubmenu( $menuItem ) {
    393572                var bottomOffset, pageHeight, adjustment, theFold, menutop, wintop, maxtop,
    $document.ready( function() { 
    421600                // iOS Safari works with touchstart, the rest work with click
    422601                mobileEvent = isIOS ? 'touchstart' : 'click';
    423602
    424                 // close any open submenus when touch/click is not on the menu
     603                /**
     604                 * @summary Closes any open submenus when touch/click is not on the menu.
     605                 *
     606                 * @param {Event} e The event object.
     607                 *
     608                 * @returns {void}
     609                 */
    425610                $body.on( mobileEvent+'.wp-mobile-hover', function(e) {
    426611                        if ( $adminmenu.data('wp-responsive') ) {
    427612                                return;
    $document.ready( function() { 
    432617                        }
    433618                });
    434619
     620                /**
     621                 * @summary Handles the opening or closing the submenu based on the mobile click|touch event.
     622                 *
     623                 * @param {Event} event The event object.
     624                 *
     625                 * @returns {void}
     626                 */
    435627                $adminmenu.find( 'a.wp-has-submenu' ).on( mobileEvent + '.wp-mobile-hover', function( event ) {
    436628                        var $menuItem = $(this).parent();
    437629
    $document.ready( function() { 
    453645
    454646        if ( ! isIOS && ! isAndroid ) {
    455647                $adminmenu.find( 'li.wp-has-submenu' ).hoverIntent({
     648
     649                        /**
     650                         * @summary Opens the submenu when hovered over the menu item for desktops.
     651                         *
     652                         * @returns {void}
     653                         */
    456654                        over: function() {
    457655                                var $menuItem = $( this ),
    458656                                        $submenu = $menuItem.find( '.wp-submenu' ),
    $document.ready( function() { 
    471669                                $adminmenu.find( 'li.opensub' ).removeClass( 'opensub' );
    472670                                $menuItem.addClass( 'opensub' );
    473671                        },
     672
     673                        /**
     674                         * @summary Closes the submenu when no longer hovering the menu item.
     675                         *
     676                         * @returns {void}
     677                         */
    474678                        out: function(){
    475679                                if ( $adminmenu.data( 'wp-responsive' ) ) {
    476680                                        // The menu is in responsive mode, bail
    $document.ready( function() { 
    484688                        interval: 90
    485689                });
    486690
     691                /**
     692                 * @summary Opens the submenu on when focused on the menu item.
     693                 *
     694                 * @param {Event} event The event object.
     695                 *
     696                 * @returns {void}
     697                 */
    487698                $adminmenu.on( 'focus.adminmenu', '.wp-submenu a', function( event ) {
    488699                        if ( $adminmenu.data( 'wp-responsive' ) ) {
    489700                                // The menu is in responsive mode, bail
    $document.ready( function() { 
    491702                        }
    492703
    493704                        $( event.target ).closest( 'li.menu-top' ).addClass( 'opensub' );
     705
     706                        /**
     707                         * @summary Closes the submenu on blur from the menu item.
     708                         *
     709                         * @param {Event} event The event object.
     710                         *
     711                         * @returns {void}
     712                         */
    494713                }).on( 'blur.adminmenu', '.wp-submenu a', function( event ) {
    495714                        if ( $adminmenu.data( 'wp-responsive' ) ) {
    496715                                return;
    497716                        }
    498717
    499718                        $( event.target ).closest( 'li.menu-top' ).removeClass( 'opensub' );
     719
     720                        /**
     721                         * @summary Adjusts the size for the submenu.
     722                         *
     723                         * @returns {void}
     724                         */
    500725                }).find( 'li.wp-has-submenu.wp-not-current-submenu' ).on( 'focusin.adminmenu', function() {
    501726                        adjustSubmenu( $( this ) );
    502727                });
    $document.ready( function() { 
    513738        }
    514739        $( 'div.updated, div.error, div.notice' ).not( '.inline, .below-h2' ).insertAfter( $headerEnd );
    515740
    516         // Make notices dismissible
     741        /**
     742         * @summary Make notices dismissible.
     743         *
     744         * @since 4.4.0
     745         *
     746         * @returns {void}
     747         */
    517748        function makeNoticesDismissible() {
    518749                $( '.notice.is-dismissible' ).each( function() {
    519750                        var $el = $( this ),
    $document.ready( function() { 
    540771        // Init screen meta
    541772        screenMeta.init();
    542773
    543         // This event needs to be delegated. Ticket #37973.
     774        /**
     775         * @summary Checks a checkbox.
     776         *
     777         * This event needs to be delegated. Ticket #37973.
     778         *
     779         * @returns {boolean} Returns whether a checkbox is checked or not.
     780         */
    544781        $body.on( 'click', 'tbody > tr > .check-column :checkbox', function( event ) {
    545782                // Shift click to select a range of checkboxes.
    546783                if ( 'undefined' == event.shiftKey ) { return true; }
    $document.ready( function() { 
    564801
    565802                // Toggle the "Select all" checkboxes depending if the other ones are all checked or not.
    566803                var unchecked = $(this).closest('tbody').find(':checkbox').filter(':visible:enabled').not(':checked');
     804
     805                /**
     806                 * @summary Determines if all checkboxes are checked.
     807                 *
     808                 * @returns {boolean} Returns true if there are no unchecked checkboxes.
     809                 */
    567810                $(this).closest('table').children('thead, tfoot').find(':checkbox').prop('checked', function() {
    568811                        return ( 0 === unchecked.length );
    569812                });
    $document.ready( function() { 
    571814                return true;
    572815        });
    573816
    574         // This event needs to be delegated. Ticket #37973.
     817        /**
     818         * @summary Controls all the toggles on bulk toggle change.
     819         *
     820         * When the bulk checkbox is changed, all the checkboxes in the tables are changed accordingly.
     821         * When the shift-button is pressed while changing the bulk checkbox the checkboxes in the table are inverted.
     822         *
     823         * This event needs to be delegated. Ticket #37973.
     824         *
     825         * @param {Event} event The event object.
     826         *
     827         * @returns {boolean}
     828         */
    575829        $body.on( 'click.wp-toggle-checkboxes', 'thead .check-column :checkbox, tfoot .check-column :checkbox', function( event ) {
    576830                var $this = $(this),
    577831                        $table = $this.closest( 'table' ),
    $document.ready( function() { 
    580834
    581835                $table.children( 'tbody' ).filter(':visible')
    582836                        .children().children('.check-column').find(':checkbox')
     837                        /**
     838                         * @summary Updates the checked state on the checkbox in the table.
     839                         *
     840                         * @returns {boolean} True checks the checkbox, False unchecks the checkbox.
     841                         */
    583842                        .prop('checked', function() {
    584843                                if ( $(this).is(':hidden,:disabled') ) {
    585844                                        return false;
    $document.ready( function() { 
    596855
    597856                $table.children('thead,  tfoot').filter(':visible')
    598857                        .children().children('.check-column').find(':checkbox')
     858                        /**
     859                         * @summary Syncs the bulk checkboxes on the top and bottom of the table.
     860                         *
     861                         * @returns {boolean} True checks the checkbox, False unchecks the checkbox.
     862                         */
    599863                        .prop('checked', function() {
    600864                                if ( toggle ) {
    601865                                        return false;
    $document.ready( function() { 
    607871                        });
    608872        });
    609873
    610         // Show row actions on keyboard focus of its parent container element or any other elements contained within
     874        /**
     875         * @summary Shows row actions on focus of its parent container element or any other elements contained within.
     876         *
     877         * @returns {void}
     878         */
    611879        $( '#wpbody-content' ).on({
    612880                focusin: function() {
    613881                        clearTimeout( transitionTimeout );
    $document.ready( function() { 
    636904                return false;
    637905        });
    638906
    639         // tab in textareas
     907        /**
     908         * @summary Handles tab keypresses in theme and plugin editor textareas.
     909         *
     910         * @param {Event} e The event object.
     911         *
     912         * @returns {void}
     913         */
    640914        $('#newcontent').bind('keydown.wpevent_InsertTab', function(e) {
    641915                var el = e.target, selStart, selEnd, val, scroll, sel;
    642916
    643                 if ( e.keyCode == 27 ) { // escape key
     917                // After pressing escape key (keyCode: 27), the tab key should tab out of the textarea.
     918                if ( e.keyCode == 27 ) {
    644919                        // when pressing Escape: Opera 12 and 27 blur form fields, IE 8 clears them
    645920                        e.preventDefault();
    646921                        $(el).data('tab-out', true);
    647922                        return;
    648923                }
    649924
    650                 if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey ) // tab key
     925                // Only listen for plain tab key (keyCode: 9) without any modifiers.
     926                if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey )
    651927                        return;
    652928
     929                // After tabbing out, reset it so next time the tab key can be used again.
    653930                if ( $(el).data('tab-out') ) {
    654931                        $(el).data('tab-out', false);
    655932                        return;
    $document.ready( function() { 
    659936                selEnd = el.selectionEnd;
    660937                val = el.value;
    661938
     939                // If any text is selected, replace the selection with a tab character.
    662940                if ( document.selection ) {
    663941                        el.focus();
    664942                        sel = document.selection.createRange();
    $document.ready( function() { 
    670948                        this.scrollTop = scroll;
    671949                }
    672950
     951                // Cancel the regular tab functionality, to prevent losing focus of the textarea.
    673952                if ( e.stopPropagation )
    674953                        e.stopPropagation();
    675954                if ( e.preventDefault )
    676955                        e.preventDefault();
    677956        });
    678957
     958        // Reset page number variable for new filters/searches but not for bulk actions. See #17685.
    679959        if ( pageInput.length ) {
     960                /**
     961                 * @summary Handles pagination variable when filtering the list table.
     962                 *
     963                 * Set the pagination argument to the first page when the post-filter form is submitted.
     964                 * This happens when pressing the 'filter' button on the list table page.
     965                 *
     966                 * The pagination argument should not be touched when the bulk action dropdowns are set to do anything.
     967                 *
     968                 * The form closest to the pageInput is the post-filter form.
     969                 *
     970                 * @returns {void}
     971                 */
    680972                pageInput.closest('form').submit( function() {
    681 
    682                         // Reset paging var for new filters/searches but not for bulk actions. See #17685.
     973                        /*
     974                         * action = bulk action dropdown at the top of the table
     975                         * action2 = bulk action dropdow at the bottom of the table
     976                         */
    683977                        if ( $('select[name="action"]').val() == -1 && $('select[name="action2"]').val() == -1 && pageInput.val() == currentPage )
    684978                                pageInput.val('1');
    685979                });
    686980        }
    687981
     982        /**
     983         * @summary Resets the bulk actions when the search button is clicked.
     984         *
     985         * @returns {void}
     986         */
    688987        $('.search-box input[type="search"], .search-box input[type="submit"]').mousedown(function () {
    689988                $('select[name^="action"]').val('-1');
    690989        });
    691990
    692         // Scroll into view when focused
     991        /**
     992         * @summary Scrolls into view when focus.scroll-into-view is triggered.
     993         *
     994         * @param {Event} e The event object.
     995         *
     996         * @returns {void}
     997         */
    693998        $('#contextual-help-link, #show-settings-link').on( 'focus.scroll-into-view', function(e){
    694999                if ( e.target.scrollIntoView )
    6951000                        e.target.scrollIntoView(false);
    6961001        });
    6971002
    698         // Disable upload buttons until files are selected
     1003        /**
     1004         * @summary Disables the submit upload buttons when no data is entered.
     1005         *
     1006         * @returns {void}
     1007         */
    6991008        (function(){
    7001009                var button, input, form = $('form.wp-upload-form');
     1010
     1011                // Exit when no upload form is found.
    7011012                if ( ! form.length )
    7021013                        return;
     1014
    7031015                button = form.find('input[type="submit"]');
    7041016                input = form.find('input[type="file"]');
    7051017
     1018                /**
     1019                 * @summary Determines if any data is entered in any file upload input.
     1020                 *
     1021                 * @since 3.5.0
     1022                 *
     1023                 * @returns {void}
     1024                 */
    7061025                function toggleUploadButton() {
     1026                        // When no inputs have a value, disable the upload buttons.
    7071027                        button.prop('disabled', '' === input.map( function() {
    7081028                                return $(this).val();
    7091029                        }).get().join(''));
    7101030                }
     1031
     1032                // Update the status initially.
    7111033                toggleUploadButton();
     1034                // Update the status when any file input changes.
    7121035                input.on('change', toggleUploadButton);
    7131036        })();
    7141037
     1038        /**
     1039         * @summary Pins the menu while distraction-free writing is enabled.
     1040         *
     1041         * @param {Event} event Event data.
     1042         *
     1043         * @since 4.1.0
     1044         *
     1045         * @returns {void}
     1046         */
    7151047        function pinMenu( event ) {
    7161048                var windowPos = $window.scrollTop(),
    7171049                        resizing = ! event || event.type !== 'scroll';
    $document.ready( function() { 
    7201052                        return;
    7211053                }
    7221054
     1055                /*
     1056                 * When the menu is higher than the window and smaller than the entire page.
     1057                 * It should be adjusted to be able to see the entire menu.
     1058                 *
     1059                 * Otherwise it can be accessed normally.
     1060                 */
    7231061                if ( height.menu + height.adminbar < height.window ||
    7241062                        height.menu + height.adminbar + 20 > height.wpwrap ) {
    7251063                        unpinMenu();
    $document.ready( function() { 
    7281066
    7291067                menuIsPinned = true;
    7301068
     1069                // If the menu is higher than the window, compensate on scroll.
    7311070                if ( height.menu + height.adminbar > height.window ) {
    732                         // Check for overscrolling
     1071                        // Check for overscrolling, this happens when swiping up at the top of the document in modern browsers.
    7331072                        if ( windowPos < 0 ) {
     1073                                // Stick the menu to the top.
    7341074                                if ( ! pinnedMenuTop ) {
    7351075                                        pinnedMenuTop = true;
    7361076                                        pinnedMenuBottom = false;
    $document.ready( function() { 
    7441084
    7451085                                return;
    7461086                        } else if ( windowPos + height.window > $document.height() - 1 ) {
     1087                                // When overscrolling at the bottom, stick the menu to the bottom.
    7471088                                if ( ! pinnedMenuBottom ) {
    7481089                                        pinnedMenuBottom = true;
    7491090                                        pinnedMenuTop = false;
    $document.ready( function() { 
    7591100                        }
    7601101
    7611102                        if ( windowPos > lastScrollPosition ) {
    762                                 // Scrolling down
     1103                                // When a down scroll has been detected.
     1104
     1105                                // If it was pinned to the top, unpin and calculate relative scroll.
    7631106                                if ( pinnedMenuTop ) {
    764                                         // let it scroll
    7651107                                        pinnedMenuTop = false;
     1108                                        // Calculate new offset position.
    7661109                                        menuTop = $adminMenuWrap.offset().top - height.adminbar - ( windowPos - lastScrollPosition );
    7671110
    7681111                                        if ( menuTop + height.menu + height.adminbar < windowPos + height.window ) {
    $document.ready( function() { 
    7751118                                                bottom: ''
    7761119                                        });
    7771120                                } else if ( ! pinnedMenuBottom && $adminMenuWrap.offset().top + height.menu < windowPos + height.window ) {
    778                                         // pin the bottom
     1121                                        // Pin it to the bottom.
    7791122                                        pinnedMenuBottom = true;
    7801123
    7811124                                        $adminMenuWrap.css({
    $document.ready( function() { 
    7851128                                        });
    7861129                                }
    7871130                        } else if ( windowPos < lastScrollPosition ) {
    788                                 // Scrolling up
     1131                                // When a scroll up is detected.
     1132
     1133                                // If it was pinned to the bottom, unpin and calculate relative scroll.
    7891134                                if ( pinnedMenuBottom ) {
    790                                         // let it scroll
    7911135                                        pinnedMenuBottom = false;
     1136                                        // Calculate new offset position.
    7921137                                        menuTop = $adminMenuWrap.offset().top - height.adminbar + ( lastScrollPosition - windowPos );
    7931138
    7941139                                        if ( menuTop + height.menu > windowPos + height.window ) {
    $document.ready( function() { 
    8011146                                                bottom: ''
    8021147                                        });
    8031148                                } else if ( ! pinnedMenuTop && $adminMenuWrap.offset().top >= windowPos + height.adminbar ) {
    804                                         // pin the top
     1149                                        // Pin it to the top.
    8051150                                        pinnedMenuTop = true;
    8061151
    8071152                                        $adminMenuWrap.css({
    $document.ready( function() { 
    8111156                                        });
    8121157                                }
    8131158                        } else if ( resizing ) {
    814                                 // Resizing
     1159                                // Window is being resized.
     1160
    8151161                                pinnedMenuTop = pinnedMenuBottom = false;
     1162
     1163                                // Calculate the new offset.
    8161164                                menuTop = windowPos + height.window - height.menu - height.adminbar - 1;
    8171165
    8181166                                if ( menuTop > 0 ) {
    $document.ready( function() { 
    8301178                lastScrollPosition = windowPos;
    8311179        }
    8321180
     1181        /**
     1182         * @summary Determines the height of certain elements.
     1183         *
     1184         * @since 4.1.0
     1185         *
     1186         * @returns {void}
     1187         */
    8331188        function resetHeights() {
    8341189                height = {
    8351190                        window: $window.height(),
    $document.ready( function() { 
    8391194                };
    8401195        }
    8411196
     1197        /**
     1198         * @summary Unpins the menu.
     1199         *
     1200         * @since 4.1.0
     1201         *
     1202         * @returns {void}
     1203         */
    8421204        function unpinMenu() {
    8431205                if ( isIOS || ! menuIsPinned ) {
    8441206                        return;
    $document.ready( function() { 
    8521214                });
    8531215        }
    8541216
     1217        /**
     1218         * @summary Pins and unpins the menu when applicable.
     1219         *
     1220         * @since 4.1.0
     1221         *
     1222         * @returns {void}
     1223         */
    8551224        function setPinMenu() {
    8561225                resetHeights();
    8571226
    $document.ready( function() { 
    8741243                });
    8751244        }
    8761245
     1246        /**
     1247         * @summary Changes properties of metaboxes and body.
     1248         *
     1249         * Changes the sortables and responsiveness of metaboxes.
     1250         *
     1251         * @since 3.8.0
     1252         *
     1253         *@returns {void}
     1254         */
    8771255        window.wpResponsive = {
     1256
     1257                /**
     1258                 * @summary Initializes the wpResponsive object.
     1259                 *
     1260                 * @since 3.8.0
     1261                 *
     1262                 * @returns {void}
     1263                 */
    8781264                init: function() {
    8791265                        var self = this;
    8801266
    $document.ready( function() { 
    8871273
    8881274                        $( '#wp-admin-bar-menu-toggle a' ).attr( 'aria-expanded', 'false' );
    8891275
    890                         // Toggle sidebar when toggle is clicked
     1276                        // Toggle sidebar when toggle is clicked.
    8911277                        $( '#wp-admin-bar-menu-toggle' ).on( 'click.wp-responsive', function( event ) {
    8921278                                event.preventDefault();
    8931279
    894                                 // close any open toolbar submenus
     1280                                // close any open toolbar submenus.
    8951281                                $adminbar.find( '.hover' ).removeClass( 'hover' );
    8961282
    8971283                                $wpwrap.toggleClass( 'wp-responsive-open' );
    $document.ready( function() { 
    9031289                                }
    9041290                        } );
    9051291
    906                         // Add menu events
     1292                        // Add menu events.
    9071293                        $adminmenu.on( 'click.wp-responsive', 'li.wp-has-submenu > a', function( event ) {
    9081294                                if ( ! $adminmenu.data('wp-responsive') ) {
    9091295                                        return;
    $document.ready( function() { 
    9161302                        self.trigger();
    9171303                        $document.on( 'wp-window-resized.wp-responsive', $.proxy( this.trigger, this ) );
    9181304
    919                         // This needs to run later as UI Sortable may be initialized later on $(document).ready()
     1305                        // This needs to run later as UI Sortable may be initialized later on $(document).ready().
    9201306                        $window.on( 'load.wp-responsive', function() {
    9211307                                var width = navigator.userAgent.indexOf('AppleWebKit/') > -1 ? $window.width() : window.innerWidth;
    9221308
    $document.ready( function() { 
    9261312                        });
    9271313                },
    9281314
     1315                /**
     1316                 * @summary Changes properties of body and admin menu.
     1317                 *
     1318                 * Pins and unpins the menu and adds the auto-fold class to the body.
     1319                 * Makes the admin menu responsive and disables the metabox sortables.
     1320                 *
     1321                 * @since 3.8.0
     1322                 *
     1323                 * @returns {void}
     1324                 */
    9291325                activate: function() {
    9301326                        setPinMenu();
    9311327
    932                         if ( ! $body.hasClass( 'auto-fold' ) ) {
    933                                 $body.addClass( 'auto-fold' );
     1328                        if ( ! $body.hasClass( "auto-fold" ) ) {
     1329                                $body.addClass( "auto-fold" );
    9341330                        }
    9351331
    936                         $adminmenu.data( 'wp-responsive', 1 );
     1332                        $adminmenu.data( "wp-responsive", 1 );
    9371333                        this.disableSortables();
    9381334                },
    9391335
     1336                /**
     1337                 * @summary Changes properties of admin menu and enables metabox sortables.
     1338                 *
     1339                 * Pin and unpin the menu.
     1340                 * Removes the responsiveness of the admin menu and enables the metabox sortables.
     1341                 *
     1342                 * @since 3.8.0
     1343                 *
     1344                 * @returns {void}
     1345                 */
    9401346                deactivate: function() {
    9411347                        setPinMenu();
    9421348                        $adminmenu.removeData('wp-responsive');
    9431349                        this.enableSortables();
    9441350                },
    9451351
     1352                /**
     1353                 * @summary Sets the responsiveness and enables the overlay based on the viewport width.
     1354                 *
     1355                 * @since 3.8.0
     1356                 *
     1357                 * @returns {void}
     1358                 */
    9461359                trigger: function() {
    9471360                        var viewportWidth = getViewportWidth();
    9481361
    $document.ready( function() { 
    9531366
    9541367                        if ( viewportWidth <= 782 ) {
    9551368                                if ( ! wpResponsiveActive ) {
    956                                         $document.trigger( 'wp-responsive-activate' );
     1369                                        $document.trigger( "wp-responsive-activate" );
    9571370                                        wpResponsiveActive = true;
    9581371                                }
    9591372                        } else {
    9601373                                if ( wpResponsiveActive ) {
    961                                         $document.trigger( 'wp-responsive-deactivate' );
     1374                                        $document.trigger( "wp-responsive-deactivate" );
    9621375                                        wpResponsiveActive = false;
    9631376                                }
    9641377                        }
    $document.ready( function() { 
    9701383                        }
    9711384                },
    9721385
     1386                /**
     1387                 * @summary Inserts a responsive overlay and toggles the window.
     1388                 *
     1389                 * @since 3.8.0
     1390                 *
     1391                 * @returns {void}
     1392                 */
    9731393                enableOverlay: function() {
    9741394                        if ( $overlay.length === 0 ) {
    9751395                                $overlay = $( '<div id="wp-responsive-overlay"></div>' )
    $document.ready( function() { 
    9861406                        });
    9871407                },
    9881408
     1409                /**
     1410                 * @summary Disables the responsive overlay and removes the overlay.
     1411                 *
     1412                 * @since 3.8.0
     1413                 *
     1414                 * @returns {void}
     1415                 */
    9891416                disableOverlay: function() {
    990                         $toolbarPopups.off( 'click.wp-responsive' );
     1417                        $toolbarPopups.off( "click.wp-responsive" );
    9911418                        $overlay.hide();
    9921419                },
    9931420
     1421                /**
     1422                 * @summary Disables sortables.
     1423                 *
     1424                 * @since 3.8.0
     1425                 *
     1426                 * @returns {void}
     1427                 */
    9941428                disableSortables: function() {
    9951429                        if ( $sortables.length ) {
    9961430                                try {
    997                                         $sortables.sortable('disable');
    998                                 } catch(e) {}
     1431                                        $sortables.sortable( "disable" );
     1432                                } catch ( e ) {}
    9991433                        }
    10001434                },
    10011435
     1436                /**
     1437                 * @summary Enables sortables.
     1438                 *
     1439                 * @since 3.8.0
     1440                 *
     1441                 * @returns {void}
     1442                 */
    10021443                enableSortables: function() {
    10031444                        if ( $sortables.length ) {
    10041445                                try {
    1005                                         $sortables.sortable('enable');
    1006                                 } catch(e) {}
     1446                                        $sortables.sortable( "enable" );
     1447                                } catch ( e ) {}
    10071448                        }
    10081449                }
    10091450        };
    10101451
    1011         // Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on.
     1452        /**
     1453         * @summary Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on.
     1454         *
     1455         * @since 4.5.0
     1456         *
     1457         * @returns {void}
     1458         */
    10121459        function aria_button_if_js() {
    1013                 $( '.aria-button-if-js' ).attr( 'role', 'button' );
     1460                $( ".aria-button-if-js" ).attr( "role", "button" );
    10141461        }
    10151462
    10161463        $( document ).ajaxComplete( function() {
    $document.ready( function() { 
    10371484        }
    10381485
    10391486        /**
    1040          * @summary Set the admin menu collapsed/expanded state.
     1487         * @summary Sets the admin menu collapsed/expanded state.
    10411488         *
    10421489         * Sets the global variable `menuState` and triggers a custom event passing
    10431490         * the current menu state.
    $document.ready( function() { 
    10641511        $document.on( 'wp-window-resized.set-menu-state', setMenuState );
    10651512
    10661513        /**
    1067          * @summary Set ARIA attributes on the collapse/expand menu button.
     1514         * @summary Sets ARIA attributes on the collapse/expand menu button.
    10681515         *
    10691516         * When the admin menu is open or folded, updates the `aria-expanded` and
    10701517         * `aria-label` attributes of the button to give feedback to assistive
    $document.ready( function() { 
    11221569        });
    11231570});
    11241571
    1125 // Fire a custom jQuery event at the end of window resize
     1572// Fire a custom jQuery event at the end of window resize.
    11261573( function() {
    11271574        var timeout;
    11281575
     1576        /**
     1577         * @summary Triggers the WP window-resize event.
     1578         *
     1579         * @since 3.8.0
     1580         *
     1581         * @returns {void}
     1582         */
     1583
    11291584        function triggerEvent() {
    1130                 $document.trigger( 'wp-window-resized' );
     1585                $document.trigger( "wp-window-resized" );
    11311586        }
    11321587
     1588        /**
     1589         * @summary Fires the trigger event again after 200 ms.
     1590         *
     1591         * @since 3.8.0
     1592         *
     1593         * @returns {void}
     1594         */
    11331595        function fireOnce() {
    11341596                window.clearTimeout( timeout );
    11351597                timeout = window.setTimeout( triggerEvent, 200 );