Ticket #39823: js_doc-inline_edit_post.diff

src/wp-admin/js/inline-edit-post.js

@@ -1 +1 @@
 /* global inlineEditL10n, ajaxurl, typenow */
+
+/**
+ *  This file contains the functions needed for the inline editing of posts.
+ *
+ *  @since 2.7.0
+ */
+
 window.wp = window.wp || {};
 
+/**
+ * Manages the quick edit and bulk edit windows for editing posts or pages.
+ *
+ * @namespace
+ *
+ * @since 2.7.0
+ * @access public
+ *
+ * @type {Object}
+ *
+ * @property {string} type The type of inline editor.
+ * @property {string} what The prefix before the post id.
+ *
+ */
 var inlineEditPost;
 ( function( $, wp ) {
-inlineEditPost = {
 
+        inlineEditPost = {
+
+        /**
+         * @summary Initializes the inline and bulk post editor.
+         *
+         * Binds event handlers to the escape key to close the inline editor
+         * and to the save and close buttons. Changes DOM to be ready for inline
+         * editing. Adds event handler to bulk edit.
+         *
+         * @memberof inlineEditPost
+         * @since 2.7.0
+         *
+         * @returns {void}
+         */
         init : function(){
                 var t = this, qeRow = $('#inline-edit'), bulkRow = $('#bulk-edit');
 
                 t.type = $('table.widefat').hasClass('pages') ? 'page' : 'post';
+                // Post id prefix.
                 t.what = '#post-';
 
-                // prepare the edit rows
+                /**
+                 * @summary Bind escape key to revert the changes and close the quick editor.
+                 *
+                 * @returns {boolean} Returns the result of revert.
+                 */
                 qeRow.keyup(function(e){
+                        // Revert changes if escape key is pressed.
                         if ( e.which === 27 ) {
                                 return inlineEditPost.revert();
                         }
                 });
+
+                /**
+                 * @summary Bind escape key to revert the changes and close the bulk editor.
+                 *
+                 * @returns {boolean} Returns the result of revert.
+                 */
                 bulkRow.keyup(function(e){
+                        // Revert changes if escape key is pressed.
                         if ( e.which === 27 ) {
                                 return inlineEditPost.revert();
                         }
                 });
 
+                /**
+                 * @summary Revert changes and close the quick editor if the cancel button is clicked.
+                 *
+                 * @returns {boolean} Returns the result of revert.
+                 */
                 $( '.cancel', qeRow ).click( function() {
                         return inlineEditPost.revert();
                 });
+
+                /**
+                 * @summary Save changes in the quick editor if the save(named: update) button is clicked.
+                 *
+                 * @returns {boolean} Returns the result of save.
+                 */
                 $( '.save', qeRow ).click( function() {
                         return inlineEditPost.save(this);
                 });
+
+                /**
+                 * @summary If enter is pressed, and the target is not the cancel button, save the post.
+                 *
+                 * @returns {boolean} Returns the result of save.
+                 */
                 $('td', qeRow).keydown(function(e){
                         if ( e.which === 13 && ! $( e.target ).hasClass( 'cancel' ) ) {
                                 return inlineEditPost.save(this);
                         }
                 });
 
+                /**
+                 * @summary Revert changes and close the bulk editor if the cancel button is clicked.
+                 *
+                 * @returns {boolean} Returns the result of revert.
+                 */
                 $( '.cancel', bulkRow ).click( function() {
                         return inlineEditPost.revert();
                 });
 
+                /**
+                 * @summary Disables the password input field when the private post checkbox is checked.
+                 *
+                 * @returns {void}
+                 */
                 $('#inline-edit .inline-edit-private input[value="private"]').click( function(){
                         var pw = $('input.inline-edit-password-input');
                         if ( $(this).prop('checked') ) {
@@ -48 +122 @@
                         }
                 });
 
-                // add events
+                /**
+                 * @summary Bind click event to the .editinline link which opens the quick editor.
+                 *
+                 * @returns {void}
+                 */
                 $('#the-list').on( 'click', 'a.editinline', function( e ) {
                         e.preventDefault();
                         inlineEditPost.edit(this);
@@ -62 +140 @@
 
                 $('select[name="_status"] option[value="future"]', bulkRow).remove();
 
+                /**
+                 * @summary Adds onclick events to the apply buttons.
+                 *
+                 * @returns {void}
+                 */
                 $('#doaction, #doaction2').click(function(e){
                         var n;
 
@@ -77 +160 @@
                 });
         },
 
+        /**
+         * @summary Toggles the quick edit window.
+         *
+         * Hides the window when it's active and shows the window when inactive.
+         *
+         * @memberof inlineEditPost
+         * @since 2.7.0
+         *
+         * @param {Object} el Element within a post table row.
+         *
+         * @returns {void}
+         */
         toggle : function(el){
                 var t = this;
                 $( t.what + t.getId( el ) ).css( 'display' ) === 'none' ? t.revert() : t.edit( el );
         },
 
+        /**
+         * @summary Creates the bulk editor row to edit multiple posts at once.
+         *
+         * @memberof inlineEditPost
+         * @since 2.7.0
+         *
+         * @returns {void}
+         */
         setBulk : function(){
                 var te = '', type = this.type, c = true;
                 this.revert();
 
                 $( '#bulk-edit td' ).attr( 'colspan', $( 'th:visible, td:visible', '.widefat:first thead' ).length );
+
                 // Insert the editor at the top of the table with an empty row above to maintain zebra striping.
                 $('table.widefat tbody').prepend( $('#bulk-edit') ).prepend('<tr class="hidden"></tr>');
                 $('#bulk-edit').addClass('inline-editor').show();
 
+                /**
+                 * @summary Create a HTML div with the title and a delete link(cross-icon) for each selected post.
+                 *
+                 * Get the selected posts based on the checked checkboxes in the post table.
+                 * Create a HTML div with the title and a link(delete-icon) for each selected post.
+                 *
+                 * @returns {void}
+                 */
                 $( 'tbody th.check-column input[type="checkbox"]' ).each( function() {
+
+                        // If the checkbox for a post is selected, add the post to the edit list.
                         if ( $(this).prop('checked') ) {
                                 c = false;
                                 var id = $(this).val(), theTitle;
@@ -100 +214 @@
                         }
                 });
 
+                // If no checkboxes where checked, just hide the quick/bulk edit rows.
                 if ( c ) {
                         return this.revert();
                 }
 
+                // Add onclick events to the delete-icons in the bulk editors the post title list.
                 $('#bulk-titles').html(te);
+
+                /**
+                 * @summary Binds on click events to the checkboxes before the posts in the table.
+                 *
+                 * @listens click
+                 *
+                 * @returns {void}
+                 */
                 $('#bulk-titles a').click(function(){
                         var id = $(this).attr('id').substr(1);
-
                         $('table.widefat input[value="' + id + '"]').prop('checked', false);
                         $('#ttle'+id).remove();
                 });
 
-                // enable autocomplete for tags
+                // Enable auto-complete for tags when editing posts.
                 if ( 'post' === type ) {
                         $( 'tr.inline-editor textarea[data-wp-taxonomy]' ).each( function ( i, element ) {
                                 $( element ).wpTagsSuggest();
                         } );
                 }
+
+                // Scrolls to the top of the table where the editor is rendered.
                 $('html, body').animate( { scrollTop: 0 }, 'fast' );
         },
 
+        /**
+         * @summary Creates a quick edit window for the post that has been clicked.
+         *
+         * @memberof inlineEditPost
+         * @since 2.7.0
+         *
+         * @param {number|Object} id The id of the clicked post or an element within a post
+         *                           table row.
+         *
+         * @returns {boolean} Always returns false at the end of execution.
+         */
         edit : function(id) {
                 var t = this, fields, editRow, rowData, status, pageOpt, pageLevel, nextPage, pageLoop = true, nextLevel, f, val, pw;
                 t.revert();
@@ -134 +270 @@
                         fields.push('post_parent', 'page_template');
                 }
 
-                // add the new edit row with an extra blank row underneath to maintain zebra striping.
+                // Add the new edit row with an extra blank row underneath to maintain zebra striping.
                 editRow = $('#inline-edit').clone(true);
                 $( 'td', editRow ).attr( 'colspan', $( 'th:visible, td:visible', '.widefat:first thead' ).length );
 
                 $(t.what+id).removeClass('is-expanded').hide().after(editRow).after('<tr class="hidden"></tr>');
 
-                // populate the data
+                // Populate fields in the quick edit window.
                 rowData = $('#inline_'+id);
                 if ( !$(':input[name="post_author"] option[value="' + $('.post_author', rowData).text() + '"]', editRow).val() ) {
-                        // author no longer has edit caps, so we need to add them to the list of authors
+                        // The post author no longer has edit capabilities, so we need to add them to the list of authors.
                         $(':input[name="post_author"]', editRow).prepend('<option value="' + $('.post_author', rowData).text() + '">' + $('#' + t.type + '-' + id + ' .author').text() + '</option>');
                 }
                 if ( $( ':input[name="post_author"] option', editRow ).length === 1 ) {
@@ -152 +288 @@
 
                 for ( f = 0; f < fields.length; f++ ) {
                         val = $('.'+fields[f], rowData);
-                        // Deal with Twemoji
+                        /**
+                         * @summary Replaces the image for a Twemoji(Twitter emoji) with it's alternate text.
+                         *
+                         * @returns Alternate text from the image.
+                         */
                         val.find( 'img' ).replaceWith( function() { return this.alt; } );
                         val = val.text();
                         $(':input[name="' + fields[f] + '"]', editRow).val( val );
@@ -168 +308 @@
                         $( 'input[name="sticky"]', editRow ).prop( 'checked', true );
                 }
 
-                // hierarchical taxonomies
+                /**
+                 * @summary Creates the select boxes for the categories.
+                 *
+                 * @returns {void}
+                 */
                 $('.post_category', rowData).each(function(){
                         var taxname,
                                 term_ids = $(this).text();
@@ -179 +323 @@
                         }
                 });
 
-                //flat taxonomies
+                /**
+                 * @summary Gets all the taxonomies for live auto-fill suggestions.
+                 * When typing the name of a tag.
+                 *
+                 * @returns {void}
+                 */
                 $('.tags_input', rowData).each(function(){
                         var terms = $(this),
                                 taxname = $(this).attr('id').replace('_' + id, ''),
@@ -240 +389 @@
                 return false;
         },
 
-        // Ajax saving is only for Quick Edit.
+
+        /**
+         * @summary Saves the changes made in the quick edit window to the post.
+         * AJAX saving is only for Quick Edit and not for bulk edit.
+         *
+         * @since 2.7.0
+         *
+         * @param   {int} id The id for the post that has been changed.
+         *
+         * @returns {boolean} Returns false so the form does not submit
+         *                    when pressing Enter on a focused field.
+         */
         save : function(id) {
                 var params, fields, page = $('.post_status_page').val() || '';
 
@@ -293 +453 @@
                 return false;
         },
 
-        // Revert is for both Quick Edit and Bulk Edit.
+        /**
+         * @summary Hides and empties the Quick Edit and/or Bulk Edit windows.
+         *
+         * @memberof    inlineEditPost
+         * @since 2.7.0
+         *
+         * @returns     {boolean} Always returns false.
+         */
         revert : function(){
                 var $tableWideFat = $( '.widefat' ),
                         id = $( '.inline-editor', $tableWideFat ).attr( 'id' );
@@ -303 +470 @@
                         $( '.ac_results' ).hide();
 
                         if ( 'bulk-edit' === id ) {
+                                // Hide the bulk editor.
                                 $( '#bulk-edit', $tableWideFat ).removeClass( 'inline-editor' ).hide().siblings( '.hidden' ).remove();
                                 $('#bulk-titles').empty();
+                                // Store the empty bulk editor in a hidden element.
                                 $('#inlineedit').append( $('#bulk-edit') );
                                 // Move focus back to the Bulk Action button that was activated.
                                 $( '#' + inlineEditPost.whichBulkButtonId ).focus();
                         } else {
+                                // Remove both the inline-editor and its hidden tr siblings.
                                 $('#'+id).siblings('tr.hidden').addBack().remove();
                                 id = id.substr( id.lastIndexOf('-') + 1 );
                                 // Show the post row and move focus back to the Quick Edit link.
@@ -319 +489 @@
                 return false;
         },
 
+        /**
+         * @summary Gets the id for a the post that you want to quick edit from the row
+         * in the quick edit table.
+         *
+         * @memberof    inlineEditPost
+         * @since 2.7.0
+         *
+         * @param   {Object} o DOM row object to get the id for.
+         *
+         * @returns {string} The post id extracted from the table row in the object.
+         */
         getId : function(o) {
                 var id = $(o).closest('tr').attr('id'),
                         parts = id.split('-');