From b4ea7855bc47eac2a7ad39a4f93a46731feed689 Mon Sep 17 00:00:00 2001 From: Anton Timmermans Date: Thu, 7 Jul 2016 16:44:45 +0200 Subject: [PATCH 1/5] Add documentation to wp-admin/js/postbox.js --- src/wp-admin/js/postbox.js | 105 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/src/wp-admin/js/postbox.js b/src/wp-admin/js/postbox.js index a8222ee..74f5def 100644 --- a/src/wp-admin/js/postbox.js +++ b/src/wp-admin/js/postbox.js @@ -1,11 +1,30 @@ /* 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. + * + * @namespace postboxes + * + * @type {Object} + */ var postboxes; (function($) { var $document = $( document ); postboxes = { + + /** + * 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. + * + * Triggers postboxes.pbshow if the postbox has just been opened, triggers postboxes.pbhide if the postbox has + * just been closed. + * + * @memberof postboxes + * @fires postboxes#postbox-toggled + */ handle_click : function () { var $el = $( this ), p = $el.parent( '.postbox' ), @@ -41,9 +60,26 @@ var postboxes; } } + /** + * Fires when the postbox has been opened or closed. Contains a jQuery object with the postbox element in + * it. + * + * @event postboxes#postbox-toggled + * @type {Object} + */ $document.trigger( 'postbox-toggled', p ); }, + /** + * Adds event handlers to all postboxes and screen option on the current page. + * + * @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. + */ add_postbox_toggles : function (page, args) { var $handles = $( '.postbox .hndle, .postbox .handlediv' ); @@ -56,12 +92,21 @@ var postboxes; e.stopPropagation(); }); + /** + * Adds an event handler to the dismissal of a postbox. Event handler completely hides the postbox element + * and it cannot be closed or opened afterwards. + */ $( '.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'); }); + /** + * Adds an event handler to the screen option checkboxes. Event handler completely hides the postbox element + * + * @fires postboxes#postbox-toggled + */ $('.hide-postbox-tog').bind('click.postboxes', function() { var $el = $(this), boxId = $el.val(), @@ -78,11 +123,15 @@ var postboxes; postboxes.pbhide( boxId ); } } + postboxes.save_state( page ); postboxes._mark_area(); $document.trigger( 'postbox-toggled', $postbox ); }); + /** + * Adds an event handler to the screen options layout preferences. + */ $('.columns-prefs input[type="radio"]').bind('click.postboxes', function(){ var n = parseInt($(this).val(), 10); @@ -93,6 +142,16 @@ var postboxes; }); }, + /** + * Initializes all the postboxes, mainly their sortable behaviour. + * + * @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. + */ init : function(page, args) { var isMobile = $( document.body ).hasClass( 'mobile' ), $handleButtons = $( '.postbox .handlediv' ); @@ -157,6 +216,14 @@ var postboxes; }); }, + /** + * 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. + * + * @memberof postboxes + * + * @param {string} page The page we are currently on. + */ save_state : function(page) { var closed, hidden; @@ -177,6 +244,14 @@ var postboxes; }); }, + /** + * Saves the order of the postboxes to the server. Sends a list of all postboxes inside a sortable area to the + * server. + * + * @memberof postboxes + * + * @param {string} page The page we are currently on. + */ save_order : function(page) { var postVars, page_columns = $('.columns-prefs input:checked').val() || 0; @@ -186,12 +261,21 @@ var postboxes; page_columns: page_columns, page: page }; + $('.meta-box-sortables').each( function() { postVars[ 'order[' + this.id.split( '-' )[0] + ']' ] = $( this ).sortable( 'toArray' ).join( ',' ); } ); + $.post( ajaxurl, postVars ); }, + /** + * 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. + * + * @memberof postboxes + * @private + */ _mark_area : function() { var visible = $('div.postbox:visible').length, side = $('#post-body #side-sortables'); @@ -215,6 +299,15 @@ var postboxes; } }, + /** + * Changes the amount of columns on the post edit page. + * + * @memberof postboxes + * @fires postboxes#postboxes-columnchange + * @private + * + * @param {number} n The amount of columns to divide the post edit page in. + */ _pb_edit : function(n) { var el = $('.metabox-holder').get(0); @@ -222,9 +315,21 @@ var postboxes; el.className = el.className.replace(/columns-\d+/, 'columns-' + n); } + /** + * Fires when the amount of columns on the post edit page has been changed. + * + * @event postboxes#postboxes-columnchange + */ $( document ).trigger( 'postboxes-columnchange' ); }, + /** + * Changes the postboxes based on the current orientation of the browser. Meant to be called when the + * orientation of the browser changes. + * + * @memberof postboxes + * @private + */ _pb_change : function() { var check = $( 'label.columns-prefs-1 input[type="radio"]' ); From 68e82d0105e03727cda2850bd6e2a49acdacaa11 Mon Sep 17 00:00:00 2001 From: Anton Timmermans Date: Thu, 7 Jul 2016 16:54:46 +0200 Subject: [PATCH 2/5] Add documentation to pbshow and pbhide --- src/wp-admin/js/postbox.js | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/wp-admin/js/postbox.js b/src/wp-admin/js/postbox.js index 74f5def..0b0be34 100644 --- a/src/wp-admin/js/postbox.js +++ b/src/wp-admin/js/postbox.js @@ -352,8 +352,17 @@ var postboxes; }, /* Callbacks */ + + /** + * @property {Function|boolean} pbshow A callback that is called when a postbox is opened. + * @memberof postboxes + */ pbshow : false, + /** + * @property {Function|boolean} pbhide A callback that is called when a postbox is closed. + * @memberof postboxes + */ pbhide : false }; From dbc91371f87df6aec7a69af4d027b71abbe7ccc5 Mon Sep 17 00:00:00 2001 From: Anton Timmermans Date: Thu, 14 Jul 2016 15:20:03 +0200 Subject: [PATCH 3/5] Add comment to duplicate event trigger --- src/wp-admin/js/postbox.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/wp-admin/js/postbox.js b/src/wp-admin/js/postbox.js index 0b0be34..2b713f2 100644 --- a/src/wp-admin/js/postbox.js +++ b/src/wp-admin/js/postbox.js @@ -126,6 +126,10 @@ var postboxes; postboxes.save_state( page ); postboxes._mark_area(); + + /** + * @see postboxes.handle_click + */ $document.trigger( 'postbox-toggled', $postbox ); }); From b852e8c059b1e43154e232898a504c4ed2b82127 Mon Sep 17 00:00:00 2001 From: Anton Timmermans Date: Thu, 14 Jul 2016 21:53:24 +0200 Subject: [PATCH 4/5] Add @since tags --- src/wp-admin/js/postbox.js | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/wp-admin/js/postbox.js b/src/wp-admin/js/postbox.js index 2b713f2..767a4d6 100644 --- a/src/wp-admin/js/postbox.js +++ b/src/wp-admin/js/postbox.js @@ -4,6 +4,8 @@ * 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} @@ -22,6 +24,7 @@ var postboxes; * Triggers postboxes.pbshow if the postbox has just been opened, triggers postboxes.pbhide if the postbox has * just been closed. * + * @since 4.4.0 * @memberof postboxes * @fires postboxes#postbox-toggled */ @@ -64,6 +67,7 @@ var postboxes; * Fires when the postbox has been opened or closed. Contains a jQuery object with the postbox element in * it. * + * @since 4.0.0 * @event postboxes#postbox-toggled * @type {Object} */ @@ -73,6 +77,7 @@ var postboxes; /** * 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. @@ -128,6 +133,7 @@ var postboxes; postboxes._mark_area(); /** + * @since 4.0.0 * @see postboxes.handle_click */ $document.trigger( 'postbox-toggled', $postbox ); @@ -149,6 +155,7 @@ var postboxes; /** * Initializes all the postboxes, mainly their sortable behaviour. * + * @since 2.7.0 * @memberof postboxes * * @param {string} page The page we are currently on. @@ -224,6 +231,7 @@ var postboxes; * 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. @@ -252,6 +260,7 @@ var postboxes; * 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. @@ -277,6 +286,7 @@ var postboxes; * 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 * @private */ @@ -306,6 +316,7 @@ var postboxes; /** * Changes the amount of columns on the post edit page. * + * @since 3.3.0 * @memberof postboxes * @fires postboxes#postboxes-columnchange * @private @@ -331,6 +342,7 @@ var postboxes; * Changes the postboxes based on the current orientation of the browser. Meant to be called when the * orientation of the browser changes. * + * @since 3.3.0 * @memberof postboxes * @private */ @@ -358,12 +370,14 @@ var postboxes; /* Callbacks */ /** + * @since 2.7.0 * @property {Function|boolean} pbshow A callback that is called when a postbox is opened. * @memberof postboxes */ pbshow : false, /** + * @since 2.7.0 * @property {Function|boolean} pbhide A callback that is called when a postbox is closed. * @memberof postboxes */ From e762ed0b8d7c27b15da5ff42bb0e88cdc2969963 Mon Sep 17 00:00:00 2001 From: Anton Timmermans Date: Thu, 14 Jul 2016 22:48:58 +0200 Subject: [PATCH 5/5] Follow WordPress JS Documentation standards --- src/wp-admin/js/postbox.js | 104 +++++++++++++++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 33 deletions(-) diff --git a/src/wp-admin/js/postbox.js b/src/wp-admin/js/postbox.js index 767a4d6..ce4cf85 100644 --- a/src/wp-admin/js/postbox.js +++ b/src/wp-admin/js/postbox.js @@ -1,3 +1,13 @@ +/** + * 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 */ /** @@ -18,11 +28,11 @@ var postboxes; postboxes = { /** - * 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. + * @summary Handles a click on either the postbox heading or the postbox open/close icon. * - * Triggers postboxes.pbshow if the postbox has just been opened, triggers postboxes.pbhide if the postbox has - * just been closed. + * 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 @@ -64,8 +74,9 @@ var postboxes; } /** - * Fires when the postbox has been opened or closed. Contains a jQuery object with the postbox element in - * it. + * @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 @@ -93,13 +104,20 @@ var postboxes; $handles.on( 'click.postboxes', this.handle_click ); + /** + * @since 2.7.0 + */ $('.postbox .hndle a').click( function(e) { e.stopPropagation(); }); /** - * Adds an event handler to the dismissal of a postbox. Event handler completely hides the postbox element - * and it cannot be closed or opened afterwards. + * @summary Hides a postbox. + * + * Event handler for the postbox dismiss button. After clicking the button + * the postbox will be hidden. + * + * @since 3.2.0 */ $( '.postbox a.dismiss' ).on( 'click.postboxes', function( e ) { var hide_id = $(this).parents('.postbox').attr('id') + '-hide'; @@ -108,8 +126,12 @@ var postboxes; }); /** - * Adds an event handler to the screen option checkboxes. Event handler completely hides the postbox element + * @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 */ $('.hide-postbox-tog').bind('click.postboxes', function() { @@ -140,7 +162,9 @@ var postboxes; }); /** - * Adds an event handler to the screen options layout preferences. + * @summary Changes the amount of columns based on the layout preferences. + * + * @since 2.8.0 */ $('.columns-prefs input[type="radio"]').bind('click.postboxes', function(){ var n = parseInt($(this).val(), 10); @@ -153,15 +177,16 @@ var postboxes; }, /** - * Initializes all the postboxes, mainly their sortable behaviour. + * @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] + * @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. + * @param {Function} args.pbhide A callback that is called when a postbox + * closes. */ init : function(page, args) { var isMobile = $( document.body ).hasClass( 'mobile' ), @@ -180,12 +205,13 @@ var postboxes; 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 ) { @@ -228,8 +254,10 @@ var postboxes; }, /** - * 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. + * @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 @@ -257,8 +285,10 @@ var postboxes; }, /** - * Saves the order of the postboxes to the server. Sends a list of all postboxes inside a sortable area to the - * server. + * @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 @@ -283,12 +313,15 @@ var postboxes; }, /** - * 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. + * @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 - * @private + * @access private */ _mark_area : function() { var visible = $('div.postbox:visible').length, side = $('#post-body #side-sortables'); @@ -314,12 +347,12 @@ var postboxes; }, /** - * Changes the amount of columns on the post edit page. + * @summary Changes the amount of columns on the post edit page. * * @since 3.3.0 * @memberof postboxes * @fires postboxes#postboxes-columnchange - * @private + * @access private * * @param {number} n The amount of columns to divide the post edit page in. */ @@ -333,18 +366,19 @@ var postboxes; /** * 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' ); }, /** - * Changes the postboxes based on the current orientation of the browser. Meant to be called when the - * orientation of the browser changes. + * @summary Changes the amount of columns the postboxes are in based on the + * current orientation of the browser. * * @since 3.3.0 * @memberof postboxes - * @private + * @access private */ _pb_change : function() { var check = $( 'label.columns-prefs-1 input[type="radio"]' ); @@ -371,15 +405,19 @@ var postboxes; /** * @since 2.7.0 - * @property {Function|boolean} pbshow A callback that is called when a postbox is opened. * @memberof postboxes + * @access public + * @property {Function|boolean} pbshow A callback that is called when a postbox + * is opened. */ pbshow : false, /** * @since 2.7.0 - * @property {Function|boolean} pbhide A callback that is called when a postbox is closed. * @memberof postboxes + * @access public + * @property {Function|boolean} pbhide A callback that is called when a postbox + * is closed. */ pbhide : false };