Ticket #37365: document-postbox.diff

src/wp-admin/js/postbox.js

@@ +1 @@
+/**
+ * Contains the postboxes logic, opening and closing postboxes, reordering and saving
+ * the state and ordering to the database.
+ *
+ * @summary Contains postboxes logic
+ *
+ * @since 2.4.0
+ * @requires jQuery
+ */
+
 /* global ajaxurl, postBoxL10n */
 
+/**
+ * This object contains all function to handle the behaviour of the post boxes. The post boxes are the boxes you see
+ * around the content on the edit page.
+ *
+ * @since 2.7.0
+ *
+ * @namespace postboxes
+ *
+ * @type {Object}
+ */
 var postboxes;
 
 (function($) {
         var $document = $( document );
 
         postboxes = {
+
+                /**
+                 * @summary Handles a click on either the postbox heading or the postbox open/close icon.
+                 *
+                 * Opens or closes the postbox. Expects `this` to equal the clicked element.
+                 * Calls postboxes.pbshow if the postbox has been opened, calls postboxes.pbhide
+                 * if the postbox has been closed.
+                 *
+                 * @since 4.4.0
+                 * @memberof postboxes
+                 * @fires postboxes#postbox-toggled
+                 *
+                 * @returns {void}
+                 */
                 handle_click : function () {
                         var $el = $( this ),
                                 p = $el.parent( '.postbox' ),
@@ -41 +75 @@
                                 }
                         }
 
+                        /**
+                         * @summary Fires when a postbox has been opened or closed.
+                         *
+                         * Contains a jQuery object with the relevant postbox element.
+                         *
+                         * @since 4.0.0
+                         * @event postboxes#postbox-toggled
+                         * @type {Object}
+                         */
                         $document.trigger( 'postbox-toggled', p );
                 },
 
+                /**
+                 * Adds event handlers to all postboxes and screen option on the current page.
+                 *
+                 * @since 2.7.0
+                 * @memberof postboxes
+                 *
+                 * @param {string} page The page we are currently on.
+                 * @param {Object} [args]
+                 * @param {Function} args.pbshow A callback that is called when a postbox opens.
+                 * @param {Function} args.pbhide A callback that is called when a postbox closes.
+                 * @returns {void}
+                 */
                 add_postbox_toggles : function (page, args) {
                         var $handles = $( '.postbox .hndle, .postbox .handlediv' );
 
@@ -52 +107 @@
 
                         $handles.on( 'click.postboxes', this.handle_click );
 
+                        /**
+                         * @since 2.7.0
+                         */
                         $('.postbox .hndle a').click( function(e) {
                                 e.stopPropagation();
                         });
 
+                        /**
+                         * @summary Hides a postbox.
+                         *
+                         * Event handler for the postbox dismiss button. After clicking the button
+                         * the postbox will be hidden.
+                         *
+                         * @since 3.2.0
+                         *
+                         * @returns {void}
+                         */
                         $( '.postbox a.dismiss' ).on( 'click.postboxes', function( e ) {
                                 var hide_id = $(this).parents('.postbox').attr('id') + '-hide';
                                 e.preventDefault();
                                 $( '#' + hide_id ).prop('checked', false).triggerHandler('click');
                         });
 
+                        /**
+                         * @summary Hides the postbox element
+                         *
+                         * Event handler for the screen options checkboxes. When a checkbox is
+                         * clicked this function will hide or show the relevant postboxes.
+                         *
+                         * @since 2.7.0
+                         * @fires postboxes#postbox-toggled
+                         *
+                         * @returns {void}
+                         */
                         $('.hide-postbox-tog').bind('click.postboxes', function() {
                                 var $el = $(this),
                                         boxId = $el.val(),
@@ -78 +157 @@
                                                 postboxes.pbhide( boxId );
                                         }
                                 }
+
                                 postboxes.save_state( page );
                                 postboxes._mark_area();
+
+                                /**
+                                 * @since 4.0.0
+                                 * @see postboxes.handle_click
+                                 */
                                 $document.trigger( 'postbox-toggled', $postbox );
                         });
 
+                        /**
+                         * @summary Changes the amount of columns based on the layout preferences.
+                         *
+                         * @since 2.8.0
+                         *
+                         * @returns {void}
+                         */
                         $('.columns-prefs input[type="radio"]').bind('click.postboxes', function(){
                                 var n = parseInt($(this).val(), 10);
 
@@ -93 +185 @@
                         });
                 },
 
