diff --git a/wp-includes/js/wp-emoji.js b/wp-includes/js/wp-emoji.js index dfb56bbecb..b2c8e1a15a 100644 --- a/wp-includes/js/wp-emoji.js +++ b/wp-includes/js/wp-emoji.js @@ -1,8 +1,24 @@ /** + * wp-emoji.js is used to replace emoji with images in browsers when the browser + * doesn't support emoji natively. + * * @output wp-includes/js/wp-emoji.js */ ( function( window, settings ) { + /** + * Replaces emoji with images when browsers don't support emoji. + * + * @since 4.2.0 + * @access private + * + * @class + * + * @see Twitter Emoji library + * @link https://github.com/twitter/twemoji + * + * @return {Object} The wpEmoji parse and test functions. + */ function wpEmoji() { var MutationObserver = window.MutationObserver || window.WebKitMutationObserver || window.MozMutationObserver, @@ -19,13 +35,15 @@ * Detect if the browser supports SVG. * * @since 4.6.0 + * @private * - * @return {Boolean} True if the browser supports svg, false if not. + * @see Modernizr + * @link https://github.com/Modernizr/Modernizr/blob/master/feature-detects/svg/asimg.js + * + * @return {boolean} True if the browser supports svg, false if not. */ function browserSupportsSvgAsImage() { if ( !! document.implementation.hasFeature ) { - // Source: Modernizr - // https://github.com/Modernizr/Modernizr/blob/master/feature-detects/svg/asimg.js return document.implementation.hasFeature( 'http://www.w3.org/TR/SVG11/feature#Image', '1.1' ); } @@ -35,15 +53,21 @@ } /** - * Runs when the document load event is fired, so we can do our first parse of the page. + * Runs when the document load event is fired, so we can do our first parse of + * the page. + * + * Listens to all the DOM mutations and checks for added nodes that contain + * emoji characters and replaces those with twitter emoji images. * * @since 4.2.0 + * @private */ function load() { if ( loaded ) { return; } + // Ensure twemoji is available on the global window before proceeding. if ( typeof window.twemoji === 'undefined' ) { // Break if waiting for longer than 30 sec. if ( count > 600 ) { @@ -61,6 +85,8 @@ twemoji = window.twemoji; loaded = true; + // Initialize the mutation observer, which checks all added nodes for + // replaceable emoji characters. if ( MutationObserver ) { new MutationObserver( function( mutationRecords ) { var i = mutationRecords.length, @@ -71,6 +97,16 @@ removedNodes = mutationRecords[ i ].removedNodes; ii = addedNodes.length; + /* + * Checks if an image has been replaced by a text element + * with the same text as the alternate description of the replaced image. + * (presumably because the image could not be loaded). + * If it is, do absolutely nothing. + * + * Node type 3 is a TEXT_NODE. + * + * @link https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType + */ if ( ii === 1 && removedNodes.length === 1 && addedNodes[0].nodeType === 3 && @@ -81,9 +117,11 @@ return; } + // Loop through all the added nodes. while ( ii-- ) { node = addedNodes[ ii ]; + // Node type 3 is a TEXT_NODE. if ( node.nodeType === 3 ) { if ( ! node.parentNode ) { continue; @@ -95,6 +133,8 @@ * It unnecessarily splits text nodes when it encounters a HTML * template interpolation symbol ( "{{", for example ). So, we * join the text nodes back together as a work-around. + * + * Node type 3 is a TEXT_NODE. */ while( node.nextSibling && 3 === node.nextSibling.nodeType ) { node.nodeValue = node.nodeValue + node.nextSibling.nodeValue; @@ -105,6 +145,11 @@ node = node.parentNode; } + /* + * If the class name of a non-element node contains 'wp-exclude-emoji' ignore it. + * + * Node type 1 is an ELEMENT_NODE. + */ if ( ! node || node.nodeType !== 1 || ( node.className && typeof node.className === 'string' && node.className.indexOf( 'wp-exclude-emoji' ) !== -1 ) ) { @@ -126,13 +171,15 @@ } /** - * Test if a text string contains emoji characters. + * Tests if a text string contains emoji characters. * * @since 4.3.0 * - * @param {String} text The string to test + * @memberOf wp.emoji * - * @return {Boolean} Whether the string contains emoji characters. + * @param {string} text The string to test. + * + * @return {boolean} Whether the string contains emoji characters. */ function test( text ) { // Single char. U+20E3 to detect keycaps. U+00A9 "copyright sign" and U+00AE "registered sign" not included. @@ -148,22 +195,36 @@ } /** - * Given an element or string, parse any emoji characters into Twemoji images. + * Parses any emoji characters into Twemoji images. + * + * - When passed an element the emoji characters are replaced inline. + * - When passed a string the emoji characters are replaced and the result is + * returned. * * @since 4.2.0 * - * @param {HTMLElement|String} object The element or string to parse. - * @param {Object} args Additional options for Twemoji. + * @memberOf wp.emoji + * + * @param {HTMLElement|string} object The element or string to parse. + * @param {Object} args Additional options for Twemoji. + * + * @return {HTMLElement|string} A string where all emoji are now image tags of + * emoji. Or the element that was passed as the first argument. */ function parse( object, args ) { var params; + /* + * If the browser has full support, twemoji is not loaded or our + * object is not what was expected, we do not parse anything. + */ if ( settings.supports.everything || ! twemoji || ! object || ( 'string' !== typeof object && ( ! object.childNodes || ! object.childNodes.length ) ) ) { return object; } + // Compose the params for the twitter emoji library. args = args || {}; params = { base: browserSupportsSvgAsImage() ? settings.svgUrl : settings.baseUrl, @@ -227,6 +288,10 @@ } window.wp = window.wp || {}; + + /** + * @namespace wp.emoji + */ window.wp.emoji = new wpEmoji(); } )( window, window._wpemojiSettings ); diff --git a/wp-includes/version.php b/wp-includes/version.php index bc961a97ad..b5f7cc3b95 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '5.0-alpha-43359'; +$wp_version = '5.0-alpha-43360'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.