WordPress.org

Make WordPress Core

Changeset 38643


Ignore:
Timestamp:
09/22/2016 06:46:34 PM (4 years ago)
Author:
SergeyBiryukov
Message:

Docs: Add documentation for wp-admin/js/postbox.js.

Props atimmer, andizer.
Fixes #37365.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/js/postbox.js

    r37659 r38643  
     1/**
     2 * Contains the postboxes logic, opening and closing postboxes, reordering and saving
     3 * the state and ordering to the database.
     4 *
     5 * @summary Contains postboxes logic
     6 *
     7 * @since 2.5.0
     8 * @requires jQuery
     9 */
     10
    111/* global ajaxurl, postBoxL10n */
    212
     13/**
     14 * This object contains all function to handle the behaviour of the post boxes. The post boxes are the boxes you see
     15 * around the content on the edit page.
     16 *
     17 * @since 2.7.0
     18 *
     19 * @namespace postboxes
     20 *
     21 * @type {Object}
     22 */
    323var postboxes;
    424
     
    727
    828    postboxes = {
     29
     30        /**
     31         * @summary Handles a click on either the postbox heading or the postbox open/close icon.
     32         *
     33         * Opens or closes the postbox. Expects `this` to equal the clicked element.
     34         * Calls postboxes.pbshow if the postbox has been opened, calls postboxes.pbhide
     35         * if the postbox has been closed.
     36         *
     37         * @since 4.4.0
     38         * @memberof postboxes
     39         * @fires postboxes#postbox-toggled
     40         *
     41         * @returns {void}
     42         */
    943        handle_click : function () {
    1044            var $el = $( this ),
     
    4276            }
    4377
     78            /**
     79             * @summary Fires when a postbox has been opened or closed.
     80             *
     81             * Contains a jQuery object with the relevant postbox element.
     82             *
     83             * @since 4.0.0
     84             * @event postboxes#postbox-toggled
     85             * @type {Object}
     86             */
    4487            $document.trigger( 'postbox-toggled', p );
    4588        },
    4689
     90        /**
     91         * Adds event handlers to all postboxes and screen option on the current page.
     92         *
     93         * @since 2.7.0
     94         * @memberof postboxes
     95         *
     96         * @param {string} page The page we are currently on.
     97         * @param {Object} [args]
     98         * @param {Function} args.pbshow A callback that is called when a postbox opens.
     99         * @param {Function} args.pbhide A callback that is called when a postbox closes.
     100         * @returns {void}
     101         */
    47102        add_postbox_toggles : function (page, args) {
    48103            var $handles = $( '.postbox .hndle, .postbox .handlediv' );
     
    53108            $handles.on( 'click.postboxes', this.handle_click );
    54109
     110            /**
     111             * @since 2.7.0
     112             */
    55113            $('.postbox .hndle a').click( function(e) {
    56114                e.stopPropagation();
    57115            });
    58116
     117            /**
     118             * @summary Hides a postbox.
     119             *
     120             * Event handler for the postbox dismiss button. After clicking the button
     121             * the postbox will be hidden.
     122             *
     123             * @since 3.2.0
     124             *
     125             * @returns {void}
     126             */
    59127            $( '.postbox a.dismiss' ).on( 'click.postboxes', function( e ) {
    60128                var hide_id = $(this).parents('.postbox').attr('id') + '-hide';
     
    63131            });
    64132
     133            /**
     134             * @summary Hides the postbox element
     135             *
     136             * Event handler for the screen options checkboxes. When a checkbox is
     137             * clicked this function will hide or show the relevant postboxes.
     138             *
     139             * @since 2.7.0
     140             * @fires postboxes#postbox-toggled
     141             *
     142             * @returns {void}
     143             */
    65144            $('.hide-postbox-tog').bind('click.postboxes', function() {
    66145                var $el = $(this),
     
    79158                    }
    80159                }
     160
    81161                postboxes.save_state( page );
    82162                postboxes._mark_area();
     163
     164                /**
     165                 * @since 4.0.0
     166                 * @see postboxes.handle_click
     167                 */
    83168                $document.trigger( 'postbox-toggled', $postbox );
    84169            });
    85170
     171            /**
     172             * @summary Changes the amount of columns based on the layout preferences.
     173             *
     174             * @since 2.8.0
     175             *
     176             * @returns {void}
     177             */
    86178            $('.columns-prefs input[type="radio"]').bind('click.postboxes', function(){
    87179                var n = parseInt($(this).val(), 10);
     
    94186        },
    95187
     188        /**
     189         * @summary Initializes all the postboxes, mainly their sortable behaviour.
     190         *
     191         * @since 2.7.0
     192         * @memberof postboxes
     193         *
     194         * @param {string} page The page we are currently on.
     195         * @param {Object} [args={}] The arguments for the postbox initializer.
     196         * @param {Function} args.pbshow A callback that is called when a postbox opens.
     197         * @param {Function} args.pbhide A callback that is called when a postbox
     198         *                               closes.
     199         *
     200         * @returns {void}
     201         */
    96202        init : function(page, args) {
    97203            var isMobile = $( document.body ).hasClass( 'mobile' ),
     
    111217                forcePlaceholderSize: true,
    112218                helper: function( event, element ) {
    113                     // `helper: 'clone'` is equivalent to `return element.clone();`
    114                     // Cloning a checked radio and then inserting that clone next to the original
    115                     // radio unchecks the original radio (since only one of the two can be checked).
    116                     // We get around this by renaming the helper's inputs' name attributes so that,
    117                     // when the helper is inserted into the DOM for the sortable, no radios are
    118                     // duplicated, and no original radio gets unchecked.
     219                    /* `helper: 'clone'` is equivalent to `return element.clone();`
     220                     * Cloning a checked radio and then inserting that clone next to the original
     221                     * radio unchecks the original radio (since only one of the two can be checked).
     222                     * We get around this by renaming the helper's inputs' name attributes so that,
     223                     * when the helper is inserted into the DOM for the sortable, no radios are
     224                     * duplicated, and no original radio gets unchecked.
     225                     */
    119226                    return element.clone()
    120227                        .find( ':input' )
     
    158265        },
    159266
     267        /**
     268         * @summary Saves the state of the postboxes to the server.
     269         *
     270         * Saves the state of the postboxes to the server. It sends two lists, one with
     271         * all the closed postboxes, one with all the hidden postboxes.
     272         *
     273         * @since 2.7.0
     274         * @memberof postboxes
     275         *
     276         * @param {string} page The page we are currently on.
     277         * @returns {void}
     278         */
    160279        save_state : function(page) {
    161280            var closed, hidden;
     
    178297        },
    179298
     299        /**
     300         * @summary Saves the order of the postboxes to the server.
     301         *
     302         * Saves the order of the postboxes to the server. Sends a list of all postboxes
     303         * inside a sortable area to the server.
     304         *
     305         * @since 2.8.0
     306         * @memberof postboxes
     307         *
     308         * @param {string} page The page we are currently on.
     309         * @returns {void}
     310         */
    180311        save_order : function(page) {
    181312            var postVars, page_columns = $('.columns-prefs input:checked').val() || 0;
     
    187318                page: page
    188319            };
     320
    189321            $('.meta-box-sortables').each( function() {
    190322                postVars[ 'order[' + this.id.split( '-' )[0] + ']' ] = $( this ).sortable( 'toArray' ).join( ',' );
    191323            } );
     324
    192325            $.post( ajaxurl, postVars );
    193326        },
    194327
     328        /**
     329         * @summary Marks empty postbox areas.
     330         *
     331         * Adds a message to empty sortable areas on the dashboard page. Also adds a
     332         * border around the side area on the post edit screen if there are no postboxes
     333         * present.
     334         *
     335         * @since 3.3.0
     336         * @memberof postboxes
     337         * @access private
     338         *
     339         * @returns {void}
     340         */
    195341        _mark_area : function() {
    196342            var visible = $('div.postbox:visible').length, side = $('#post-body #side-sortables');
     
    216362        },
    217363
     364        /**
     365         * @summary Changes the amount of columns on the post edit page.
     366         *
     367         * @since 3.3.0
     368         * @memberof postboxes
     369         * @fires postboxes#postboxes-columnchange
     370         * @access private
     371         *
     372         * @param {number} n The amount of columns to divide the post edit page in.
     373         * @returns {void}
     374         */
    218375        _pb_edit : function(n) {
    219376            var el = $('.metabox-holder').get(0);
     
    223380            }
    224381
     382            /**
     383             * Fires when the amount of columns on the post edit page has been changed.
     384             *
     385             * @since 4.0.0
     386             * @event postboxes#postboxes-columnchange
     387             */
    225388            $( document ).trigger( 'postboxes-columnchange' );
    226389        },
    227390
     391        /**
     392         * @summary Changes the amount of columns the postboxes are in based on the
     393         *          current orientation of the browser.
     394         *
     395         * @since 3.3.0
     396         * @memberof postboxes
     397         * @access private
     398         *
     399         * @returns {void}
     400         */
    228401        _pb_change : function() {
    229402            var check = $( 'label.columns-prefs-1 input[type="radio"]' );
     
    248421
    249422        /* Callbacks */
     423
     424        /**
     425         * @since 2.7.0
     426         * @memberof postboxes
     427         * @access public
     428         * @property {Function|boolean} pbshow A callback that is called when a postbox
     429         *                                     is opened.
     430         */
    250431        pbshow : false,
    251432
     433        /**
     434         * @since 2.7.0
     435         * @memberof postboxes
     436         * @access public
     437         * @property {Function|boolean} pbhide A callback that is called when a postbox
     438         *                                     is closed.
     439         */
    252440        pbhide : false
    253441    };
Note: See TracChangeset for help on using the changeset viewer.