WordPress.org

Make WordPress Core

Ticket #39823: js_doc-inline_edit_post.diff

File js_doc-inline_edit_post.diff, 11.5 KB (added by jjcomack, 3 years ago)
  • src/wp-admin/js/inline-edit-post.js

    diff --git src/wp-admin/js/inline-edit-post.js src/wp-admin/js/inline-edit-post.js
    index 9582707..e59f0fa 100644
     
    11/* global inlineEditL10n, ajaxurl, typenow */
     2
     3/**
     4 *  This file contains the functions needed for the inline editing of posts.
     5 *
     6 *  @since 2.7.0
     7 */
     8
    29window.wp = window.wp || {};
    310
     11/**
     12 * Manages the quick edit and bulk edit windows for editing posts or pages.
     13 *
     14 * @namespace
     15 *
     16 * @since 2.7.0
     17 * @access public
     18 *
     19 * @type {Object}
     20 *
     21 * @property {string} type The type of inline editor.
     22 * @property {string} what The prefix before the post id.
     23 *
     24 */
    425var inlineEditPost;
    526( function( $, wp ) {
    6 inlineEditPost = {
    727
     28        inlineEditPost = {
     29
     30        /**
     31         * @summary Initializes the inline and bulk post editor.
     32         *
     33         * Binds event handlers to the escape key to close the inline editor
     34         * and to the save and close buttons. Changes DOM to be ready for inline
     35         * editing. Adds event handler to bulk edit.
     36         *
     37         * @memberof inlineEditPost
     38         * @since 2.7.0
     39         *
     40         * @returns {void}
     41         */
    842        init : function(){
    943                var t = this, qeRow = $('#inline-edit'), bulkRow = $('#bulk-edit');
    1044
    1145                t.type = $('table.widefat').hasClass('pages') ? 'page' : 'post';
     46                // Post id prefix.
    1247                t.what = '#post-';
    1348
    14                 // prepare the edit rows
     49                /**
     50                 * @summary Bind escape key to revert the changes and close the quick editor.
     51                 *
     52                 * @returns {boolean} Returns the result of revert.
     53                 */
    1554                qeRow.keyup(function(e){
     55                        // Revert changes if escape key is pressed.
    1656                        if ( e.which === 27 ) {
    1757                                return inlineEditPost.revert();
    1858                        }
    1959                });
     60
     61                /**
     62                 * @summary Bind escape key to revert the changes and close the bulk editor.
     63                 *
     64                 * @returns {boolean} Returns the result of revert.
     65                 */
    2066                bulkRow.keyup(function(e){
     67                        // Revert changes if escape key is pressed.
    2168                        if ( e.which === 27 ) {
    2269                                return inlineEditPost.revert();
    2370                        }
    2471                });
    2572
     73                /**
     74                 * @summary Revert changes and close the quick editor if the cancel button is clicked.
     75                 *
     76                 * @returns {boolean} Returns the result of revert.
     77                 */
    2678                $( '.cancel', qeRow ).click( function() {
    2779                        return inlineEditPost.revert();
    2880                });
     81
     82                /**
     83                 * @summary Save changes in the quick editor if the save(named: update) button is clicked.
     84                 *
     85                 * @returns {boolean} Returns the result of save.
     86                 */
    2987                $( '.save', qeRow ).click( function() {
    3088                        return inlineEditPost.save(this);
    3189                });
     90
     91                /**
     92                 * @summary If enter is pressed, and the target is not the cancel button, save the post.
     93                 *
     94                 * @returns {boolean} Returns the result of save.
     95                 */
    3296                $('td', qeRow).keydown(function(e){
    3397                        if ( e.which === 13 && ! $( e.target ).hasClass( 'cancel' ) ) {
    3498                                return inlineEditPost.save(this);
    3599                        }
    36100                });
    37101
     102                /**
     103                 * @summary Revert changes and close the bulk editor if the cancel button is clicked.
     104                 *
     105                 * @returns {boolean} Returns the result of revert.
     106                 */
    38107                $( '.cancel', bulkRow ).click( function() {
    39108                        return inlineEditPost.revert();
    40109                });
    41110
     111                /**
     112                 * @summary Disables the password input field when the private post checkbox is checked.
     113                 *
     114                 * @returns {void}
     115                 */
    42116                $('#inline-edit .inline-edit-private input[value="private"]').click( function(){
    43117                        var pw = $('input.inline-edit-password-input');
    44118                        if ( $(this).prop('checked') ) {
    inlineEditPost = { 
    48122                        }
    49123                });
    50124
    51                 // add events
     125                /**
     126                 * @summary Bind click event to the .editinline link which opens the quick editor.
     127                 *
     128                 * @returns {void}
     129                 */
    52130                $('#the-list').on( 'click', 'a.editinline', function( e ) {
    53131                        e.preventDefault();
    54132                        inlineEditPost.edit(this);
    inlineEditPost = { 
    62140
    63141                $('select[name="_status"] option[value="future"]', bulkRow).remove();
    64142
     143                /**
     144                 * @summary Adds onclick events to the apply buttons.
     145                 *
     146                 * @returns {void}
     147                 */
    65148                $('#doaction, #doaction2').click(function(e){
    66149                        var n;
    67150
    inlineEditPost = { 
    77160                });
    78161        },
    79162
     163        /**
     164         * @summary Toggles the quick edit window.
     165         *
     166         * Hides the window when it's active and shows the window when inactive.
     167         *
     168         * @memberof inlineEditPost
     169         * @since 2.7.0
     170         *
     171         * @param {Object} el Element within a post table row.
     172         *
     173         * @returns {void}
     174         */
    80175        toggle : function(el){
    81176                var t = this;
    82177                $( t.what + t.getId( el ) ).css( 'display' ) === 'none' ? t.revert() : t.edit( el );
    83178        },
    84179
     180        /**
     181         * @summary Creates the bulk editor row to edit multiple posts at once.
     182         *
     183         * @memberof inlineEditPost
     184         * @since 2.7.0
     185         *
     186         * @returns {void}
     187         */
    85188        setBulk : function(){
    86189                var te = '', type = this.type, c = true;
    87190                this.revert();
    88191
    89192                $( '#bulk-edit td' ).attr( 'colspan', $( 'th:visible, td:visible', '.widefat:first thead' ).length );
     193
    90194                // Insert the editor at the top of the table with an empty row above to maintain zebra striping.
    91195                $('table.widefat tbody').prepend( $('#bulk-edit') ).prepend('<tr class="hidden"></tr>');
    92196                $('#bulk-edit').addClass('inline-editor').show();
    93197
     198                /**
     199                 * @summary Create a HTML div with the title and a delete link(cross-icon) for each selected post.
     200                 *
     201                 * Get the selected posts based on the checked checkboxes in the post table.
     202                 * Create a HTML div with the title and a link(delete-icon) for each selected post.
     203                 *
     204                 * @returns {void}
     205                 */
    94206                $( 'tbody th.check-column input[type="checkbox"]' ).each( function() {
     207
     208                        // If the checkbox for a post is selected, add the post to the edit list.
    95209                        if ( $(this).prop('checked') ) {
    96210                                c = false;
    97211                                var id = $(this).val(), theTitle;
    inlineEditPost = { 
    100214                        }
    101215                });
    102216
     217                // If no checkboxes where checked, just hide the quick/bulk edit rows.
    103218                if ( c ) {
    104219                        return this.revert();
    105220                }
    106221
     222                // Add onclick events to the delete-icons in the bulk editors the post title list.
    107223                $('#bulk-titles').html(te);
     224
     225                /**
     226                 * @summary Binds on click events to the checkboxes before the posts in the table.
     227                 *
     228                 * @listens click
     229                 *
     230                 * @returns {void}
     231                 */
    108232                $('#bulk-titles a').click(function(){
    109233                        var id = $(this).attr('id').substr(1);
    110 
    111234                        $('table.widefat input[value="' + id + '"]').prop('checked', false);
    112235                        $('#ttle'+id).remove();
    113236                });
    114237
    115                 // enable autocomplete for tags
     238                // Enable auto-complete for tags when editing posts.
    116239                if ( 'post' === type ) {
    117240                        $( 'tr.inline-editor textarea[data-wp-taxonomy]' ).each( function ( i, element ) {
    118241                                $( element ).wpTagsSuggest();
    119242                        } );
    120243                }
     244
     245                // Scrolls to the top of the table where the editor is rendered.
    121246                $('html, body').animate( { scrollTop: 0 }, 'fast' );
    122247        },
    123248
     249        /**
     250         * @summary Creates a quick edit window for the post that has been clicked.
     251         *
     252         * @memberof inlineEditPost
     253         * @since 2.7.0
     254         *
     255         * @param {number|Object} id The id of the clicked post or an element within a post
     256         *                           table row.
     257         *
     258         * @returns {boolean} Always returns false at the end of execution.
     259         */
    124260        edit : function(id) {
    125261                var t = this, fields, editRow, rowData, status, pageOpt, pageLevel, nextPage, pageLoop = true, nextLevel, f, val, pw;
    126262                t.revert();
    inlineEditPost = { 
    134270                        fields.push('post_parent', 'page_template');
    135271                }
    136272
    137                 // add the new edit row with an extra blank row underneath to maintain zebra striping.
     273                // Add the new edit row with an extra blank row underneath to maintain zebra striping.
    138274                editRow = $('#inline-edit').clone(true);
    139275                $( 'td', editRow ).attr( 'colspan', $( 'th:visible, td:visible', '.widefat:first thead' ).length );
    140276
    141277                $(t.what+id).removeClass('is-expanded').hide().after(editRow).after('<tr class="hidden"></tr>');
    142278
    143                 // populate the data
     279                // Populate fields in the quick edit window.
    144280                rowData = $('#inline_'+id);
    145281                if ( !$(':input[name="post_author"] option[value="' + $('.post_author', rowData).text() + '"]', editRow).val() ) {
    146                         // author no longer has edit caps, so we need to add them to the list of authors
     282                        // The post author no longer has edit capabilities, so we need to add them to the list of authors.
    147283                        $(':input[name="post_author"]', editRow).prepend('<option value="' + $('.post_author', rowData).text() + '">' + $('#' + t.type + '-' + id + ' .author').text() + '</option>');
    148284                }
    149285                if ( $( ':input[name="post_author"] option', editRow ).length === 1 ) {
    inlineEditPost = { 
    152288
    153289                for ( f = 0; f < fields.length; f++ ) {
    154290                        val = $('.'+fields[f], rowData);
    155                         // Deal with Twemoji
     291                        /**
     292                         * @summary Replaces the image for a Twemoji(Twitter emoji) with it's alternate text.
     293                         *
     294                         * @returns Alternate text from the image.
     295                         */
    156296                        val.find( 'img' ).replaceWith( function() { return this.alt; } );
    157297                        val = val.text();
    158298                        $(':input[name="' + fields[f] + '"]', editRow).val( val );
    inlineEditPost = { 
    168308                        $( 'input[name="sticky"]', editRow ).prop( 'checked', true );
    169309                }
    170310
    171                 // hierarchical taxonomies
     311                /**
     312                 * @summary Creates the select boxes for the categories.
     313                 *
     314                 * @returns {void}
     315                 */
    172316                $('.post_category', rowData).each(function(){
    173317                        var taxname,
    174318                                term_ids = $(this).text();
    inlineEditPost = { 
    179323                        }
    180324                });
    181325
    182                 //flat taxonomies
     326                /**
     327                 * @summary Gets all the taxonomies for live auto-fill suggestions.
     328                 * When typing the name of a tag.
     329                 *
     330                 * @returns {void}
     331                 */
    183332                $('.tags_input', rowData).each(function(){
    184333                        var terms = $(this),
    185334                                taxname = $(this).attr('id').replace('_' + id, ''),
    inlineEditPost = { 
    240389                return false;
    241390        },
    242391
    243         // Ajax saving is only for Quick Edit.
     392
     393        /**
     394         * @summary Saves the changes made in the quick edit window to the post.
     395         * AJAX saving is only for Quick Edit and not for bulk edit.
     396         *
     397         * @since 2.7.0
     398         *
     399         * @param   {int} id The id for the post that has been changed.
     400         *
     401         * @returns {boolean} Returns false so the form does not submit
     402         *                    when pressing Enter on a focused field.
     403         */
    244404        save : function(id) {
    245405                var params, fields, page = $('.post_status_page').val() || '';
    246406
    inlineEditPost = { 
    293453                return false;
    294454        },
    295455
    296         // Revert is for both Quick Edit and Bulk Edit.
     456        /**
     457         * @summary Hides and empties the Quick Edit and/or Bulk Edit windows.
     458         *
     459         * @memberof    inlineEditPost
     460         * @since 2.7.0
     461         *
     462         * @returns     {boolean} Always returns false.
     463         */
    297464        revert : function(){
    298465                var $tableWideFat = $( '.widefat' ),
    299466                        id = $( '.inline-editor', $tableWideFat ).attr( 'id' );
    inlineEditPost = { 
    303470                        $( '.ac_results' ).hide();
    304471
    305472                        if ( 'bulk-edit' === id ) {
     473                                // Hide the bulk editor.
    306474                                $( '#bulk-edit', $tableWideFat ).removeClass( 'inline-editor' ).hide().siblings( '.hidden' ).remove();
    307475                                $('#bulk-titles').empty();
     476                                // Store the empty bulk editor in a hidden element.
    308477                                $('#inlineedit').append( $('#bulk-edit') );
    309478                                // Move focus back to the Bulk Action button that was activated.
    310479                                $( '#' + inlineEditPost.whichBulkButtonId ).focus();
    311480                        } else {
     481                                // Remove both the inline-editor and its hidden tr siblings.
    312482                                $('#'+id).siblings('tr.hidden').addBack().remove();
    313483                                id = id.substr( id.lastIndexOf('-') + 1 );
    314484                                // Show the post row and move focus back to the Quick Edit link.
    inlineEditPost = { 
    319489                return false;
    320490        },
    321491
     492        /**
     493         * @summary Gets the id for a the post that you want to quick edit from the row
     494         * in the quick edit table.
     495         *
     496         * @memberof    inlineEditPost
     497         * @since 2.7.0
     498         *
     499         * @param   {Object} o DOM row object to get the id for.
     500         *
     501         * @returns {string} The post id extracted from the table row in the object.
     502         */
    322503        getId : function(o) {
    323504                var id = $(o).closest('tr').attr('id'),
    324505                        parts = id.split('-');