<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[42963] trunk/src/wp-admin/js/tags-box.js: Docs: Improve JSDoc for `wp-admin/js/tags-box.js`.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/42963">42963</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/42963","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>atimmer</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2018-04-06 07:46:14 +0000 (Fri, 06 Apr 2018)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Docs: Improve JSDoc for `wp-admin/js/tags-box.js`.
Props carolinegeven, andizer, ireneyoast, herregroen, jjcomack.
Fixes <a href="https://core.trac.wordpress.org/ticket/43499">#43499</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpadminjstagsboxjs">trunk/src/wp-admin/js/tags-box.js</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpadminjstagsboxjs"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-admin/js/tags-box.js</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-admin/js/tags-box.js 2018-04-05 13:39:42 UTC (rev 42962)
+++ trunk/src/wp-admin/js/tags-box.js 2018-04-06 07:46:14 UTC (rev 42963)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -6,10 +6,24 @@
</span><span class="cx" style="display: block; padding: 0 10px"> ( function( $ ) {
</span><span class="cx" style="display: block; padding: 0 10px"> var tagDelimiter = ( window.tagsSuggestL10n && window.tagsSuggestL10n.tagDelimiter ) || ',';
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // Return an array with any duplicate, whitespace or empty values removed
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Filters unique items and returns a new array.
+ *
+ * Filters all items from an array into a new array containing only the unique
+ * items. This also excludes whitespace or empty values.
+ *
+ * @since 2.8.0
+ *
+ * @global
+ *
+ * @param {Array} array The array to filter through.
+ *
+ * @return {Array} A new array containing only the unique items.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> array_unique_noempty = function( array ) {
</span><span class="cx" style="display: block; padding: 0 10px"> var out = [];
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Trim the values and ensure they are unique.
</ins><span class="cx" style="display: block; padding: 0 10px"> $.each( array, function( key, val ) {
</span><span class="cx" style="display: block; padding: 0 10px"> val = $.trim( val );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -21,7 +35,27 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return out;
</span><span class="cx" style="display: block; padding: 0 10px"> };
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * The TagBox object.
+ *
+ * Contains functions to create and manage tags that can be associated with a
+ * post.
+ *
+ * @since 2.9.0
+ *
+ * @global
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> tagBox = {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Cleans up tags by removing redundant characters.
+ *
+ * @since 2.9.0
+ * @memberOf tagBox
+ *
+ * @param {string} tags Comma separated tags that need to be cleaned up.
+ *
+ * @return {string} The cleaned up tags.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> clean : function( tags ) {
</span><span class="cx" style="display: block; padding: 0 10px"> if ( ',' !== tagDelimiter ) {
</span><span class="cx" style="display: block; padding: 0 10px"> tags = tags.replace( new RegExp( tagDelimiter, 'g' ), ',' );
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -36,6 +70,16 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return tags;
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Parses tags and makes them editable.
+ *
+ * @since 2.9.0
+ * @memberOf tagBox
+ *
+ * @param {Object} el The tag element to retrieve the ID from.
+ *
+ * @return {boolean} Always returns false.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> parseTags : function(el) {
</span><span class="cx" style="display: block; padding: 0 10px"> var id = el.id,
</span><span class="cx" style="display: block; padding: 0 10px"> num = id.split('-check-num-')[1],
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -46,6 +90,7 @@
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> delete current_tags[num];
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Sanitize the current tags and push them as if they're new tags.
</ins><span class="cx" style="display: block; padding: 0 10px"> $.each( current_tags, function( key, val ) {
</span><span class="cx" style="display: block; padding: 0 10px"> val = $.trim( val );
</span><span class="cx" style="display: block; padding: 0 10px"> if ( val ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -59,6 +104,16 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Creates clickable links, buttons and fields for adding or editing tags.
+ *
+ * @since 2.9.0
+ * @memberOf tagBox
+ *
+ * @param {Object} el The container HTML element.
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> quickClicks : function( el ) {
</span><span class="cx" style="display: block; padding: 0 10px"> var thetags = $('.the-tags', el),
</span><span class="cx" style="display: block; padding: 0 10px"> tagchecklist = $('.tagchecklist', el),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -73,6 +128,17 @@
</span><span class="cx" style="display: block; padding: 0 10px"> current_tags = thetags.val().split( tagDelimiter );
</span><span class="cx" style="display: block; padding: 0 10px"> tagchecklist.empty();
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Creates a delete button if tag editing is enabled, before adding it to the tag list.
+ *
+ * @since 2.5.0
+ * @memberOf tagBox
+ *
+ * @param {string} key The index of the current tag.
+ * @param {string} val The value of the current tag.
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> $.each( current_tags, function( key, val ) {
</span><span class="cx" style="display: block; padding: 0 10px"> var listItem, xbutton;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -95,6 +161,18 @@
</span><span class="cx" style="display: block; padding: 0 10px"> '<span class="screen-reader-text">' + window.tagsSuggestL10n.removeTerm + ' ' + listItem.html() + '</span>' +
</span><span class="cx" style="display: block; padding: 0 10px"> '</button>' );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Handles the click and keypress event of the tag remove button.
+ *
+ * Makes sure the focus ends up in the tag input field when using
+ * the keyboard to delete the tag.
+ *
+ * @since 4.2.0
+ *
+ * @param {Event} e The click or keypress event to handle.
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> xbutton.on( 'click keypress', function( e ) {
</span><span class="cx" style="display: block; padding: 0 10px"> // On click or when using the Enter/Spacebar keys.
</span><span class="cx" style="display: block; padding: 0 10px"> if ( 'click' === e.type || 13 === e.keyCode || 32 === e.keyCode ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -118,10 +196,27 @@
</span><span class="cx" style="display: block; padding: 0 10px"> // Append the list item to the tag list.
</span><span class="cx" style="display: block; padding: 0 10px"> tagchecklist.append( listItem );
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
</ins><span class="cx" style="display: block; padding: 0 10px"> // The buttons list is built now, give feedback to screen reader users.
</span><span class="cx" style="display: block; padding: 0 10px"> tagBox.screenReadersMessage();
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Adds a new tag.
+ *
+ * Also ensures that the quick links are properly generated.
+ *
+ * @since 2.9.0
+ * @memberOf tagBox
+ *
+ * @param {Object} el The container HTML element.
+ * @param {Object|boolean} a When this is an HTML element the text of that
+ * element will be used for the new tag.
+ * @param {number|boolean} f If this value is not passed then the tag input
+ * field is focused.
+ *
+ * @return {boolean} Always returns false.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> flushTags : function( el, a, f ) {
</span><span class="cx" style="display: block; padding: 0 10px"> var tagsval, newtags, text,
</span><span class="cx" style="display: block; padding: 0 10px"> tags = $( '.the-tags', el ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -158,9 +253,34 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Retrieves the available tags and creates a tagcloud.
+ *
+ * Retrieves the available tags from the database and creates an interactive
+ * tagcloud. Clicking a tag will add it.
+ *
+ * @since 2.9.0
+ * @memberOf tagBox
+ *
+ * @param {string} id The ID to extract the taxonomy from.
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> get : function( id ) {
</span><span class="cx" style="display: block; padding: 0 10px"> var tax = id.substr( id.indexOf('-') + 1 );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Puts a received tag cloud into a DOM element.
+ *
+ * The tag cloud HTML is generated on the server.
+ *
+ * @since 2.9.0
+ *
+ * @param {number|string} r The response message from the AJAX call.
+ * @param {string} stat The status of the AJAX request.
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> $.post( ajaxurl, { 'action': 'get-tagcloud', 'tax': tax }, function( r, stat ) {
</span><span class="cx" style="display: block; padding: 0 10px"> if ( 0 === r || 'success' != stat ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -168,6 +288,13 @@
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> r = $( '<div id="tagcloud-' + tax + '" class="the-tagcloud">' + r + '</div>' );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Adds a new tag when a tag in the tagcloud is clicked.
+ *
+ * @since 2.9.0
+ *
+ * @return {boolean} Returns false to prevent the default action.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> $( 'a', r ).click( function() {
</span><span class="cx" style="display: block; padding: 0 10px"> tagBox.userAction = 'add';
</span><span class="cx" style="display: block; padding: 0 10px"> tagBox.flushTags( $( '#' + tax ), this );
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -186,9 +313,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> userAction: '',
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> /**
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * Dispatch an audible message to screen readers.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Dispatches an audible message to screen readers.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * This will inform the user when a tag has been added or removed.
+ *
</ins><span class="cx" style="display: block; padding: 0 10px"> * @since 4.7.0
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ *
+ * @return {void}
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> screenReadersMessage: function() {
</span><span class="cx" style="display: block; padding: 0 10px"> var message;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -209,6 +340,18 @@
</span><span class="cx" style="display: block; padding: 0 10px"> window.wp.a11y.speak( message, 'assertive' );
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Initializes the tags box by setting up the links, buttons. Sets up event
+ * handling.
+ *
+ * This includes handling of pressing the enter key in the input field and the
+ * retrieval of tag suggestions.
+ *
+ * @since 2.9.0
+ * @memberOf tagBox
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> init : function() {
</span><span class="cx" style="display: block; padding: 0 10px"> var ajaxtag = $('div.ajaxtag');
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -221,6 +364,17 @@
</span><span class="cx" style="display: block; padding: 0 10px"> tagBox.flushTags( $( this ).closest( '.tagsdiv' ) );
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Handles pressing enter on the new tag input field.
+ *
+ * Prevents submitting the post edit form.
+ *
+ * @since 2.9.0
+ *
+ * @param {Event} event The keypress event that occurred.
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> $( 'input.newtag', ajaxtag ).keypress( function( event ) {
</span><span class="cx" style="display: block; padding: 0 10px"> if ( 13 == event.which ) {
</span><span class="cx" style="display: block; padding: 0 10px"> tagBox.userAction = 'add';
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -237,14 +391,29 @@
</span><span class="cx" style="display: block; padding: 0 10px"> $( element ).wpTagsSuggest();
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // save tags on post save/publish
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Before a post is saved the value currently in the new tag input field will be
+ * added as a tag.
+ *
+ * @since 2.9.0
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> $('#post').submit(function(){
</span><span class="cx" style="display: block; padding: 0 10px"> $('div.tagsdiv').each( function() {
</span><span class="cx" style="display: block; padding: 0 10px"> tagBox.flushTags(this, false, 1);
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // Fetch and toggle the Tag cloud.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Handles clicking on the tag cloud link.
+ *
+ * Makes sure the ARIA attributes are set correctly.
+ *
+ * @since 2.9.0
+ *
+ * @return {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> $('.tagcloud-link').click(function(){
</span><span class="cx" style="display: block; padding: 0 10px"> // On the first click, fetch the tag cloud and insert it in the DOM.
</span><span class="cx" style="display: block; padding: 0 10px"> tagBox.get( $( this ).attr( 'id' ) );
</span></span></pre>
</div>
</div>
</body>
</html>