From 4619b059b1ce4a399ec489b666285d64592dddfe Mon Sep 17 00:00:00 2001 From: Adam Silverstein Date: Sun, 3 Dec 2017 18:10:21 +0000 Subject: [PATCH] Docs: Improve JSDocs for common.js. Props andizer, rensw90, benvaassen, jipmoors, ireneyoast and nicollle. Fixes 42679. git-svn-id: https://develop.svn.wordpress.org/trunk@42351 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/js/common.js | 567 ++++++++++++++++++++++++++++++++++---- 1 file changed, 518 insertions(+), 49 deletions(-) diff --git a/src/wp-admin/js/common.js b/src/wp-admin/js/common.js index d8748f53af..7c92850a3a 100644 --- a/src/wp-admin/js/common.js +++ b/src/wp-admin/js/common.js @@ -1,12 +1,24 @@ /* global setUserSetting, ajaxurl, commonL10n, alert, confirm, pagenow */ var showNotice, adminMenu, columns, validateForm, screenMeta; + +/** + * @summary Adds common WordPress functionality to the window. + * + * @param {jQuery} $ jQuery object. + * @param {Object} window The window object. + * @param {mixed} undefined Unused. + */ ( function( $, window, undefined ) { var $document = $( document ), $window = $( window ), $body = $( document.body ); -// Removed in 3.3. -// (perhaps) needed for back-compat +/** + * @summary Removed in 3.3.0, needed for back-compatibility. + * + * @since 2.7.0 + * @deprecated 3.3.0 + */ adminMenu = { init : function() {}, fold : function() {}, @@ -15,8 +27,19 @@ adminMenu = { favorites : function() {} }; -// show/hide/save table columns +// Show/hide/save table columns. columns = { + + /** + * @summary Initializes the column toggles in the screen options. + * + * Binds an onClick event to the checkboxes to show or hide the table columns + * based on their toggled state. And persists the toggled state. + * + * @since 2.7.0 + * + * @returns {void} + */ init : function() { var that = this; $('.hide-column-tog', '#adv-settings').click( function() { @@ -30,6 +53,15 @@ columns = { }); }, + /** + * @summary Saves the toggled state for the columns. + * + * Saves whether the columns should be shown or hidden on a page. + * + * @since 3.0.0 + * + * @returns {void} + */ saveManageColumnsState : function() { var hidden = this.hidden(); $.post(ajaxurl, { @@ -40,22 +72,52 @@ columns = { }); }, + /** + * @summary Makes a column visible and adjusts the column span for the table. + * + * @since 3.0.0 + * @param {string} column The column name. + * + * @returns {void} + */ checked : function(column) { $('.column-' + column).removeClass( 'hidden' ); this.colSpanChange(+1); }, + /** + * @summary Hides a column and adjusts the column span for the table. + * + * @since 3.0.0 + * @param {string} column The column name. + * + * @returns {void} + */ unchecked : function(column) { $('.column-' + column).addClass( 'hidden' ); this.colSpanChange(-1); }, + /** + * @summary Get all hidden columns. + * + * @since 3.0.0 + * + * @returns {string} The hidden column names separated by a comma. + */ hidden : function() { return $( '.manage-column[id]' ).filter( ':hidden' ).map(function() { return this.id; }).get().join( ',' ); }, + /** + * @summary Gets the checked column toggles from the screen options. + * + * @since 3.0.0 + * + * @returns {string} String containing the checked column names. + */ useCheckboxesForHidden : function() { this.hidden = function(){ return $('.hide-column-tog').not(':checked').map(function() { @@ -65,6 +127,13 @@ columns = { }; }, + /** + * @summary Adjusts the column span for the table. + * + * @since 3.1.0 + * + * @param {int} diff The modifier for the column span. + */ colSpanChange : function(diff) { var $t = $('table').find('.colspanchange'), n; if ( !$t.length ) @@ -76,6 +145,15 @@ columns = { $document.ready(function(){columns.init();}); +/** + * @summary Validates that the required form fields are not empty. + * + * @since 2.9.0 + * + * @param {jQuery} form The form to validate. + * + * @returns {boolean} Returns true if all required fields are not an empty string. + */ validateForm = function( form ) { return !$( form ) .find( '.form-required' ) @@ -87,7 +165,24 @@ validateForm = function( form ) { }; // stub for doing better warnings +/** + * @summary Shows message pop-up notice or confirmation message. + * + * @since 2.7.0 + * + * @type {{warn: showNotice.warn, note: showNotice.note}} + * + * @returns {void} + */ showNotice = { + + /** + * @summary Shows a delete confirmation pop-up message. + * + * @since 2.7.0 + * + * @returns {boolean} Returns true if the message is confirmed. + */ warn : function() { var msg = commonL10n.warnDelete || ''; if ( confirm(msg) ) { @@ -97,16 +192,41 @@ showNotice = { return false; }, + /** + * @summary Shows an alert message. + * + * @since 2.7.0 + * + * @param text The text to display in the message. + */ note : function(text) { alert(text); } }; +/** + * @summary Represents the functions for the meta screen options panel. + * + * @since 3.2.0 + * + * @type {{element: null, toggles: null, page: null, init: screenMeta.init, + * toggleEvent: screenMeta.toggleEvent, open: screenMeta.open, + * close: screenMeta.close}} + * + * @returns {void} + */ screenMeta = { element: null, // #screen-meta toggles: null, // .screen-meta-toggle page: null, // #wpcontent + /** + * @summary Initializes the screen meta options panel. + * + * @since 3.2.0 + * + * @returns {void} + */ init: function() { this.element = $('#screen-meta'); this.toggles = $( '#screen-meta-links' ).find( '.show-settings' ); @@ -115,6 +235,13 @@ screenMeta = { this.toggles.click( this.toggleEvent ); }, + /** + * @summary Toggles the screen meta options panel. + * + * @since 3.2.0 + * + * @returns {void} + */ toggleEvent: function() { var panel = $( '#' + $( this ).attr( 'aria-controls' ) ); @@ -127,11 +254,29 @@ screenMeta = { screenMeta.open( panel, $(this) ); }, + /** + * @summary Opens the screen meta options panel. + * + * @since 3.2.0 + * + * @param {jQuery} panel The screen meta options panel div. + * @param {jQuery} button The toggle button. + * + * @returns {void} + */ open: function( panel, button ) { $( '#screen-meta-links' ).find( '.screen-meta-toggle' ).not( button.parent() ).css( 'visibility', 'hidden' ); panel.parent().show(); + + /** + * @summary Sets the focus to the meta options panel and adds the necessary CSS classes. + * + * @since 3.2.0 + * + * @returns {void} + */ panel.slideDown( 'fast', function() { panel.focus(); button.addClass( 'screen-meta-active' ).attr( 'aria-expanded', true ); @@ -140,7 +285,24 @@ screenMeta = { $document.trigger( 'screen:options:open' ); }, + /** + * @summary Closes the screen meta options panel. + * + * @since 3.2.0 + * + * @param {jQuery} panel The screen meta options panel div. + * @param {jQuery} button The toggle button. + * + * @returns {void} + */ close: function( panel, button ) { + /** + * @summary Hides the screen meta options panel. + * + * @since 3.2.0 + * + * @returns {void} + */ panel.slideUp( 'fast', function() { button.removeClass( 'screen-meta-active' ).attr( 'aria-expanded', false ); $('.screen-meta-toggle').css('visibility', ''); @@ -152,7 +314,11 @@ screenMeta = { }; /** - * Help tabs. + * @summary Initializes the help tabs in the help panel. + * + * @param {Event} e The event object. + * + * @returns {void} */ $('.contextual-help-tabs').delegate('a', 'click', function(e) { var link = $(this), @@ -178,7 +344,6 @@ $('.contextual-help-tabs').delegate('a', 'click', function(e) { /** * Update custom permalink structure via buttons. */ - var permalinkStructureFocused = false, $permalinkStructure = $( '#permalink_structure' ), $permalinkStructureInputs = $( '.permalink-structure input:radio' ), @@ -329,12 +494,22 @@ $document.ready( function() { }, $headerEnd = $( '.wp-header-end' ); - - // when the menu is folded, make the fly-out submenu header clickable + /** + * @summary Makes the fly-out submenu header clickable, when the menu is folded. + * + * @param {Event} e The event object. + * + * @returns {void} + */ $adminmenu.on('click.wp-submenu-head', '.wp-submenu-head', function(e){ $(e.target).parent().siblings('a').get(0).click(); }); + /** + * @summary Collapses the admin menu. + * + * @returns {void} + */ $( '#collapse-button' ).on( 'click.collapse-menu', function() { var viewportWidth = getViewportWidth() || 961; @@ -367,7 +542,13 @@ $document.ready( function() { $document.trigger( 'wp-collapse-menu', { state: menuState } ); }); - // Handle the `aria-haspopup` attribute on the current menu item when it has a sub-menu. + /** + * @summary Handles the `aria-haspopup` attribute on the current menu item when it has a submenu. + * + * @since 4.4.0 + * + * @returns {void} + */ function currentMenuItemHasPopup() { var $current = $( 'a.wp-has-current-submenu' ); @@ -383,11 +564,13 @@ $document.ready( function() { $document.on( 'wp-menu-state-set wp-collapse-menu wp-responsive-activate wp-responsive-deactivate', currentMenuItemHasPopup ); /** - * Ensure an admin submenu is within the visual viewport. + * @summary Ensures an admin submenu is within the visual viewport. * * @since 4.1.0 * * @param {jQuery} $menuItem The parent menu item containing the submenu. + * + * @returns {void} */ function adjustSubmenu( $menuItem ) { var bottomOffset, pageHeight, adjustment, theFold, menutop, wintop, maxtop, @@ -421,7 +604,13 @@ $document.ready( function() { // iOS Safari works with touchstart, the rest work with click mobileEvent = isIOS ? 'touchstart' : 'click'; - // close any open submenus when touch/click is not on the menu + /** + * @summary Closes any open submenus when touch/click is not on the menu. + * + * @param {Event} e The event object. + * + * @returns {void} + */ $body.on( mobileEvent+'.wp-mobile-hover', function(e) { if ( $adminmenu.data('wp-responsive') ) { return; @@ -432,6 +621,13 @@ $document.ready( function() { } }); + /** + * @summary Handles the opening or closing the submenu based on the mobile click|touch event. + * + * @param {Event} event The event object. + * + * @returns {void} + */ $adminmenu.find( 'a.wp-has-submenu' ).on( mobileEvent + '.wp-mobile-hover', function( event ) { var $menuItem = $(this).parent(); @@ -453,6 +649,12 @@ $document.ready( function() { if ( ! isIOS && ! isAndroid ) { $adminmenu.find( 'li.wp-has-submenu' ).hoverIntent({ + + /** + * @summary Opens the submenu when hovered over the menu item for desktops. + * + * @returns {void} + */ over: function() { var $menuItem = $( this ), $submenu = $menuItem.find( '.wp-submenu' ), @@ -471,6 +673,12 @@ $document.ready( function() { $adminmenu.find( 'li.opensub' ).removeClass( 'opensub' ); $menuItem.addClass( 'opensub' ); }, + + /** + * @summary Closes the submenu when no longer hovering the menu item. + * + * @returns {void} + */ out: function(){ if ( $adminmenu.data( 'wp-responsive' ) ) { // The menu is in responsive mode, bail @@ -484,6 +692,13 @@ $document.ready( function() { interval: 90 }); + /** + * @summary Opens the submenu on when focused on the menu item. + * + * @param {Event} event The event object. + * + * @returns {void} + */ $adminmenu.on( 'focus.adminmenu', '.wp-submenu a', function( event ) { if ( $adminmenu.data( 'wp-responsive' ) ) { // The menu is in responsive mode, bail @@ -491,12 +706,26 @@ $document.ready( function() { } $( event.target ).closest( 'li.menu-top' ).addClass( 'opensub' ); + + /** + * @summary Closes the submenu on blur from the menu item. + * + * @param {Event} event The event object. + * + * @returns {void} + */ }).on( 'blur.adminmenu', '.wp-submenu a', function( event ) { if ( $adminmenu.data( 'wp-responsive' ) ) { return; } $( event.target ).closest( 'li.menu-top' ).removeClass( 'opensub' ); + + /** + * @summary Adjusts the size for the submenu. + * + * @returns {void} + */ }).find( 'li.wp-has-submenu.wp-not-current-submenu' ).on( 'focusin.adminmenu', function() { adjustSubmenu( $( this ) ); }); @@ -513,7 +742,13 @@ $document.ready( function() { } $( 'div.updated, div.error, div.notice' ).not( '.inline, .below-h2' ).insertAfter( $headerEnd ); - // Make notices dismissible + /** + * @summary Make notices dismissible. + * + * @since 4.4.0 + * + * @returns {void} + */ function makeNoticesDismissible() { $( '.notice.is-dismissible' ).each( function() { var $el = $( this ), @@ -540,7 +775,13 @@ $document.ready( function() { // Init screen meta screenMeta.init(); - // This event needs to be delegated. Ticket #37973. + /** + * @summary Checks a checkbox. + * + * This event needs to be delegated. Ticket #37973. + * + * @returns {boolean} Returns whether a checkbox is checked or not. + */ $body.on( 'click', 'tbody > tr > .check-column :checkbox', function( event ) { // Shift click to select a range of checkboxes. if ( 'undefined' == event.shiftKey ) { return true; } @@ -564,6 +805,12 @@ $document.ready( function() { // Toggle the "Select all" checkboxes depending if the other ones are all checked or not. var unchecked = $(this).closest('tbody').find(':checkbox').filter(':visible:enabled').not(':checked'); + + /** + * @summary Determines if all checkboxes are checked. + * + * @returns {boolean} Returns true if there are no unchecked checkboxes. + */ $(this).closest('table').children('thead, tfoot').find(':checkbox').prop('checked', function() { return ( 0 === unchecked.length ); }); @@ -571,7 +818,18 @@ $document.ready( function() { return true; }); - // This event needs to be delegated. Ticket #37973. + /** + * @summary Controls all the toggles on bulk toggle change. + * + * When the bulk checkbox is changed, all the checkboxes in the tables are changed accordingly. + * When the shift-button is pressed while changing the bulk checkbox the checkboxes in the table are inverted. + * + * This event needs to be delegated. Ticket #37973. + * + * @param {Event} event The event object. + * + * @returns {boolean} + */ $body.on( 'click.wp-toggle-checkboxes', 'thead .check-column :checkbox, tfoot .check-column :checkbox', function( event ) { var $this = $(this), $table = $this.closest( 'table' ), @@ -580,6 +838,11 @@ $document.ready( function() { $table.children( 'tbody' ).filter(':visible') .children().children('.check-column').find(':checkbox') + /** + * @summary Updates the checked state on the checkbox in the table. + * + * @returns {boolean} True checks the checkbox, False unchecks the checkbox. + */ .prop('checked', function() { if ( $(this).is(':hidden,:disabled') ) { return false; @@ -596,6 +859,12 @@ $document.ready( function() { $table.children('thead, tfoot').filter(':visible') .children().children('.check-column').find(':checkbox') + + /** + * @summary Syncs the bulk checkboxes on the top and bottom of the table. + * + * @returns {boolean} True checks the checkbox, False unchecks the checkbox. + */ .prop('checked', function() { if ( toggle ) { return false; @@ -607,7 +876,11 @@ $document.ready( function() { }); }); - // Show row actions on keyboard focus of its parent container element or any other elements contained within + /** + * @summary Shows row actions on focus of its parent container element or any other elements contained within. + * + * @returns {void} + */ $( '#wpbody-content' ).on({ focusin: function() { clearTimeout( transitionTimeout ); @@ -636,20 +909,29 @@ $document.ready( function() { return false; }); - // tab in textareas + /** + * @summary Handles tab keypresses in theme and plugin editor textareas. + * + * @param {Event} e The event object. + * + * @returns {void} + */ $('#newcontent').bind('keydown.wpevent_InsertTab', function(e) { var el = e.target, selStart, selEnd, val, scroll, sel; - if ( e.keyCode == 27 ) { // escape key + // After pressing escape key (keyCode: 27), the tab key should tab out of the textarea. + if ( e.keyCode == 27 ) { // when pressing Escape: Opera 12 and 27 blur form fields, IE 8 clears them e.preventDefault(); $(el).data('tab-out', true); return; } - if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey ) // tab key + // Only listen for plain tab key (keyCode: 9) without any modifiers. + if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey ) return; + // After tabbing out, reset it so next time the tab key can be used again. if ( $(el).data('tab-out') ) { $(el).data('tab-out', false); return; @@ -659,6 +941,7 @@ $document.ready( function() { selEnd = el.selectionEnd; val = el.value; + // If any text is selected, replace the selection with a tab character. if ( document.selection ) { el.focus(); sel = document.selection.createRange(); @@ -670,48 +953,103 @@ $document.ready( function() { this.scrollTop = scroll; } + // Cancel the regular tab functionality, to prevent losing focus of the textarea. if ( e.stopPropagation ) e.stopPropagation(); if ( e.preventDefault ) e.preventDefault(); }); + // Reset page number variable for new filters/searches but not for bulk actions. See #17685. if ( pageInput.length ) { - pageInput.closest('form').submit( function() { - // Reset paging var for new filters/searches but not for bulk actions. See #17685. + /** + * @summary Handles pagination variable when filtering the list table. + * + * Set the pagination argument to the first page when the post-filter form is submitted. + * This happens when pressing the 'filter' button on the list table page. + * + * The pagination argument should not be touched when the bulk action dropdowns are set to do anything. + * + * The form closest to the pageInput is the post-filter form. + * + * @returns {void} + */ + pageInput.closest('form').submit( function() { + /* + * action = bulk action dropdown at the top of the table + * action2 = bulk action dropdow at the bottom of the table + */ if ( $('select[name="action"]').val() == -1 && $('select[name="action2"]').val() == -1 && pageInput.val() == currentPage ) pageInput.val('1'); }); } + /** + * @summary Resets the bulk actions when the search button is clicked. + * + * @returns {void} + */ $('.search-box input[type="search"], .search-box input[type="submit"]').mousedown(function () { $('select[name^="action"]').val('-1'); }); - // Scroll into view when focused + /** + * @summary Scrolls into view when focus.scroll-into-view is triggered. + * + * @param {Event} e The event object. + * + * @returns {void} + */ $('#contextual-help-link, #show-settings-link').on( 'focus.scroll-into-view', function(e){ if ( e.target.scrollIntoView ) e.target.scrollIntoView(false); }); - // Disable upload buttons until files are selected + /** + * @summary Disables the submit upload buttons when no data is entered. + * + * @returns {void} + */ (function(){ var button, input, form = $('form.wp-upload-form'); + + // Exit when no upload form is found. if ( ! form.length ) return; + button = form.find('input[type="submit"]'); input = form.find('input[type="file"]'); + /** + * @summary Determines if any data is entered in any file upload input. + * + * @since 3.5.0 + * + * @returns {void} + */ function toggleUploadButton() { + // When no inputs have a value, disable the upload buttons. button.prop('disabled', '' === input.map( function() { return $(this).val(); }).get().join('')); } + + // Update the status initially. toggleUploadButton(); + // Update the status when any file input changes. input.on('change', toggleUploadButton); })(); + /** + * @summary Pins the menu while distraction-free writing is enabled. + * + * @param {Event} event Event data. + * + * @since 4.1.0 + * + * @returns {void} + */ function pinMenu( event ) { var windowPos = $window.scrollTop(), resizing = ! event || event.type !== 'scroll'; @@ -720,6 +1058,12 @@ $document.ready( function() { return; } + /* + * When the menu is higher than the window and smaller than the entire page. + * It should be adjusted to be able to see the entire menu. + * + * Otherwise it can be accessed normally. + */ if ( height.menu + height.adminbar < height.window || height.menu + height.adminbar + 20 > height.wpwrap ) { unpinMenu(); @@ -728,9 +1072,11 @@ $document.ready( function() { menuIsPinned = true; + // If the menu is higher than the window, compensate on scroll. if ( height.menu + height.adminbar > height.window ) { - // Check for overscrolling + // Check for overscrolling, this happens when swiping up at the top of the document in modern browsers. if ( windowPos < 0 ) { + // Stick the menu to the top. if ( ! pinnedMenuTop ) { pinnedMenuTop = true; pinnedMenuBottom = false; @@ -744,6 +1090,7 @@ $document.ready( function() { return; } else if ( windowPos + height.window > $document.height() - 1 ) { + // When overscrolling at the bottom, stick the menu to the bottom. if ( ! pinnedMenuBottom ) { pinnedMenuBottom = true; pinnedMenuTop = false; @@ -759,10 +1106,12 @@ $document.ready( function() { } if ( windowPos > lastScrollPosition ) { - // Scrolling down + // When a down scroll has been detected. + + // If it was pinned to the top, unpin and calculate relative scroll. if ( pinnedMenuTop ) { - // let it scroll pinnedMenuTop = false; + // Calculate new offset position. menuTop = $adminMenuWrap.offset().top - height.adminbar - ( windowPos - lastScrollPosition ); if ( menuTop + height.menu + height.adminbar < windowPos + height.window ) { @@ -775,7 +1124,7 @@ $document.ready( function() { bottom: '' }); } else if ( ! pinnedMenuBottom && $adminMenuWrap.offset().top + height.menu < windowPos + height.window ) { - // pin the bottom + // Pin it to the bottom. pinnedMenuBottom = true; $adminMenuWrap.css({ @@ -785,10 +1134,13 @@ $document.ready( function() { }); } } else if ( windowPos < lastScrollPosition ) { - // Scrolling up + // When a scroll up is detected. + + // If it was pinned to the bottom, unpin and calculate relative scroll. if ( pinnedMenuBottom ) { - // let it scroll pinnedMenuBottom = false; + + // Calculate new offset position. menuTop = $adminMenuWrap.offset().top - height.adminbar + ( lastScrollPosition - windowPos ); if ( menuTop + height.menu > windowPos + height.window ) { @@ -801,7 +1153,8 @@ $document.ready( function() { bottom: '' }); } else if ( ! pinnedMenuTop && $adminMenuWrap.offset().top >= windowPos + height.adminbar ) { - // pin the top + + // Pin it to the top. pinnedMenuTop = true; $adminMenuWrap.css({ @@ -811,8 +1164,11 @@ $document.ready( function() { }); } } else if ( resizing ) { - // Resizing + // Window is being resized. + pinnedMenuTop = pinnedMenuBottom = false; + + // Calculate the new offset. menuTop = windowPos + height.window - height.menu - height.adminbar - 1; if ( menuTop > 0 ) { @@ -830,6 +1186,13 @@ $document.ready( function() { lastScrollPosition = windowPos; } + /** + * @summary Determines the height of certain elements. + * + * @since 4.1.0 + * + * @returns {void} + */ function resetHeights() { height = { window: $window.height(), @@ -839,6 +1202,13 @@ $document.ready( function() { }; } + /** + * @summary Unpins the menu. + * + * @since 4.1.0 + * + * @returns {void} + */ function unpinMenu() { if ( isIOS || ! menuIsPinned ) { return; @@ -852,6 +1222,13 @@ $document.ready( function() { }); } + /** + * @summary Pins and unpins the menu when applicable. + * + * @since 4.1.0 + * + * @returns {void} + */ function setPinMenu() { resetHeights(); @@ -874,7 +1251,24 @@ $document.ready( function() { }); } + /** + * @summary Changes properties of metaboxes and body. + * + * Changes the sortables and responsiveness of metaboxes. + * + * @since 3.8.0 + * + *@returns {void} + */ window.wpResponsive = { + + /** + * @summary Initializes the wpResponsive object. + * + * @since 3.8.0 + * + * @returns {void} + */ init: function() { var self = this; @@ -887,11 +1281,11 @@ $document.ready( function() { $( '#wp-admin-bar-menu-toggle a' ).attr( 'aria-expanded', 'false' ); - // Toggle sidebar when toggle is clicked + // Toggle sidebar when toggle is clicked. $( '#wp-admin-bar-menu-toggle' ).on( 'click.wp-responsive', function( event ) { event.preventDefault(); - // close any open toolbar submenus + // close any open toolbar submenus. $adminbar.find( '.hover' ).removeClass( 'hover' ); $wpwrap.toggleClass( 'wp-responsive-open' ); @@ -903,7 +1297,7 @@ $document.ready( function() { } } ); - // Add menu events + // Add menu events. $adminmenu.on( 'click.wp-responsive', 'li.wp-has-submenu > a', function( event ) { if ( ! $adminmenu.data('wp-responsive') ) { return; @@ -916,7 +1310,7 @@ $document.ready( function() { self.trigger(); $document.on( 'wp-window-resized.wp-responsive', $.proxy( this.trigger, this ) ); - // This needs to run later as UI Sortable may be initialized later on $(document).ready() + // This needs to run later as UI Sortable may be initialized later on $(document).ready(). $window.on( 'load.wp-responsive', function() { var width = navigator.userAgent.indexOf('AppleWebKit/') > -1 ? $window.width() : window.innerWidth; @@ -926,23 +1320,50 @@ $document.ready( function() { }); }, + /** + * @summary Changes properties of body and admin menu. + * + * Pins and unpins the menu and adds the auto-fold class to the body. + * Makes the admin menu responsive and disables the metabox sortables. + * + * @since 3.8.0 + * + * @returns {void} + */ activate: function() { setPinMenu(); - if ( ! $body.hasClass( 'auto-fold' ) ) { - $body.addClass( 'auto-fold' ); + if ( ! $body.hasClass( "auto-fold" ) ) { + $body.addClass( "auto-fold" ); } - $adminmenu.data( 'wp-responsive', 1 ); + $adminmenu.data( "wp-responsive", 1 ); this.disableSortables(); }, + /** + * @summary Changes properties of admin menu and enables metabox sortables. + * + * Pin and unpin the menu. + * Removes the responsiveness of the admin menu and enables the metabox sortables. + * + * @since 3.8.0 + * + * @returns {void} + */ deactivate: function() { setPinMenu(); $adminmenu.removeData('wp-responsive'); this.enableSortables(); }, + /** + * @summary Sets the responsiveness and enables the overlay based on the viewport width. + * + * @since 3.8.0 + * + * @returns {void} + */ trigger: function() { var viewportWidth = getViewportWidth(); @@ -953,12 +1374,12 @@ $document.ready( function() { if ( viewportWidth <= 782 ) { if ( ! wpResponsiveActive ) { - $document.trigger( 'wp-responsive-activate' ); + $document.trigger( "wp-responsive-activate" ); wpResponsiveActive = true; } } else { if ( wpResponsiveActive ) { - $document.trigger( 'wp-responsive-deactivate' ); + $document.trigger( "wp-responsive-deactivate" ); wpResponsiveActive = false; } } @@ -970,6 +1391,13 @@ $document.ready( function() { } }, + /** + * @summary Inserts a responsive overlay and toggles the window. + * + * @since 3.8.0 + * + * @returns {void} + */ enableOverlay: function() { if ( $overlay.length === 0 ) { $overlay = $( '
' ) @@ -986,31 +1414,58 @@ $document.ready( function() { }); }, + /** + * @summary Disables the responsive overlay and removes the overlay. + * + * @since 3.8.0 + * + * @returns {void} + */ disableOverlay: function() { - $toolbarPopups.off( 'click.wp-responsive' ); + $toolbarPopups.off( "click.wp-responsive" ); $overlay.hide(); }, + /** + * @summary Disables sortables. + * + * @since 3.8.0 + * + * @returns {void} + */ disableSortables: function() { if ( $sortables.length ) { try { - $sortables.sortable('disable'); - } catch(e) {} + $sortables.sortable( "disable" ); + } catch ( e ) {} } }, + /** + * @summary Enables sortables. + * + * @since 3.8.0 + * + * @returns {void} + */ enableSortables: function() { if ( $sortables.length ) { try { - $sortables.sortable('enable'); - } catch(e) {} + $sortables.sortable( "enable" ); + } catch ( e ) {} } } }; - // Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on. + /** + * @summary Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on. + * + * @since 4.5.0 + * + * @returns {void} + */ function aria_button_if_js() { - $( '.aria-button-if-js' ).attr( 'role', 'button' ); + $( ".aria-button-if-js" ).attr( "role", "button" ); } $( document ).ajaxComplete( function() { @@ -1037,7 +1492,7 @@ $document.ready( function() { } /** - * @summary Set the admin menu collapsed/expanded state. + * @summary Sets the admin menu collapsed/expanded state. * * Sets the global variable `menuState` and triggers a custom event passing * the current menu state. @@ -1064,7 +1519,7 @@ $document.ready( function() { $document.on( 'wp-window-resized.set-menu-state', setMenuState ); /** - * @summary Set ARIA attributes on the collapse/expand menu button. + * @summary Sets ARIA attributes on the collapse/expand menu button. * * When the admin menu is open or folded, updates the `aria-expanded` and * `aria-label` attributes of the button to give feedback to assistive @@ -1122,14 +1577,28 @@ $document.ready( function() { }); }); -// Fire a custom jQuery event at the end of window resize +// Fire a custom jQuery event at the end of window resize. ( function() { var timeout; + /** + * @summary Triggers the WP window-resize event. + * + * @since 3.8.0 + * + * @returns {void} + */ function triggerEvent() { - $document.trigger( 'wp-window-resized' ); + $document.trigger( "wp-window-resized" ); } + /** + * @summary Fires the trigger event again after 200 ms. + * + * @since 3.8.0 + * + * @returns {void} + */ function fireOnce() { window.clearTimeout( timeout ); timeout = window.setTimeout( triggerEvent, 200 );