mirror of
https://github.com/WordPress/WordPress.git
synced 2024-12-23 01:27:36 +01:00
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
This commit is contained in:
parent
b558fbec6f
commit
78138cd2c7
@ -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
|
||||
};
|
||||
|
||||
|
@ -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.
|
||||
|
Loading…
Reference in New Issue
Block a user