--- a/wp/wp-admin/js/common.js Mon Oct 14 18:06:33 2019 +0200
+++ b/wp/wp-admin/js/common.js Mon Oct 14 18:28:13 2019 +0200
@@ -1,13 +1,29 @@
+/**
+ * @output wp-admin/js/common.js
+ */
+
/* global setUserSetting, ajaxurl, commonL10n, alert, confirm, pagenow */
-var showNotice, adminMenu, columns, validateForm, screenMeta;
+/* global columns, screenMeta */
+
+/**
+ * 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
-adminMenu = {
+/**
+ * Removed in 3.3.0, needed for back-compatibility.
+ *
+ * @since 2.7.0
+ * @deprecated 3.3.0
+ */
+window.adminMenu = {
init : function() {},
fold : function() {},
restoreMenuState : function() {},
@@ -15,8 +31,19 @@
favorites : function() {}
};
-// show/hide/save table columns
-columns = {
+// Show/hide/save table columns.
+window.columns = {
+
+ /**
+ * 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 +57,15 @@
});
},
+ /**
+ * 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 +76,52 @@
});
},
+ /**
+ * 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);
},
+ /**
+ * 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);
},
+ /**
+ * Gets 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 $( '.manage-column[id]' ).filter( '.hidden' ).map(function() {
return this.id;
}).get().join( ',' );
},
+ /**
+ * 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 +131,13 @@
};
},
+ /**
+ * 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,7 +149,16 @@
$document.ready(function(){columns.init();});
-validateForm = function( form ) {
+/**
+ * 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.
+ */
+window.validateForm = function( form ) {
return !$( form )
.find( '.form-required' )
.filter( function() { return $( ':input:visible', this ).val() === ''; } )
@@ -87,7 +169,24 @@
};
// stub for doing better warnings
-showNotice = {
+/**
+ * Shows message pop-up notice or confirmation message.
+ *
+ * @since 2.7.0
+ *
+ * @type {{warn: showNotice.warn, note: showNotice.note}}
+ *
+ * @returns {void}
+ */
+window.showNotice = {
+
+ /**
+ * 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 +196,41 @@
return false;
},
+ /**
+ * Shows an alert message.
+ *
+ * @since 2.7.0
+ *
+ * @param text The text to display in the message.
+ */
note : function(text) {
alert(text);
}
};
-screenMeta = {
+/**
+ * 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}
+ */
+window.screenMeta = {
element: null, // #screen-meta
toggles: null, // .screen-meta-toggle
page: null, // #wpcontent
+ /**
+ * 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 +239,13 @@
this.toggles.click( this.toggleEvent );
},
+ /**
+ * Toggles the screen meta options panel.
+ *
+ * @since 3.2.0
+ *
+ * @returns {void}
+ */
toggleEvent: function() {
var panel = $( '#' + $( this ).attr( 'aria-controls' ) );
@@ -127,11 +258,29 @@
screenMeta.open( panel, $(this) );
},
+ /**
+ * 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();
+
+ /**
+ * 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 +289,24 @@
$document.trigger( 'screen:options:open' );
},
+ /**
+ * 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 ) {
+ /**
+ * 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 +318,11 @@
};
/**
- * Help tabs.
+ * 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 +348,6 @@
/**
* Update custom permalink structure via buttons.
*/
-
var permalinkStructureFocused = false,
$permalinkStructure = $( '#permalink_structure' ),
$permalinkStructureInputs = $( '.permalink-structure input:radio' ),
@@ -329,12 +498,22 @@
},
$headerEnd = $( '.wp-header-end' );
-
- // when the menu is folded, make the fly-out submenu header clickable
+ /**
+ * 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();
});
+ /**
+ * Collapses the admin menu.
+ *
+ * @returns {void}
+ */
$( '#collapse-button' ).on( 'click.collapse-menu', function() {
var viewportWidth = getViewportWidth() || 961;
@@ -367,7 +546,13 @@
$document.trigger( 'wp-collapse-menu', { state: menuState } );
});
- // Handle the `aria-haspopup` attribute on the current menu item when it has a sub-menu.
+ /**
+ * 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 +568,13 @@
$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.
+ * 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 +608,13 @@
// 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
+ /**
+ * 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 +625,13 @@
}
});
+ /**
+ * 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 +653,12 @@
if ( ! isIOS && ! isAndroid ) {
$adminmenu.find( 'li.wp-has-submenu' ).hoverIntent({
+
+ /**
+ * 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 +677,12 @@
$adminmenu.find( 'li.opensub' ).removeClass( 'opensub' );
$menuItem.addClass( 'opensub' );
},
+
+ /**
+ * 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 +696,13 @@
interval: 90
});
+ /**
+ * 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 +710,26 @@
}
$( event.target ).closest( 'li.menu-top' ).addClass( 'opensub' );
+
+ /**
+ * 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' );
+
+ /**
+ * 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 +746,13 @@
}
$( 'div.updated, div.error, div.notice' ).not( '.inline, .below-h2' ).insertAfter( $headerEnd );
- // Make notices dismissible
+ /**
+ * Makes notices dismissible.
+ *
+ * @since 4.4.0
+ *
+ * @returns {void}
+ */
function makeNoticesDismissible() {
$( '.notice.is-dismissible' ).each( function() {
var $el = $( this ),
@@ -540,7 +779,13 @@
// Init screen meta
screenMeta.init();
- // This event needs to be delegated. Ticket #37973.
+ /**
+ * 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 +809,12 @@
// 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');
+
+ /**
+ * 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 +822,18 @@
return true;
});
- // This event needs to be delegated. Ticket #37973.
+ /**
+ * 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 +842,11 @@
$table.children( 'tbody' ).filter(':visible')
.children().children('.check-column').find(':checkbox')
+ /**
+ * 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 +863,12 @@
$table.children('thead, tfoot').filter(':visible')
.children().children('.check-column').find(':checkbox')
+
+ /**
+ * 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 +880,11 @@
});
});
- // Show row actions on keyboard focus of its parent container element or any other elements contained within
+ /**
+ * 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 +913,29 @@
return false;
});
- // tab in textareas
+ /**
+ * 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 +945,7 @@
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 +957,103 @@
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 ) {
+
+ /**
+ * 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() {
-
- // Reset paging var for new filters/searches but not for bulk actions. See #17685.
+ /*
+ * 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');
});
}
+ /**
+ * 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
+ /**
+ * 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
+ /**
+ * 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"]');
+ /**
+ * 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);
})();
+ /**
+ * 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 +1062,12 @@
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 +1076,11 @@
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 +1094,7 @@
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 +1110,12 @@
}
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 +1128,7 @@
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 +1138,13 @@
});
}
} 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 +1157,8 @@
bottom: ''
});
} else if ( ! pinnedMenuTop && $adminMenuWrap.offset().top >= windowPos + height.adminbar ) {
- // pin the top
+
+ // Pin it to the top.
pinnedMenuTop = true;
$adminMenuWrap.css({
@@ -811,8 +1168,11 @@
});
}
} 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 +1190,13 @@
lastScrollPosition = windowPos;
}
+ /**
+ * Determines the height of certain elements.
+ *
+ * @since 4.1.0
+ *
+ * @returns {void}
+ */
function resetHeights() {
height = {
window: $window.height(),
@@ -839,6 +1206,13 @@
};
}
+ /**
+ * Unpins the menu.
+ *
+ * @since 4.1.0
+ *
+ * @returns {void}
+ */
function unpinMenu() {
if ( isIOS || ! menuIsPinned ) {
return;
@@ -852,6 +1226,13 @@
});
}
+ /**
+ * Pins and unpins the menu when applicable.
+ *
+ * @since 4.1.0
+ *
+ * @returns {void}
+ */
function setPinMenu() {
resetHeights();
@@ -874,7 +1255,22 @@
});
}
+ /**
+ * Changes the sortables and responsiveness of metaboxes.
+ *
+ * @since 3.8.0
+ *
+ *@returns {void}
+ */
window.wpResponsive = {
+
+ /**
+ * Initializes the wpResponsive object.
+ *
+ * @since 3.8.0
+ *
+ * @returns {void}
+ */
init: function() {
var self = this;
@@ -887,11 +1283,11 @@
$( '#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 +1299,7 @@
}
} );
- // 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 +1312,7 @@
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,6 +1322,16 @@
});
},
+ /**
+ * 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();
@@ -937,12 +1343,29 @@
this.disableSortables();
},
+ /**
+ * 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();
},
+ /**
+ * Sets the responsiveness and enables the overlay based on the viewport width.
+ *
+ * @since 3.8.0
+ *
+ * @returns {void}
+ */
trigger: function() {
var viewportWidth = getViewportWidth();
@@ -970,6 +1393,13 @@
}
},
+ /**
+ * Inserts a responsive overlay and toggles the window.
+ *
+ * @since 3.8.0
+ *
+ * @returns {void}
+ */
enableOverlay: function() {
if ( $overlay.length === 0 ) {
$overlay = $( '<div id="wp-responsive-overlay"></div>' )
@@ -986,29 +1416,56 @@
});
},
+ /**
+ * Disables the responsive overlay and removes the overlay.
+ *
+ * @since 3.8.0
+ *
+ * @returns {void}
+ */
disableOverlay: function() {
$toolbarPopups.off( 'click.wp-responsive' );
$overlay.hide();
},
+ /**
+ * Disables sortables.
+ *
+ * @since 3.8.0
+ *
+ * @returns {void}
+ */
disableSortables: function() {
if ( $sortables.length ) {
try {
- $sortables.sortable('disable');
- } catch(e) {}
+ $sortables.sortable( 'disable' );
+ } catch ( e ) {}
}
},
+ /**
+ * 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.
+ /**
+ * 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' );
}
@@ -1018,7 +1475,7 @@
});
/**
- * @summary Get the viewport width.
+ * Get the viewport width.
*
* @since 4.7.0
*
@@ -1037,7 +1494,7 @@
}
/**
- * @summary Set the admin menu collapsed/expanded state.
+ * Sets the admin menu collapsed/expanded state.
*
* Sets the global variable `menuState` and triggers a custom event passing
* the current menu state.
@@ -1064,7 +1521,7 @@
$document.on( 'wp-window-resized.set-menu-state', setMenuState );
/**
- * @summary Set ARIA attributes on the collapse/expand menu button.
+ * 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 +1579,28 @@
});
});
-// 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;
+ /**
+ * Triggers the WP window-resize event.
+ *
+ * @since 3.8.0
+ *
+ * @returns {void}
+ */
function triggerEvent() {
$document.trigger( 'wp-window-resized' );
}
+ /**
+ * Fires the trigger event again after 200 ms.
+ *
+ * @since 3.8.0
+ *
+ * @returns {void}
+ */
function fireOnce() {
window.clearTimeout( timeout );
timeout = window.setTimeout( triggerEvent, 200 );