From 78138cd2c7734aa676a92fdd92f627ee6570cc3d Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Thu, 22 Sep 2016 18:47:31 +0000 Subject: [PATCH] Docs: Add documentation for `wp-admin/js/postbox.js`. Props atimmer, andizer. Fixes #37365. Built from https://develop.svn.wordpress.org/trunk@38643 git-svn-id: http://core.svn.wordpress.org/trunk@38586 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/js/postbox.js | 200 ++++++++++++++++++++++++++++++++++++++-- wp-includes/version.php | 2 +- 2 files changed, 195 insertions(+), 7 deletions(-) diff --git a/wp-admin/js/postbox.js b/wp-admin/js/postbox.js index a8222ee296..bbc73b2a69 100644 --- a/wp-admin/js/postbox.js +++ b/wp-admin/js/postbox.js @@ -1,11 +1,45 @@ +/** + * Contains the postboxes logic, opening and closing postboxes, reordering and saving + * the state and ordering to the database. + * + * @summary Contains postboxes logic + * + * @since 2.5.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,9 +75,30 @@ var postboxes; } } + /** + * @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,16 +107,40 @@ var postboxes; $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,11 +157,24 @@ var postboxes; 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,6 +185,20 @@ var postboxes; }); }, + /** + * @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,12 +216,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 ) { @@ -157,6 +264,18 @@ var 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 + * + * @param {string} page The page we are currently on. + * @returns {void} + */ save_state : function(page) { var closed, hidden; @@ -177,6 +296,18 @@ var postboxes; }); }, + /** + * @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,12 +317,27 @@ 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 ); }, + /** + * @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,6 +361,17 @@ var postboxes; } }, + /** + * @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,9 +379,25 @@ 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. + * + * @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,8 +420,23 @@ var postboxes; }, /* 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 }; diff --git a/wp-includes/version.php b/wp-includes/version.php index 8fb7edcfc9..1a18937aa7 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '4.7-alpha-38642'; +$wp_version = '4.7-alpha-38643'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.