WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs: Improve JSDoc for `emoji.js`. 

Props lisannekluitmans, hansjovisyoast, igorsch, nicollle.
Fixes #44367.

Built from https://develop.svn.wordpress.org/trunk@43360


git-svn-id: http://core.svn.wordpress.org/trunk@43188 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
atimmer 2018-06-28 02:35:44 +00:00
parent 649a95f840
commit 96bfb67e79
2 changed files with 76 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
wp-includes/js/wp-emoji.js
View File

@ -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 );

2
wp-includes/version.php
View File

@ -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.