Changeset 38644

Timestamp:

09/22/2016 06:49:26 PM (9 years ago)

Author:

SergeyBiryukov

Message:

Docs: Add documentation for wp-admin/js/inline-edit-tax.js.

Props atimmer, boblinthorst.
Fixes #37571.

File:

• trunk/src/wp-admin/js/inline-edit-tax.js (modified) (13 diffs)

trunk/src/wp-admin/js/inline-edit-tax.js

@@ -1 +1 @@
 /* global inlineEditL10n, ajaxurl */
+/**
+ * This file is used on the term overview page to power quick-editing terms.
+ */
+
 window.wp = window.wp || {};
 
+/**
+ * Consists of functions relevant to the inline taxonomy editor.
+ *
+ * @namespace inlineEditTax
+ *
+ * @property {string} type The type of inline edit we are currently on.
+ * @property {string} what The type property with a hash prefixed and a dash
+ *                         suffixed.
+ */
 var inlineEditTax;
+
 ( function( $, wp ) {
+
 inlineEditTax = {
 
+    /**
+     * @summary Initializes the inline taxonomy editor.
+     *
+     * Adds event handlers to be able to quick edit.
+     *
+     * @since 2.7.0
+     *
+     * @this inlineEditTax
+     * @memberof inlineEditTax
+     * @returns {void}
+     */
     init : function() {
         var t = this, row = $('#inline-edit');
@@ -17 +43 @@
         });
 
-        // prepare the edit row
+        /*
+         * @summary Cancels inline editing when pressing escape inside the inline editor.
+         *
+         * @param {Object} e The keyup event that has been triggered.
+         */
         row.keyup( function( e ) {
+            // 27 = [escape]
             if ( e.which === 27 ) {
                 return inlineEditTax.revert();
@@ -24 +55 @@
         });
 
+        /**
+         * @summary Cancels inline editing when clicking the cancel button.
+         */
         $( '.cancel', row ).click( function() {
             return inlineEditTax.revert();
         });
+
+        /**
+         * @summary Saves the inline edits when clicking the save button.
+         */
         $( '.save', row ).click( function() {
             return inlineEditTax.save(this);
         });
+
+        /**
+         * @summary Saves the inline edits when pressing enter inside the inline editor.
+         */
         $( 'input, select', row ).keydown( function( e ) {
+            // 13 = [enter]
             if ( e.which === 13 ) {
                 return inlineEditTax.save( this );
@@ -36 +79 @@
         });
 
+        /**
+         * @summary Saves the inline edits on submitting the inline edit form.
+         */
         $( '#posts-filter input[type="submit"]' ).mousedown( function() {
             t.revert();
@@ -41 +87 @@
     },
 
+    /**
+     * Toggles the quick edit based on if it is currently shown or hidden.
+     *
+     * @since 2.7.0
+     *
+     * @this inlineEditTax
+     * @memberof inlineEditTax
+     *
+     * @param {HTMLElement} el An element within the table row or the table row
+     *                         itself that we want to quick edit.
+     * @returns {void}
+     */
     toggle : function(el) {
         var t = this;
+
         $(t.what+t.getId(el)).css('display') === 'none' ? t.revert() : t.edit(el);
     },
 
+    /**
+     * Shows the quick editor
+     *
+     * @since 2.7.0
+     *
+     * @this inlineEditTax
+     * @memberof inlineEditTax
+     *
+     * @param {string|HTMLElement} id The ID of the term we want to quick edit or an
+     *                                element within the table row or the
+     * table row itself.
+     * @returns {boolean} Always returns false.
+     */
     edit : function(id) {
         var editRow, rowData, val,
@@ -51 +123 @@
         t.revert();
 
+        // Makes sure we can pass an HTMLElement as the ID.
         if ( typeof(id) === 'object' ) {
             id = t.getId(id);
@@ -76 +149 @@
     },
 
+    /**
+     * @summary Saves the quick edit data.
+     *
+     * Saves the quick edit data to the server and replaces the table row with the
+     * HTML retrieved from the server.
+     *
+     * @since 2.7.0
+     *
+     * @this inlineEditTax
+     * @memberof inlineEditTax
+     *
+     * @param {string|HTMLElement} id The ID of the term we want to quick edit or an
+     *                                element within the table row or the
+     * table row itself.
+     * @returns {boolean} Always returns false.
+     */
     save : function(id) {
         var params, fields, tax = $('input[name="taxonomy"]').val() || '';
 
+        // Makes sure we can pass an HTMLElement as the ID.
         if( typeof(id) === 'object' ) {
             id = this.getId(id);
@@ -95 +185 @@
         params = fields + '&' + $.param(params);
 
-        // make ajax request
+        // Do the ajax request to save the data to the server.
         $.post( ajaxurl, params,
+            /**
+             * @summary Handles the response from the server.
+             *
+             * Handles the response from the server, replaces the table row with the response
+             * from the server.
+             *
+             * @param {string} r The string with which to replace the table row.
+             */
             function(r) {
                 var row, new_id, option_value,
@@ -129 +227 @@
                     } else {
                         $errorSpan.html( r ).show();
-                        // Some error strings may contain HTML entities (e.g. `&#8220`), let's use the HTML element's text.
+                        /*
+                         * Some error strings may contain HTML entities (e.g. `&#8220`), let's use
+                         * the HTML element's text.
+                         */
                         wp.a11y.speak( $errorSpan.text() );
                     }
@@ -138 +239 @@
             }
         );
+
         // Prevent submitting the form when pressing Enter on a focused field.
         return false;
     },
 
+    /**
+     * Closes the quick edit form.
+     *
+     * @since 2.7.0
+     *
+     * @this inlineEditTax
+     * @memberof inlineEditTax
+     * @returns {void}
+     */
     revert : function() {
         var id = $('table.widefat tr.inline-editor').attr('id');
@@ -149 +260 @@
             $('#'+id).siblings('tr.hidden').addBack().remove();
             id = id.substr( id.lastIndexOf('-') + 1 );
+
             // Show the taxonomy row and move focus back to the Quick Edit link.
             $( this.what + id ).show().find( '.editinline' ).focus();
@@ -154 +266 @@
     },
 
+    /**
+     * Retrieves the ID of the term of the element inside the table row.
+     *
+     * @since 2.7.0
+     *
+     * @memberof inlineEditTax
+     *
+     * @param {HTMLElement} o An element within the table row or the table row itself.
+     * @returns {string} The ID of the term based on the element.
+     */
     getId : function(o) {
         var id = o.tagName === 'TR' ? o.id : $(o).parents('tr').attr('id'), parts = id.split('-');
+
         return parts[parts.length - 1];
     }
@@ -161 +284 @@
 
 $(document).ready(function(){inlineEditTax.init();});
+
 })( jQuery, window.wp );