WordPress.org
Get WordPress

Make WordPress Core

Ticket #43499: documents-tags-box.patch

File documents-tags-box.patch, 9.0 KB (added by DiedeExterkate, 7 years ago)

Document tags-box.js

  • src/wp-admin/js/tags-box.js 

    diff --git a/src/wp-admin/js/tags-box.js b/src/wp-admin/js/tags-box.js
index 9603c1ea7c..c416392fbb 100644
    a b  
    44var tagBox, array_unique_noempty;
    55
    66( function( $ ) {
     7
    78        var tagDelimiter = ( window.tagsSuggestL10n && window.tagsSuggestL10n.tagDelimiter ) || ',';
    89
    9         // Return an array with any duplicate, whitespace or empty values removed
     10        /**
     11         * Filters unique items and returns a new array.
     12         *
     13         * Filters all items from an array into a new array containing only the unique items.
     14         * This also excludes whitespace or empty values.
     15         *
     16         * @since 4.2.0
     17         *
     18         * @global
     19         *
     20         * @param {Array} array The array to filter through.
     21         *
     22         * @return {Array} A new array containing only the unique items.
     23         */
    1024        array_unique_noempty = function( array ) {
    1125                var out = [];
    1226
    13                 $.each( array, function( key, val ) {
    14                         val = $.trim( val );
     27                $.each( array,
     28                        // Trim the values and ensure they are unique.
     29                        function( key, val ) {
     30                                val = $.trim( val );
    1531
    16                         if ( val && $.inArray( val, out ) === -1 ) {
    17                                 out.push( val );
     32                                if ( val && $.inArray( val, out ) === -1 ) {
     33                                        out.push( val );
     34                                }
    1835                        }
    19                 } );
     36                );
    2037
    2138                return out;
    2239        };
    2340
     41        /**
     42         * The TagBox object.
     43         *
     44         * Contains functions to create and manage tags that can be associated with a post.
     45         *
     46         * @since 4.2.0
     47         * @global
     48         */
    2449        tagBox = {
     50
     51                /**
     52                 * Cleans up tags by removing redundant characters.
     53                 *
     54                 * Converting the tag delimiter to commas and by removing extra spaces and commas.
     55                 *
     56                 * @since 4.2.0
     57                 * @memberOf tagBox
     58                 *
     59                 * @param {string} tags The tags that need to be cleaned up.
     60                 *
     61                 * @return {string} The cleaned up tags.
     62                 */
    2563                clean : function( tags ) {
    2664                        if ( ',' !== tagDelimiter ) {
    2765                                tags = tags.replace( new RegExp( tagDelimiter, 'g' ), ',' );
    … … var tagBox, array_unique_noempty; 
    3674                        return tags;
    3775                },
    3876
     77                /**
     78                 * Parses tags and makes them editable.
     79                 *
     80                 * @since 4.2.0
     81                 * @memberOf tagBox
     82                 *
     83                 * @param {Object} el The tag element to retrieve the ID from.
     84                 *
     85                 * @return {boolean} Always returns false.
     86                 */
    3987                parseTags : function(el) {
    4088                        var id = el.id,
    4189                                num = id.split('-check-num-')[1],
    … … var tagBox, array_unique_noempty; 
    4694
    4795                        delete current_tags[num];
    4896
     97                        // Sanitize the current tags and push them as if they're new tags.
    4998                        $.each( current_tags, function( key, val ) {
    5099                                val = $.trim( val );
    51100                                if ( val ) {
    52101                                        new_tags.push( val );
    53102                                }
    54                         });
     103                        } );
    55104
    56105                        thetags.val( this.clean( new_tags.join( tagDelimiter ) ) );
    57106
    … … var tagBox, array_unique_noempty; 
    59108                        return false;
    60109                },
    61110
     111                /**
     112                 * Creates clickable links, buttons and fields for adding or editing tags.
     113                 *
     114                 * @since 4.2.0
     115                 * @memberOf tagBox
     116                 *
     117                 * @param {Object} el The container HTML element.
     118                 *
     119                 * @return {void}
     120                 */
    62121                quickClicks : function( el ) {
    63122                        var thetags = $('.the-tags', el),
    64123                                tagchecklist = $('.tagchecklist', el),
    … … var tagBox, array_unique_noempty; 
    73132                        current_tags = thetags.val().split( tagDelimiter );
    74133                        tagchecklist.empty();
    75134
     135                        /**
     136                         * Creates a delete button if tag editing is enabled, before adding it to the tag list.
     137                         *
     138                         * @since 4.2.0
     139                         * @memberOf tagBox
     140                         *
     141                         * @param {string} key The key value of the current tag.
     142                         * @param {string} val The value of the current tag.
     143                         *
     144                         * @return {void}
     145                         */
    76146                        $.each( current_tags, function( key, val ) {
    77147                                var listItem, xbutton;
    78148
    … … var tagBox, array_unique_noempty; 
    95165                                                '<span class="screen-reader-text">' + window.tagsSuggestL10n.removeTerm + ' ' + listItem.html() + '</span>' +
    96166                                                '</button>' );
    97167
     168                                        /**
     169                                         * Handles the click and keypress event of a tag.
     170                                         *
     171                                         * Handles the click and keypress event when an event is called on a tag and re-parses the tags
     172                                         * in the tag box.
     173                                         * Sets the focus on the new tag field when the enter key is pressed.
     174                                         *
     175                                         * @since 4.2.0
     176                                         *
     177                                         * @param {Event} e The window event to handle.
     178                                         *
     179                                         * @return {void}
     180                                         */
    98181                                        xbutton.on( 'click keypress', function( e ) {
    99182                                                // On click or when using the Enter/Spacebar keys.
    100183                                                if ( 'click' === e.type || 13 === e.keyCode || 32 === e.keyCode ) {
    … … var tagBox, array_unique_noempty; 
    118201                                // Append the list item to the tag list.
    119202                                tagchecklist.append( listItem );
    120203                        });
     204
    121205                        // The buttons list is built now, give feedback to screen reader users.
    122206                        tagBox.screenReadersMessage();
    123207                },
    124208
     209                /**
     210                 * Flushes tags on save and on delete.
     211                 *
     212                 * Flushes the tags to a hidden field as a comma separated list on save.
     213                 * Also ensures that the quick links are properly generated.
     214                 *
     215                 * @since 4.2.0
     216                 * @memberOf tagBox
     217                 *
     218                 * @param {Object} el The container HTML element.
     219                 * @param {Object|boolean} a Is either a link from the tag cloud or a hard set boolean value.
     220                 * @param {Number|boolean} f Determines whether or not focus should be applied to the input field.
     221                 *
     222                 * @return {boolean} Always returns false.
     223                 */
    125224                flushTags : function( el, a, f ) {
    126225                        var tagsval, newtags, text,
    127226                                tags = $( '.the-tags', el ),
    … … var tagBox, array_unique_noempty; 
    158257                        return false;
    159258                },
    160259
     260                /**
     261                 * Retrieves the available tags and creates a tagcloud.
     262                 *
     263                 * Retrieves the available tags from the database and creates an interactive tagcloud.
     264                 * If a tag is clicked, the tagbox is flushed for the current taxonomy.
     265                 *
     266                 * @since 4.2.0
     267                 * @memberOf tagBox
     268                 *
     269                 * @param {string} id The ID to extract the indice from.
     270                 *
     271                 * @return {void}
     272                 */
    161273                get : function( id ) {
    162274                        var tax = id.substr( id.indexOf('-') + 1 );
    163275
     276                        /**
     277                         * Creates a tagcloud based on the AJAX request.
     278                         *
     279                         * Handles the AJAX request and creates a tagcloud.
     280                         * Also handles the flushing of the tagbox whenever an anchor or a tagcloud is clicked.
     281                         *
     282                         * @since 4.2.0
     283                         *
     284                         * @param {number|string} r The response message from the AJAX call. Can be numeric or a string.
     285                         * @param {string} stat The status code of the response.
     286                         *
     287                         * @return {void}
     288                         */
    164289                        $.post( ajaxurl, { 'action': 'get-tagcloud', 'tax': tax }, function( r, stat ) {
    165290                                if ( 0 === r || 'success' != stat ) {
    166291                                        return;
    … … var tagBox, array_unique_noempty; 
    168293
    169294                                r = $( '<div id="tagcloud-' + tax + '" class="the-tagcloud">' + r + '</div>' );
    170295
     296                                /**
     297                                 * Flushes the tagbox when an anchor is clicked.
     298                                 *
     299                                 * @since 4.2.0
     300                                 *
     301                                 * @return {boolean} Always returns false.
     302                                 */
    171303                                $( 'a', r ).click( function() {
    172304                                        tagBox.userAction = 'add';
    173305                                        tagBox.flushTags( $( '#' + tax ), this );
    … … var tagBox, array_unique_noempty; 
    186318                userAction: '',
    187319
    188320                /**
    189                  * Dispatch an audible message to screen readers.
     321                 * Dispatches an audible message to screen readers.
    190322                 *
    191323                 * @since 4.7.0
     324                 *
     325                 * @return {void}
    192326                 */
    193327                screenReadersMessage: function() {
    194328                        var message;
    … … var tagBox, array_unique_noempty; 
    209343                        window.wp.a11y.speak( message, 'assertive' );
    210344                },
    211345
     346                /**
     347                 * Initializes the tags box by setting up the links, buttons. Also adds event handling.
     348                 *
     349                 * This includes handling of pressing the enter key in the input field and the retrieval of tag suggestions.
     350                 *
     351                 * @since 4.2.0
     352                 * @memberOf tagBox
     353                 *
     354                 * @return {void}
     355                 */
    212356                init : function() {
    213357                        var ajaxtag = $('div.ajaxtag');
    214358
    … … var tagBox, array_unique_noempty; 
    221365                                tagBox.flushTags( $( this ).closest( '.tagsdiv' ) );
    222366                        });
    223367
     368                        /**
     369                         * Handles the flushing of the tagbox when adding a new tag.
     370                         *
     371                         * Handles the flushing of the tagbox whenever the enter key is pressed in the new tag field.
     372                         *
     373                         * @since 4.2.0
     374                         *
     375                         * @param {Event} event The window event to handle.
     376                         *
     377                         * @return {void}
     378                         */
    224379                        $( 'input.newtag', ajaxtag ).keypress( function( event ) {
    225380                                if ( 13 == event.which ) {
    226381                                        tagBox.userAction = 'add';
    … … var tagBox, array_unique_noempty; 
    237392                                $( element ).wpTagsSuggest();
    238393                        });
    239394
    240                         // save tags on post save/publish
     395                        /**
     396                         * Flushes tags whenever the post is saved.
     397                         *
     398                         * @since 4.2.0
     399                         *
     400                         * @return {void}
     401                         */
    241402                        $('#post').submit(function(){
    242403                                $('div.tagsdiv').each( function() {
    243404                                        tagBox.flushTags(this, false, 1);
    244405                                });
    245406                        });
    246407
    247                         // Fetch and toggle the Tag cloud.
    248                         $('.tagcloud-link').click(function(){
     408                        /**
     409                         * Unbinds the click event and toggles siblings.
     410                         *
     411                         * Unbinds the click event and toggles all sibling tagcloud elements when the tagcloud-link is clicked.
     412                         *
     413                         * @since 4.2.0
     414                         *
     415                         * @return {void}
     416                         */
     417                        $('.tagcloud-link').click(function() {
    249418                                // On the first click, fetch the tag cloud and insert it in the DOM.
    250419                                tagBox.get( $( this ).attr( 'id' ) );
    251420                                // Update button state, remove previous click event and attach a new one to toggle the cloud.