WordPress.org

Make WordPress Core

Changeset 42963


Ignore:
Timestamp:
04/06/2018 07:46:14 AM (2 years ago)
Author:
atimmer
Message:

Docs: Improve JSDoc for wp-admin/js/tags-box.js.

Props carolinegeven, andizer, ireneyoast, herregroen, jjcomack.
Fixes #43499.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/js/tags-box.js

    r41988 r42963  
    77    var tagDelimiter = ( window.tagsSuggestL10n && window.tagsSuggestL10n.tagDelimiter ) || ',';
    88
    9     // Return an array with any duplicate, whitespace or empty values removed
     9    /**
     10     * Filters unique items and returns a new array.
     11     *
     12     * Filters all items from an array into a new array containing only the unique
     13     * items. This also excludes whitespace or empty values.
     14     *
     15     * @since 2.8.0
     16     *
     17     * @global
     18     *
     19     * @param {Array} array The array to filter through.
     20     *
     21     * @return {Array} A new array containing only the unique items.
     22     */
    1023    array_unique_noempty = function( array ) {
    1124        var out = [];
    1225
     26        // Trim the values and ensure they are unique.
    1327        $.each( array, function( key, val ) {
    1428            val = $.trim( val );
     
    2236    };
    2337
     38    /**
     39     * The TagBox object.
     40     *
     41     * Contains functions to create and manage tags that can be associated with a
     42     * post.
     43     *
     44     * @since 2.9.0
     45     *
     46     * @global
     47     */
    2448    tagBox = {
     49        /**
     50         * Cleans up tags by removing redundant characters.
     51         *
     52         * @since 2.9.0
     53         * @memberOf tagBox
     54         *
     55         * @param {string} tags Comma separated tags that need to be cleaned up.
     56         *
     57         * @return {string} The cleaned up tags.
     58         */
    2559        clean : function( tags ) {
    2660            if ( ',' !== tagDelimiter ) {
     
    3771        },
    3872
     73        /**
     74         * Parses tags and makes them editable.
     75         *
     76         * @since 2.9.0
     77         * @memberOf tagBox
     78         *
     79         * @param {Object} el The tag element to retrieve the ID from.
     80         *
     81         * @return {boolean} Always returns false.
     82         */
    3983        parseTags : function(el) {
    4084            var id = el.id,
     
    4791            delete current_tags[num];
    4892
     93            // Sanitize the current tags and push them as if they're new tags.
    4994            $.each( current_tags, function( key, val ) {
    5095                val = $.trim( val );
     
    60105        },
    61106
     107        /**
     108         * Creates clickable links, buttons and fields for adding or editing tags.
     109         *
     110         * @since 2.9.0
     111         * @memberOf tagBox
     112         *
     113         * @param {Object} el The container HTML element.
     114         *
     115         * @return {void}
     116         */
    62117        quickClicks : function( el ) {
    63118            var thetags = $('.the-tags', el),
     
    74129            tagchecklist.empty();
    75130
     131            /**
     132             * Creates a delete button if tag editing is enabled, before adding it to the tag list.
     133             *
     134             * @since 2.5.0
     135             * @memberOf tagBox
     136             *
     137             * @param {string} key The index of the current tag.
     138             * @param {string} val The value of the current tag.
     139             *
     140             * @return {void}
     141             */
    76142            $.each( current_tags, function( key, val ) {
    77143                var listItem, xbutton;
     
    96162                        '</button>' );
    97163
     164                    /**
     165                     * Handles the click and keypress event of the tag remove button.
     166                     *
     167                     * Makes sure the focus ends up in the tag input field when using
     168                     * the keyboard to delete the tag.
     169                     *
     170                     * @since 4.2.0
     171                     *
     172                     * @param {Event} e The click or keypress event to handle.
     173                     *
     174                     * @return {void}
     175                     */
    98176                    xbutton.on( 'click keypress', function( e ) {
    99177                        // On click or when using the Enter/Spacebar keys.
     
    119197                tagchecklist.append( listItem );
    120198            });
     199
    121200            // The buttons list is built now, give feedback to screen reader users.
    122201            tagBox.screenReadersMessage();
    123202        },
    124203
     204        /**
     205         * Adds a new tag.
     206         *
     207         * Also ensures that the quick links are properly generated.
     208         *
     209         * @since 2.9.0
     210         * @memberOf tagBox
     211         *
     212         * @param {Object} el The container HTML element.
     213         * @param {Object|boolean} a When this is an HTML element the text of that
     214         *                           element will be used for the new tag.
     215         * @param {number|boolean} f If this value is not passed then the tag input
     216         *                           field is focused.
     217         *
     218         * @return {boolean} Always returns false.
     219         */
    125220        flushTags : function( el, a, f ) {
    126221            var tagsval, newtags, text,
     
    159254        },
    160255
     256        /**
     257         * Retrieves the available tags and creates a tagcloud.
     258         *
     259         * Retrieves the available tags from the database and creates an interactive
     260         * tagcloud. Clicking a tag will add it.
     261         *
     262         * @since 2.9.0
     263         * @memberOf tagBox
     264         *
     265         * @param {string} id The ID to extract the taxonomy from.
     266         *
     267         * @return {void}
     268         */
    161269        get : function( id ) {
    162270            var tax = id.substr( id.indexOf('-') + 1 );
    163271
     272            /**
     273             * Puts a received tag cloud into a DOM element.
     274             *
     275             * The tag cloud HTML is generated on the server.
     276             *
     277             * @since 2.9.0
     278             *
     279             * @param {number|string} r The response message from the AJAX call.
     280             * @param {string} stat The status of the AJAX request.
     281             *
     282             * @return {void}
     283             */
    164284            $.post( ajaxurl, { 'action': 'get-tagcloud', 'tax': tax }, function( r, stat ) {
    165285                if ( 0 === r || 'success' != stat ) {
     
    169289                r = $( '<div id="tagcloud-' + tax + '" class="the-tagcloud">' + r + '</div>' );
    170290
     291                /**
     292                 * Adds a new tag when a tag in the tagcloud is clicked.
     293                 *
     294                 * @since 2.9.0
     295                 *
     296                 * @return {boolean} Returns false to prevent the default action.
     297                 */
    171298                $( 'a', r ).click( function() {
    172299                    tagBox.userAction = 'add';
     
    187314
    188315        /**
    189          * Dispatch an audible message to screen readers.
     316         * Dispatches an audible message to screen readers.
     317         *
     318         * This will inform the user when a tag has been added or removed.
    190319         *
    191320         * @since 4.7.0
     321         *
     322         * @return {void}
    192323         */
    193324        screenReadersMessage: function() {
     
    210341        },
    211342
     343        /**
     344         * Initializes the tags box by setting up the links, buttons. Sets up event
     345         * handling.
     346         *
     347         * This includes handling of pressing the enter key in the input field and the
     348         * retrieval of tag suggestions.
     349         *
     350         * @since 2.9.0
     351         * @memberOf tagBox
     352         *
     353         * @return {void}
     354         */
    212355        init : function() {
    213356            var ajaxtag = $('div.ajaxtag');
     
    222365            });
    223366
     367            /**
     368             * Handles pressing enter on the new tag input field.
     369             *
     370             * Prevents submitting the post edit form.
     371             *
     372             * @since 2.9.0
     373             *
     374             * @param {Event} event The keypress event that occurred.
     375             *
     376             * @return {void}
     377             */
    224378            $( 'input.newtag', ajaxtag ).keypress( function( event ) {
    225379                if ( 13 == event.which ) {
     
    238392            });
    239393
    240             // save tags on post save/publish
     394            /**
     395             * Before a post is saved the value currently in the new tag input field will be
     396             * added as a tag.
     397             *
     398             * @since 2.9.0
     399             *
     400             * @return {void}
     401             */
    241402            $('#post').submit(function(){
    242403                $('div.tagsdiv').each( function() {
     
    245406            });
    246407
    247             // Fetch and toggle the Tag cloud.
     408            /**
     409             * Handles clicking on the tag cloud link.
     410             *
     411             * Makes sure the ARIA attributes are set correctly.
     412             *
     413             * @since 2.9.0
     414             *
     415             * @return {void}
     416             */
    248417            $('.tagcloud-link').click(function(){
    249418                // On the first click, fetch the tag cloud and insert it in the DOM.
Note: See TracChangeset for help on using the changeset viewer.