WordPress.org
Get WordPress

Make WordPress Core

Changeset 40796


Ignore:
Timestamp:
05/19/2017 03:44:10 PM (9 years 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.