+                /**
+                 * @summary Initializes all the postboxes, mainly their sortable behaviour.
+                 *
+                 * @since 2.7.0
+                 * @memberof postboxes
+                 *
+                 * @param {string} page The page we are currently on.
+                 * @param {Object} [args={}] The arguments for the postbox initializer.
+                 * @param {Function} args.pbshow A callback that is called when a postbox opens.
+                 * @param {Function} args.pbhide A callback that is called when a postbox
+                 *                               closes.
+                 *
+                 * @returns {void}
+                 */
                 init : function(page, args) {
                         var isMobile = $( document.body ).hasClass( 'mobile' ),
                                 $handleButtons = $( '.postbox .handlediv' );
@@ -110 +216 @@
                                 tolerance: 'pointer',
                                 forcePlaceholderSize: true,
                                 helper: function( event, element ) {
-                                        // `helper: 'clone'` is equivalent to `return element.clone();`
-                                        // Cloning a checked radio and then inserting that clone next to the original
-                                        // radio unchecks the original radio (since only one of the two can be checked).
-                                        // We get around this by renaming the helper's inputs' name attributes so that,
-                                        // when the helper is inserted into the DOM for the sortable, no radios are
-                                        // duplicated, and no original radio gets unchecked.
+                                        /* `helper: 'clone'` is equivalent to `return element.clone();`
+                                         * Cloning a checked radio and then inserting that clone next to the original
+                                         * radio unchecks the original radio (since only one of the two can be checked).
+                                         * We get around this by renaming the helper's inputs' name attributes so that,
+                                         * when the helper is inserted into the DOM for the sortable, no radios are
+                                         * duplicated, and no original radio gets unchecked.
+                                         */
                                         return element.clone()
                                                 .find( ':input' )
                                                         .attr( 'name', function( i, currentName ) {
@@ -157 +264 @@
                         });
                 },
 
+                /**
+                 * @summary Saves the state of the postboxes to the server.
+                 *
+                 * Saves the state of the postboxes to the server. It sends two lists, one with
+                 * all the closed postboxes, one with all the hidden postboxes.
+                 *
+                 * @since 2.7.0
+                 * @memberof postboxes
+                 *
+                 * @param {string} page The page we are currently on.
+                 * @returns {void}
+                 */
                 save_state : function(page) {
                         var closed, hidden;
 
@@ -177 +296 @@
                         });
                 },
 
+                /**
+                 * @summary Saves the order of the postboxes to the server.
+                 *
+                 * Saves the order of the postboxes to the server. Sends a list of all postboxes
+                 * inside a sortable area to the server.
+                 *
+                 * @since 2.8.0
+                 * @memberof postboxes
+                 *
+                 * @param {string} page The page we are currently on.
+                 * @returns {void}
+                 */
                 save_order : function(page) {
                         var postVars, page_columns = $('.columns-prefs input:checked').val() || 0;
 
@@ -186 +317 @@
                                 page_columns: page_columns,
                                 page: page
                         };
+
                         $('.meta-box-sortables').each( function() {
                                 postVars[ 'order[' + this.id.split( '-' )[0] + ']' ] = $( this ).sortable( 'toArray' ).join( ',' );
                         } );
+
                         $.post( ajaxurl, postVars );
                 },
 
+                /**
+                 * @summary Marks empty postbox areas.
+                 *
+                 * Adds a message to empty sortable areas on the dashboard page. Also adds a
+                 * border around the side area on the post edit screen if there are no postboxes
+                 * present.
+                 *
+                 * @since 3.3.0
+                 * @memberof postboxes
+                 * @access private
+                 *
+                 * @returns {void}
+                 */
                 _mark_area : function() {
                         var visible = $('div.postbox:visible').length, side = $('#post-body #side-sortables');
 
@@ -215 +361 @@
                         }
                 },
 
+                /**
+                 * @summary Changes the amount of columns on the post edit page.
+                 *
+                 * @since 3.3.0
+                 * @memberof postboxes
+                 * @fires postboxes#postboxes-columnchange
+                 * @access private
+                 *
+                 * @param {number} n The amount of columns to divide the post edit page in.
+                 * @returns {void}
+                 */
                 _pb_edit : function(n) {
                         var el = $('.metabox-holder').get(0);
 
@@ -222 +379 @@
                                 el.className = el.className.replace(/columns-\d+/, 'columns-' + n);
                         }
 
+                        /**
+                         * Fires when the amount of columns on the post edit page has been changed.
+                         *
+                         * @since 4.0.0
+                         * @event postboxes#postboxes-columnchange
+                         */
                         $( document ).trigger( 'postboxes-columnchange' );
                 },
 
+                /**
+                 * @summary Changes the amount of columns the postboxes are in based on the
+                 *          current orientation of the browser.
+                 *
+                 * @since 3.3.0
+                 * @memberof postboxes
+                 * @access private
+                 *
+                 * @returns {void}
+                 */
                 _pb_change : function() {
                         var check = $( 'label.columns-prefs-1 input[type="radio"]' );
 
@@ -247 +420 @@
                 },
 
                 /* Callbacks */
+
+                /**
+                 * @since 2.7.0
+                 * @memberof postboxes
+                 * @access public
+                 * @property {Function|boolean} pbshow A callback that is called when a postbox
+                 *                                     is opened.
+                 */
                 pbshow : false,
 
+                /**
+                 * @since 2.7.0
+                 * @memberof postboxes
+                 * @access public
+                 * @property {Function|boolean} pbhide A callback that is called when a postbox
+                 *                                     is closed.
+                 */
                 pbhide : false
         };