WordPress.org

Make WordPress Core

Changeset 40796


Ignore:
Timestamp:
05/19/17 15:44:10 (2 months ago)
Author:
obenland
Message:

Docs: Improve inline docs for inlineEditPost.

Props jjcomack, rensw90.
Fixes #39823.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/js/inline-edit-post.js

    r40357 r40796  
    11/* global inlineEditL10n, ajaxurl, typenow */ 
     2/** 
     3 * This file contains the functions needed for the inline editing of posts. 
     4 * 
     5 * @since 2.7.0 
     6 */ 
     7 
    28window.wp = window.wp || {}; 
    39 
     10/** 
     11 * Manages the quick edit and bulk edit windows for editing posts or pages. 
     12 * 
     13 * @namespace 
     14 * 
     15 * @since 2.7.0 
     16 * @access public 
     17 * 
     18 * @type {Object} 
     19 * 
     20 * @property {string} type The type of inline editor. 
     21 * @property {string} what The prefix before the post id. 
     22 * 
     23 */ 
    424var inlineEditPost; 
    525( function( $, wp ) { 
    6 inlineEditPost = { 
    7  
     26 
     27    inlineEditPost = { 
     28 
     29    /** 
     30     * @summary Initializes the inline and bulk post editor. 
     31     * 
     32     * Binds event handlers to the escape key to close the inline editor 
     33     * and to the save and close buttons. Changes DOM to be ready for inline 
     34     * editing. Adds event handler to bulk edit. 
     35     * 
     36     * @memberof inlineEditPost 
     37     * @since 2.7.0 
     38     * 
     39     * @returns {void} 
     40     */ 
    841    init : function(){ 
    942        var t = this, qeRow = $('#inline-edit'), bulkRow = $('#bulk-edit'); 
    1043 
    1144        t.type = $('table.widefat').hasClass('pages') ? 'page' : 'post'; 
     45        // Post id prefix. 
    1246        t.what = '#post-'; 
    1347 
    14         // prepare the edit rows 
     48        /** 
     49         * @summary Bind escape key to revert the changes and close the quick editor. 
     50         * 
     51         * @returns {boolean} The result of revert. 
     52         */ 
    1553        qeRow.keyup(function(e){ 
     54            // Revert changes if escape key is pressed. 
    1655            if ( e.which === 27 ) { 
    1756                return inlineEditPost.revert(); 
    1857            } 
    1958        }); 
     59 
     60        /** 
     61         * @summary Bind escape key to revert the changes and close the bulk editor. 
     62         * 
     63         * @returns {boolean} The result of revert. 
     64         */ 
    2065        bulkRow.keyup(function(e){ 
     66            // Revert changes if escape key is pressed. 
    2167            if ( e.which === 27 ) { 
    2268                return inlineEditPost.revert(); 
     
    2470        }); 
    2571 
     72        /** 
     73         * @summary Revert changes and close the quick editor if the cancel button is clicked. 
     74         * 
     75         * @returns {boolean} The result of revert. 
     76         */ 
    2677        $( '.cancel', qeRow ).click( function() { 
    2778            return inlineEditPost.revert(); 
    2879        }); 
     80 
     81        /** 
     82         * @summary Save changes in the quick editor if the save(named: update) button is clicked. 
     83         * 
     84         * @returns {boolean} The result of save. 
     85         */ 
    2986        $( '.save', qeRow ).click( function() { 
    3087            return inlineEditPost.save(this); 
    3188        }); 
     89 
     90        /** 
     91         * @summary If enter is pressed, and the target is not the cancel button, save the post. 
     92         * 
     93         * @returns {boolean} The result of save. 
     94         */ 
    3295        $('td', qeRow).keydown(function(e){ 
    3396            if ( e.which === 13 && ! $( e.target ).hasClass( 'cancel' ) ) { 
     
    3699        }); 
    37100 
     101        /** 
     102         * @summary Revert changes and close the bulk editor if the cancel button is clicked. 
     103         * 
     104         * @returns {boolean} The result of revert. 
     105         */ 
    38106        $( '.cancel', bulkRow ).click( function() { 
    39107            return inlineEditPost.revert(); 
    40108        }); 
    41109 
     110        /** 
     111         * @summary Disables the password input field when the private post checkbox is checked. 
     112         */ 
    42113        $('#inline-edit .inline-edit-private input[value="private"]').click( function(){ 
    43114            var pw = $('input.inline-edit-password-input'); 
     
    49120        }); 
    50121 
    51         // add events 
     122        /** 
     123         * @summary Bind click event to the .editinline link which opens the quick editor. 
     124         */ 
    52125        $('#the-list').on( 'click', 'a.editinline', function( e ) { 
    53126            e.preventDefault(); 
     
    63136        $('select[name="_status"] option[value="future"]', bulkRow).remove(); 
    64137 
     138        /** 
     139         * @summary Adds onclick events to the apply buttons. 
     140         */ 
    65141        $('#doaction, #doaction2').click(function(e){ 
    66142            var n; 
     
    78154    }, 
    79155 
     156    /** 
     157     * @summary Toggles the quick edit window. 
     158     * 
     159     * Hides the window when it's active and shows the window when inactive. 
     160     * 
     161     * @memberof inlineEditPost 
     162     * @since 2.7.0 
     163     * 
     164     * @param {Object} el Element within a post table row. 
     165     */ 
    80166    toggle : function(el){ 
    81167        var t = this; 
     
    83169    }, 
    84170 
     171    /** 
     172     * @summary Creates the bulk editor row to edit multiple posts at once. 
     173     * 
     174     * @memberof inlineEditPost 
     175     * @since 2.7.0 
     176     */ 
    85177    setBulk : function(){ 
    86178        var te = '', type = this.type, c = true; 
     
    88180 
    89181        $( '#bulk-edit td' ).attr( 'colspan', $( 'th:visible, td:visible', '.widefat:first thead' ).length ); 
     182 
    90183        // Insert the editor at the top of the table with an empty row above to maintain zebra striping. 
    91184        $('table.widefat tbody').prepend( $('#bulk-edit') ).prepend('<tr class="hidden"></tr>'); 
    92185        $('#bulk-edit').addClass('inline-editor').show(); 
    93186 
     187        /** 
     188         * @summary Create a HTML div with the title and a delete link(cross-icon) for each selected post. 
     189         * 
     190         * Get the selected posts based on the checked checkboxes in the post table. 
     191         * Create a HTML div with the title and a link(delete-icon) for each selected post. 
     192         */ 
    94193        $( 'tbody th.check-column input[type="checkbox"]' ).each( function() { 
     194 
     195            // If the checkbox for a post is selected, add the post to the edit list. 
    95196            if ( $(this).prop('checked') ) { 
    96197                c = false; 
     
    101202        }); 
    102203 
     204        // If no checkboxes where checked, just hide the quick/bulk edit rows. 
    103205        if ( c ) { 
    104206            return this.revert(); 
    105207        } 
    106208 
     209        // Add onclick events to the delete-icons in the bulk editors the post title list. 
    107210        $('#bulk-titles').html(te); 
     211        /** 
     212         * @summary Binds on click events to the checkboxes before the posts in the table. 
     213         * 
     214         * @listens click 
     215         */ 
    108216        $('#bulk-titles a').click(function(){ 
    109217            var id = $(this).attr('id').substr(1); 
     
    113221        }); 
    114222 
    115         // enable autocomplete for tags 
     223        // Enable auto-complete for tags when editing posts. 
    116224        if ( 'post' === type ) { 
    117225            $( 'tr.inline-editor textarea[data-wp-taxonomy]' ).each( function ( i, element ) { 
     
    128236            } ); 
    129237        } 
     238 
     239        // Scrolls to the top of the table where the editor is rendered. 
    130240        $('html, body').animate( { scrollTop: 0 }, 'fast' ); 
    131241    }, 
    132242 
     243    /** 
     244     * @summary Creates a quick edit window for the post that has been clicked. 
     245     * 
     246     * @memberof inlineEditPost 
     247     * @since 2.7.0 
     248     * 
     249     * @param {number|Object} id The id of the clicked post or an element within a post 
     250     *                           table row. 
     251     * @returns {boolean} Always returns false at the end of execution. 
     252     */ 
    133253    edit : function(id) { 
    134254        var t = this, fields, editRow, rowData, status, pageOpt, pageLevel, nextPage, pageLoop = true, nextLevel, f, val, pw; 
     
    144264        } 
    145265 
    146         // add the new edit row with an extra blank row underneath to maintain zebra striping. 
     266        // Add the new edit row with an extra blank row underneath to maintain zebra striping. 
    147267        editRow = $('#inline-edit').clone(true); 
    148268        $( 'td', editRow ).attr( 'colspan', $( 'th:visible, td:visible', '.widefat:first thead' ).length ); 
     
    150270        $(t.what+id).removeClass('is-expanded').hide().after(editRow).after('<tr class="hidden"></tr>'); 
    151271 
    152         // populate the data 
     272        // Populate fields in the quick edit window. 
    153273        rowData = $('#inline_'+id); 
    154274        if ( !$(':input[name="post_author"] option[value="' + $('.post_author', rowData).text() + '"]', editRow).val() ) { 
    155             // author no longer has edit caps, so we need to add them to the list of authors 
     275 
     276            // The post author no longer has edit capabilities, so we need to add them to the list of authors. 
    156277            $(':input[name="post_author"]', editRow).prepend('<option value="' + $('.post_author', rowData).text() + '">' + $('#' + t.type + '-' + id + ' .author').text() + '</option>'); 
    157278        } 
     
    162283        for ( f = 0; f < fields.length; f++ ) { 
    163284            val = $('.'+fields[f], rowData); 
    164             // Deal with Twemoji 
     285 
     286            /** 
     287             * @summary Replaces the image for a Twemoji(Twitter emoji) with it's alternate text. 
     288             * 
     289             * @returns Alternate text from the image. 
     290             */ 
    165291            val.find( 'img' ).replaceWith( function() { return this.alt; } ); 
    166292            val = val.text(); 
     
    178304        } 
    179305 
    180         // hierarchical taxonomies 
     306        /** 
     307         * @summary Creates the select boxes for the categories. 
     308         */ 
    181309        $('.post_category', rowData).each(function(){ 
    182310            var taxname, 
     
    189317        }); 
    190318 
    191         //flat taxonomies 
     319        /** 
     320         * @summary Gets all the taxonomies for live auto-fill suggestions. 
     321         * When typing the name of a tag. 
     322         */ 
    192323        $('.tags_input', rowData).each(function(){ 
    193324            var terms = $(this), 
     
    209340        }); 
    210341 
    211         // handle the post status 
     342        // Handle the post status. 
    212343        status = $('._status', rowData).text(); 
    213344        if ( 'future' !== status ) { 
     
    221352        } 
    222353 
    223         // remove the current page and children from the parent dropdown 
     354        // Remove the current page and children from the parent dropdown. 
    224355        pageOpt = $('select[name="post_parent"] option[value="' + id + '"]', editRow); 
    225356        if ( pageOpt.length > 0 ) { 
     
    250381    }, 
    251382 
    252     // Ajax saving is only for Quick Edit. 
     383    /** 
     384     * @summary Saves the changes made in the quick edit window to the post. 
     385     * AJAX saving is only for Quick Edit and not for bulk edit. 
     386     * 
     387     * @since 2.7.0 
     388     * 
     389     * @param   {int}     id The id for the post that has been changed. 
     390     * @returns {boolean}    false, so the form does not submit when pressing 
     391     *                       Enter on a focused field. 
     392     */ 
    253393    save : function(id) { 
    254394        var params, fields, page = $('.post_status_page').val() || ''; 
     
    271411        params = fields + '&' + $.param(params); 
    272412 
    273         // make ajax request 
     413        // Make ajax request. 
    274414        $.post( ajaxurl, params, 
    275415            function(r) { 
     
    299439            }, 
    300440        'html'); 
     441 
    301442        // Prevent submitting the form when pressing Enter on a focused field. 
    302443        return false; 
    303444    }, 
    304445 
    305     // Revert is for both Quick Edit and Bulk Edit. 
     446    /** 
     447     * @summary Hides and empties the Quick Edit and/or Bulk Edit windows. 
     448     * 
     449     * @memberof    inlineEditPost 
     450     * @since 2.7.0 
     451     * 
     452     * @returns {boolean} Always returns false. 
     453     */ 
    306454    revert : function(){ 
    307455        var $tableWideFat = $( '.widefat' ), 
     
    313461 
    314462            if ( 'bulk-edit' === id ) { 
     463 
     464                // Hide the bulk editor. 
    315465                $( '#bulk-edit', $tableWideFat ).removeClass( 'inline-editor' ).hide().siblings( '.hidden' ).remove(); 
    316466                $('#bulk-titles').empty(); 
     467 
     468                // Store the empty bulk editor in a hidden element. 
    317469                $('#inlineedit').append( $('#bulk-edit') ); 
     470 
    318471                // Move focus back to the Bulk Action button that was activated. 
    319472                $( '#' + inlineEditPost.whichBulkButtonId ).focus(); 
    320473            } else { 
     474 
     475                // Remove both the inline-editor and its hidden tr siblings. 
    321476                $('#'+id).siblings('tr.hidden').addBack().remove(); 
    322477                id = id.substr( id.lastIndexOf('-') + 1 ); 
     478 
    323479                // Show the post row and move focus back to the Quick Edit link. 
    324480                $( this.what + id ).show().find( '.editinline' ).focus(); 
     
    329485    }, 
    330486 
     487    /** 
     488     * @summary Gets the id for a the post that you want to quick edit from the row 
     489     * in the quick edit table. 
     490     * 
     491     * @memberof    inlineEditPost 
     492     * @since 2.7.0 
     493     * 
     494     * @param   {Object} o DOM row object to get the id for. 
     495     * @returns {string}   The post id extracted from the table row in the object. 
     496     */ 
    331497    getId : function(o) { 
    332498        var id = $(o).closest('tr').attr('id'), 
     
    338504$( document ).ready( function(){ inlineEditPost.init(); } ); 
    339505 
    340 // Show/hide locks on posts 
     506// Show/hide locks on posts. 
    341507$( document ).on( 'heartbeat-tick.wp-check-locked-posts', function( e, data ) { 
    342508    var locked = data['wp-check-locked-posts'] || {}; 
     
    375541    } 
    376542}).ready( function() { 
     543 
    377544    // Set the heartbeat interval to 15 sec. 
    378545    if ( typeof wp !== 'undefined' && wp.heartbeat ) { 
Note: See TracChangeset for help on using the changeset viewer.