diff --git src/wp-includes/js/admin-bar.js src/wp-includes/js/admin-bar.js index 10d2954..d8d9fbb 100644 --- src/wp-includes/js/admin-bar.js +++ src/wp-includes/js/admin-bar.js @@ -10,12 +10,31 @@ if ( typeof(jQuery) != 'undefined' ) { jQuery(document).ready(function($){ var adminbar = $('#wpadminbar'), refresh, touchOpen, touchClose, disableHoverIntent = false; - refresh = function(i, el){ // force the browser to refresh the tabbing index + /** + * Forces the browser to refresh the tabbing index. + * + * @since 3.5.0 + * + * @param {integer} i The index of the HTML element to remove the tab index from. + * @param {HTMLElement} el The HTML element to remove the tab index from. + * + * @returns {void} + */ + refresh = function(i, el){ var node = $(el), tab = node.attr('tabindex'); if ( tab ) node.attr('tabindex', '0').attr('tabindex', tab); }; + /** + * Adds or removes the hover class on touch. + * + * @since 3.5.0 + * + * @param {bool} unbind If true removes the wp-mobile-hover class. + * + * @returns {void} + */ touchOpen = function(unbind) { adminbar.find('li.menupop').on('click.wp-mobile-hover', function(e) { var el = $(this); @@ -43,6 +62,13 @@ if ( typeof(jQuery) != 'undefined' ) { }); }; + /** + * Removes the hover class if clicked or touched outside the adminbar. + * + * @since 3.5.0 + * + * @returns {void} + */ touchClose = function() { var mobileEvent = /Mobile\/.+Safari/.test(navigator.userAgent) ? 'touchstart' : 'click'; // close any open drop-downs when the click/touch is not on the toolbar @@ -54,6 +80,7 @@ if ( typeof(jQuery) != 'undefined' ) { adminbar.removeClass('nojq').removeClass('nojs'); + // If clicked on the adminbar add the hoverclass, if clicked outside it remove it. if ( 'ontouchstart' in window ) { adminbar.on('touchstart', function(){ touchOpen(true); @@ -65,6 +92,7 @@ if ( typeof(jQuery) != 'undefined' ) { touchClose(); } + // Adds or remove the hover class based on the hover intent. adminbar.find('li.menupop').hoverIntent({ over: function() { if ( disableHoverIntent ) @@ -83,9 +111,21 @@ if ( typeof(jQuery) != 'undefined' ) { interval: 100 }); + // Prevents the toolbar from covering up content when a hash is present in the URL. if ( window.location.hash ) window.scrollBy( 0, -32 ); + /** + * Adds selected class to shortlink in admin bar. + * + * Removes the selected class from the parents of the selected shortlink-input. + * + * @since 3.5.0 + * + * @param {event} e The click event. + * + * @returns {void} + **/ $('#wp-admin-bar-get-shortlink').click(function(e){ e.preventDefault(); $(this).addClass('selected').children('.shortlink-input').blur(function(){ @@ -93,7 +133,20 @@ if ( typeof(jQuery) != 'undefined' ) { }).focus().select(); }); + /** + * It removes the hoverclass if the enter key is pressed. + * + * Makes sure the tab index is refreshed by refreshing each ab-item + * and its children. + * + * @since 3.5.0 + * + * @param {event} e The keydown event. + * + * @returns {void} + */ $('#wpadminbar li.menupop > .ab-item').bind('keydown.adminbar', function(e){ + // Key code 13 is the enter key. if ( e.which != 13 ) return; @@ -116,7 +169,20 @@ if ( typeof(jQuery) != 'undefined' ) { target.siblings('.ab-sub-wrapper').find('.ab-item').each(refresh); }).each(refresh); + /** + * Removes the hover class when the escape key is pressed. + * + * Makes sure the tab index is refreshed by refreshing each ab-item + * and its children. + * + * @since 3.5.0 + * + * @param {event} e The keydown event. + * + * @returns {void} + */ $('#wpadminbar .ab-item').bind('keydown.adminbar', function(e){ + // Key code 27 is the escape key. if ( e.which != 27 ) return; @@ -129,6 +195,15 @@ if ( typeof(jQuery) != 'undefined' ) { target.siblings('.ab-sub-wrapper').find('.ab-item').each(refresh); }); + /** + * Scrolls to top of page by clicking the adminbar. + * + * @since 4.3.0 + * + * @param {event} e The click event. + * + * @returns {void} + */ adminbar.click( function(e) { if ( e.target.id != 'wpadminbar' && e.target.id != 'wp-admin-bar-top-secondary' ) { return; @@ -139,7 +214,17 @@ if ( typeof(jQuery) != 'undefined' ) { e.preventDefault(); }); - // fix focus bug in WebKit + /** + * Sets the focus on an element with a href attribute. + * + * The timeout is used to fix a focus bug in WebKit. + * + * @since 3.5.0 + * + * @param {event} e The keydown event. + * + * @returns {void} + */ $('.screen-reader-shortcut').keydown( function(e) { var id, ua; @@ -158,15 +243,35 @@ if ( typeof(jQuery) != 'undefined' ) { }); $( '#adminbar-search' ).on({ + /** + * Adds the adminbar-focused class on focus. + * + * @since 4.2.0 + * + * @returns {void} + */ focus: function() { $( '#adminbarsearch' ).addClass( 'adminbar-focused' ); + /** + * Remove the adminbar-focused class on blur. + * + * @since 4.2.0 + * + * @returns {void} + */ }, blur: function() { $( '#adminbarsearch' ).removeClass( 'adminbar-focused' ); } } ); - // Empty sessionStorage on logging out if ( 'sessionStorage' in window ) { + /** + * Empties sessionStorage on logging out. + * + * @since 3.6.0 + * + * @returns {void} + */ $('#wp-admin-bar-logout a').click( function() { try { for ( var key in sessionStorage ) { @@ -184,7 +289,28 @@ if ( typeof(jQuery) != 'undefined' ) { } }); } else { + /** + * Wrapper function for the adminbar that's used if jQuery isn't available. + * + * @since 3.5.0 + * + * @param {Object} d The document object. + * @param {Object} w The window object. + * + * @returns {void} + */ (function(d, w) { + /** + * Adds an event listener to an object. + * + * @since 3.5.0 + * + * @param {Object} obj The object to add the event listener to. + * @param {string} type The type of event. + * @param {function} fn The function to bind to the event listener. + * + * @returns {void} + */ var addEvent = function( obj, type, fn ) { if ( obj.addEventListener ) obj.addEventListener(type, fn, false); @@ -195,8 +321,14 @@ if ( typeof(jQuery) != 'undefined' ) { aB, hc = new RegExp('\\bhover\\b', 'g'), q = [], rselected = new RegExp('\\bselected\\b', 'g'), - /** - * Get the timeout ID of the given element + /** + * Gets the timeout ID of the given element. + * + * @since 3.5.0 + * + * @param {HTMLElement} el The HTML element. + * + * @returns {number|boolean} The ID value of the timer that is set or false. */ getTOID = function(el) { var i = q.length; @@ -207,11 +339,21 @@ if ( typeof(jQuery) != 'undefined' ) { return false; }, + /** + * Adds the hoverclass to menu items. + * + * @since 3.5.0 + * + * @param {HTMLElement} t The HTML element. + * + * @returns {void} + */ addHoverClass = function(t) { var i, id, inA, hovering, ul, li, ancestors = [], ancestorLength = 0; + // aB is adminbar. d is document. while ( t && t != aB && t != d ) { if ( 'LI' == t.nodeName.toUpperCase() ) { ancestors[ ancestors.length ] = t; @@ -224,7 +366,7 @@ if ( typeof(jQuery) != 'undefined' ) { t = t.parentNode; } - // Remove any selected classes. + // Removes any selected classes. if ( hovering && hovering.parentNode ) { ul = hovering.parentNode; if ( ul && 'UL' == ul.nodeName.toUpperCase() ) { @@ -237,7 +379,7 @@ if ( typeof(jQuery) != 'undefined' ) { } } - /* remove the hover class for any objects not in the immediate element's ancestry */ + // Removes the hover class for any objects not in the immediate element's ancestry. i = q.length; while ( i-- ) { inA = false; @@ -252,6 +394,15 @@ if ( typeof(jQuery) != 'undefined' ) { } }, + /** + * Removes the hoverclass from menu items. + * + * @since 3.5.0 + * + * @param {HTMLElement} t The HTML element. + * + * @returns {void} + */ removeHoverClass = function(t) { while ( t && t != aB && t != d ) { if ( 'LI' == t.nodeName.toUpperCase() ) { @@ -266,6 +417,15 @@ if ( typeof(jQuery) != 'undefined' ) { } }, + /** + * Handles the click on a shortlink in the adminbar. + * + * @since 3.5.0 + * + * @param {HTMLElement} e The HTML element. + * + * @returns {boolean} + */ clickShortlink = function(e) { var i, l, node, t = e.target || e.srcElement; @@ -304,6 +464,15 @@ if ( typeof(jQuery) != 'undefined' ) { return false; }, + /** + * Scrolls to the top of the page. + * + * @since 3.5.0 + * + * @param {HTMLElement} t The HTML element. + * + * @returns {void} + */ scrollToTop = function(t) { var distance, speed, step, steps, timer, speed_step;