WordPress.org
Get WordPress

Make WordPress Core

Ticket #37365: document-postbox.2.patch

File document-postbox.2.patch, 19.9 KB (added by atimmer, 10 years ago)

  • src/wp-admin/js/postbox.js 

    From b4ea7855bc47eac2a7ad39a4f93a46731feed689 Mon Sep 17 00:00:00 2001
From: Anton Timmermans <email@atimmer.com>
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 b  
    11/* global ajaxurl, postBoxL10n */
    22
     3/**
     4 * This object contains all function to handle the behaviour of the post boxes. The post boxes are the boxes you see
     5 * around the content on the edit page.
     6 *
     7 * @namespace postboxes
     8 *
     9 * @type {Object}
     10 */
    311var postboxes;
    412
    513(function($) {
    614        var $document = $( document );
    715
    816        postboxes = {
     17
     18                /**
     19                 * Handles a click on either the postbox heading or the postbox open/close icon. Opens or closes the postbox.
     20                 * Expects this to equal the clicked element.
     21                 *
     22                 * Triggers postboxes.pbshow if the postbox has just been opened, triggers postboxes.pbhide if the postbox has
     23                 * just been closed.
     24                 *
     25                 * @memberof postboxes
     26                 * @fires postboxes#postbox-toggled
     27                 */
    928                handle_click : function () {
    1029                        var $el = $( this ),
    1130                                p = $el.parent( '.postbox' ),
    … … var postboxes;  
    4160                                }
    4261                        }
    4362
     63                        /**
     64                         * Fires when the postbox has been opened or closed. Contains a jQuery object with the postbox element in
     65                         * it.
     66                         *
     67                         * @event postboxes#postbox-toggled
     68                         * @type {Object}
     69                         */
    4470                        $document.trigger( 'postbox-toggled', p );
    4571                },
    4672
     73                /**
     74                 * Adds event handlers to all postboxes and screen option on the current page.
     75                 *
     76                 * @memberof postboxes
     77                 *
     78                 * @param {string} page The page we are currently on.
     79                 * @param {Object} [args]
     80                 * @param {Function} args.pbshow A callback that is called when a postbox opens.
     81                 * @param {Function} args.pbhide A callback that is called when a postbox closes.
     82                 */
    4783                add_postbox_toggles : function (page, args) {
    4884                        var $handles = $( '.postbox .hndle, .postbox .handlediv' );
    4985
    … … var postboxes;  
    5692                                e.stopPropagation();
    5793                        });
    5894
     95                        /**
     96                         * Adds an event handler to the dismissal of a postbox. Event handler completely hides the postbox element
     97                         * and it cannot be closed or opened afterwards.
     98                         */
    5999                        $( '.postbox a.dismiss' ).on( 'click.postboxes', function( e ) {
    60100                                var hide_id = $(this).parents('.postbox').attr('id') + '-hide';
    61101                                e.preventDefault();
    62102                                $( '#' + hide_id ).prop('checked', false).triggerHandler('click');
    63103                        });
    64104
     105                        /**
     106                         * Adds an event handler to the screen option checkboxes. Event handler completely hides the postbox element
     107                         *
     108                         * @fires postboxes#postbox-toggled
     109                         */
    65110                        $('.hide-postbox-tog').bind('click.postboxes', function() {
    66111                                var $el = $(this),
    67112                                        boxId = $el.val(),
    … … var postboxes;  
    78123                                                postboxes.pbhide( boxId );
    79124                                        }
    80125                                }
     126
    81127                                postboxes.save_state( page );
    82128                                postboxes._mark_area();
    83129                                $document.trigger( 'postbox-toggled', $postbox );
    84130                        });
    85131
     132                        /**
     133                         * Adds an event handler to the screen options layout preferences.
     134                         */
    86135                        $('.columns-prefs input[type="radio"]').bind('click.postboxes', function(){
    87136                                var n = parseInt($(this).val(), 10);
    88137
    … … var postboxes;  
    93142                        });
    94143                },
    95144
     145                /**
     146                 * Initializes all the postboxes, mainly their sortable behaviour.
     147                 *
     148                 * @memberof postboxes
     149                 *
     150                 * @param {string} page The page we are currently on.
     151                 * @param {Object} [args]
     152                 * @param {Function} args.pbshow A callback that is called when a postbox opens.
     153                 * @param {Function} args.pbhide A callback that is called when a postbox closes.
     154                 */
    96155                init : function(page, args) {
    97156                        var isMobile = $( document.body ).hasClass( 'mobile' ),
    98157                                $handleButtons = $( '.postbox .handlediv' );
    … … var postboxes;  
    157216                        });
    158217                },
    159218
     219                /**
     220                 * Saves the state of the postboxes to the server. It sends two lists, one with all the closed postboxes, one
     221                 * with all the hidden postboxes.
     222                 *
     223                 * @memberof postboxes
     224                 *
     225                 * @param {string} page The page we are currently on.
     226                 */
    160227                save_state : function(page) {
    161228                        var closed, hidden;
    162229
    … … var postboxes;  
    177244                        });
    178245                },
    179246
     247                /**
     248                 * Saves the order of the postboxes to the server. Sends a list of all postboxes inside a sortable area to the
     249                 * server.
     250                 *
     251                 * @memberof postboxes
     252                 *
     253                 * @param {string} page The page we are currently on.
     254                 */
    180255                save_order : function(page) {
    181256                        var postVars, page_columns = $('.columns-prefs input:checked').val() || 0;
    182257
    … … var postboxes;  
    186261                                page_columns: page_columns,
    187262                                page: page
    188263                        };
     264
    189265                        $('.meta-box-sortables').each( function() {
    190266                                postVars[ 'order[' + this.id.split( '-' )[0] + ']' ] = $( this ).sortable( 'toArray' ).join( ',' );
    191267                        } );
     268
    192269                        $.post( ajaxurl, postVars );
    193270                },
    194271
     272                /**
     273                 * Adds a message to empty sortable areas on the dashboard page. Also adds a border around the side area on the
     274                 * post edit screen if there are no postboxes present.
     275                 *
     276                 * @memberof postboxes
     277                 * @private
     278                 */
    195279                _mark_area : function() {
    196280                        var visible = $('div.postbox:visible').length, side = $('#post-body #side-sortables');
    197281
    … … var postboxes;  
    215299                        }
    216300                },
    217301
     302                /**
     303                 * Changes the amount of columns on the post edit page.
     304                 *
     305                 * @memberof postboxes
     306                 * @fires postboxes#postboxes-columnchange
     307                 * @private
     308                 *
     309                 * @param {number} n The amount of columns to divide the post edit page in.
     310                 */
    218311                _pb_edit : function(n) {
    219312                        var el = $('.metabox-holder').get(0);
    220313
    … … var postboxes;  
    222315                                el.className = el.className.replace(/columns-\d+/, 'columns-' + n);
    223316                        }
    224317
     318                        /**
     319                         * Fires when the amount of columns on the post edit page has been changed.
     320                         *
     321                         * @event postboxes#postboxes-columnchange
     322                         */
    225323                        $( document ).trigger( 'postboxes-columnchange' );
    226324                },
    227325
     326                /**
     327                 * Changes the postboxes based on the current orientation of the browser. Meant to be called when the
     328                 * orientation of the browser changes.
     329                 *
     330                 * @memberof postboxes
     331                 * @private
     332                 */
    228333                _pb_change : function() {
    229334                        var check = $( 'label.columns-prefs-1 input[type="radio"]' );
    230335

  • src/wp-admin/js/postbox.js 

    From 68e82d0105e03727cda2850bd6e2a49acdacaa11 Mon Sep 17 00:00:00 2001
From: Anton Timmermans <email@atimmer.com>
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 b var postboxes;  
    352352                },
    353353
    354354                /* Callbacks */
     355
     356                /**
     357                 * @property {Function|boolean} pbshow A callback that is called when a postbox is opened.
     358                 * @memberof postboxes
     359                 */
    355360                pbshow : false,
    356361
     362                /**
     363                 * @property {Function|boolean} pbhide A callback that is called when a postbox is closed.
     364                 * @memberof postboxes
     365                 */
    357366                pbhide : false
    358367        };
    359368

  • src/wp-admin/js/postbox.js 

    From dbc91371f87df6aec7a69af4d027b71abbe7ccc5 Mon Sep 17 00:00:00 2001
From: Anton Timmermans <email@atimmer.com>
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 b var postboxes;  
    126126
    127127                                postboxes.save_state( page );
    128128                                postboxes._mark_area();
     129
     130                                /**
     131                                 * @see postboxes.handle_click
     132                                 */
    129133                                $document.trigger( 'postbox-toggled', $postbox );
    130134                        });
    131135

  • src/wp-admin/js/postbox.js 

    From b852e8c059b1e43154e232898a504c4ed2b82127 Mon Sep 17 00:00:00 2001
From: Anton Timmermans <email@atimmer.com>
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 b  
    44 * This object contains all function to handle the behaviour of the post boxes. The post boxes are the boxes you see
    55 * around the content on the edit page.
    66 *
     7 * @since 2.7.0
     8 *
    79 * @namespace postboxes
    810 *
    911 * @type {Object}
    … … var postboxes;  
    2224                 * Triggers postboxes.pbshow if the postbox has just been opened, triggers postboxes.pbhide if the postbox has
    2325                 * just been closed.
    2426                 *
     27                 * @since 4.4.0
    2528                 * @memberof postboxes
    2629                 * @fires postboxes#postbox-toggled
    2730                 */
    … … var postboxes;  
    6467                         * Fires when the postbox has been opened or closed. Contains a jQuery object with the postbox element in
    6568                         * it.
    6669                         *
     70                         * @since 4.0.0
    6771                         * @event postboxes#postbox-toggled
    6872                         * @type {Object}
    6973                         */
    … … var postboxes;  
    7377                /**
    7478                 * Adds event handlers to all postboxes and screen option on the current page.
    7579                 *
     80                 * @since 2.7.0
    7681                 * @memberof postboxes
    7782                 *
    7883                 * @param {string} page The page we are currently on.
    … … var postboxes;  
    128133                                postboxes._mark_area();
    129134
    130135                                /**
     136                                 * @since 4.0.0
    131137                                 * @see postboxes.handle_click
    132138                                 */
    133139                                $document.trigger( 'postbox-toggled', $postbox );
    … … var postboxes;  
    149155                /**
    150156                 * Initializes all the postboxes, mainly their sortable behaviour.
    151157                 *
     158                 * @since 2.7.0
    152159                 * @memberof postboxes
    153160                 *
    154161                 * @param {string} page The page we are currently on.
    … … var postboxes;  
    224231                 * Saves the state of the postboxes to the server. It sends two lists, one with all the closed postboxes, one
    225232                 * with all the hidden postboxes.
    226233                 *
     234                 * @since 2.7.0
    227235                 * @memberof postboxes
    228236                 *
    229237                 * @param {string} page The page we are currently on.
    … … var postboxes;  
    252260                 * Saves the order of the postboxes to the server. Sends a list of all postboxes inside a sortable area to the
    253261                 * server.
    254262                 *
     263                 * @since 2.8.0
    255264                 * @memberof postboxes
    256265                 *
    257266                 * @param {string} page The page we are currently on.
    … … var postboxes;  
    277286                 * Adds a message to empty sortable areas on the dashboard page. Also adds a border around the side area on the
    278287                 * post edit screen if there are no postboxes present.
    279288                 *
     289                 * @since 3.3.0
    280290                 * @memberof postboxes
    281291                 * @private
    282292                 */
    … … var postboxes;  
    306316                /**
    307317                 * Changes the amount of columns on the post edit page.
    308318                 *
     319                 * @since 3.3.0
    309320                 * @memberof postboxes
    310321                 * @fires postboxes#postboxes-columnchange
    311322                 * @private
    … … var postboxes;  
    331342                 * Changes the postboxes based on the current orientation of the browser. Meant to be called when the
    332343                 * orientation of the browser changes.
    333344                 *
     345                 * @since 3.3.0
    334346                 * @memberof postboxes
    335347                 * @private
    336348                 */
    … … var postboxes;  
    358370                /* Callbacks */
    359371
    360372                /**
     373                 * @since 2.7.0
    361374                 * @property {Function|boolean} pbshow A callback that is called when a postbox is opened.
    362375                 * @memberof postboxes
    363376                 */
    364377                pbshow : false,
    365378
    366379                /**
     380                 * @since 2.7.0
    367381                 * @property {Function|boolean} pbhide A callback that is called when a postbox is closed.
    368382                 * @memberof postboxes
    369383                 */

  • src/wp-admin/js/postbox.js 

    From e762ed0b8d7c27b15da5ff42bb0e88cdc2969963 Mon Sep 17 00:00:00 2001
From: Anton Timmermans <email@atimmer.com>
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 b  
     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.4.0
     8 * @requires jQuery
     9 */
     10
    111/* global ajaxurl, postBoxL10n */
    212
    313/**
    … … var postboxes;  
    1828        postboxes = {
    1929
    2030                /**
    21                  * Handles a click on either the postbox heading or the postbox open/close icon. Opens or closes the postbox.
    22                  * Expects this to equal the clicked element.
     31                 * @summary Handles a click on either the postbox heading or the postbox open/close icon.
    2332                 *
    24                  * Triggers postboxes.pbshow if the postbox has just been opened, triggers postboxes.pbhide if the postbox has
    25                  * just been closed.
     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.
    2636                 *
    2737                 * @since 4.4.0
    2838                 * @memberof postboxes
    … … var postboxes;  
    6474                        }
    6575
    6676                        /**
    67                          * Fires when the postbox has been opened or closed. Contains a jQuery object with the postbox element in
    68                          * it.
     77                         * @summary Fires when a postbox has been opened or closed.
     78                         *
     79                         * Contains a jQuery object with the relevant postbox element.
    6980                         *
    7081                         * @since 4.0.0
    7182                         * @event postboxes#postbox-toggled
    … … var postboxes;  
    93104
    94105                        $handles.on( 'click.postboxes', this.handle_click );
    95106
     107                        /**
     108                         * @since 2.7.0
     109                         */
    96110                        $('.postbox .hndle a').click( function(e) {
    97111                                e.stopPropagation();
    98112                        });
    99113
    100114                        /**
    101                          * Adds an event handler to the dismissal of a postbox. Event handler completely hides the postbox element
    102                          * and it cannot be closed or opened afterwards.
     115                         * @summary Hides a postbox.
     116                         *
     117                         * Event handler for the postbox dismiss button. After clicking the button
     118                         * the postbox will be hidden.
     119                         *
     120                         * @since 3.2.0
    103121                         */
    104122                        $( '.postbox a.dismiss' ).on( 'click.postboxes', function( e ) {
    105123                                var hide_id = $(this).parents('.postbox').attr('id') + '-hide';
    … … var postboxes;  
    108126                        });
    109127
    110128                        /**
    111                          * Adds an event handler to the screen option checkboxes. Event handler completely hides the postbox element
     129                         * @summary Hides the postbox element
     130                         *
     131                         * Event handler for the screen options checkboxes. When a checkbox is
     132                         * clicked this function will hide or show the relevant postboxes.
    112133                         *
     134                         * @since 2.7.0
    113135                         * @fires postboxes#postbox-toggled
    114136                         */
    115137                        $('.hide-postbox-tog').bind('click.postboxes', function() {
    … … var postboxes;  
    140162                        });
    141163
    142164                        /**
    143                          * Adds an event handler to the screen options layout preferences.
     165                         * @summary Changes the amount of columns based on the layout preferences.
     166                         *
     167                         * @since 2.8.0
    144168                         */
    145169                        $('.columns-prefs input[type="radio"]').bind('click.postboxes', function(){
    146170                                var n = parseInt($(this).val(), 10);
    … … var postboxes;  
    153177                },
    154178
    155179                /**
    156                  * Initializes all the postboxes, mainly their sortable behaviour.
     180                 * @summary Initializes all the postboxes, mainly their sortable behaviour.
    157181                 *
    158182                 * @since 2.7.0
    159183                 * @memberof postboxes
    160184                 *
    161185                 * @param {string} page The page we are currently on.
    162                  * @param {Object} [args]
     186                 * @param {Object} [args={}] The arguments for the postbox initializer.
    163187                 * @param {Function} args.pbshow A callback that is called when a postbox opens.
    164                  * @param {Function} args.pbhide A callback that is called when a postbox closes.
     188                 * @param {Function} args.pbhide A callback that is called when a postbox
     189                 *                               closes.
    165190                 */
    166191                init : function(page, args) {
    167192                        var isMobile = $( document.body ).hasClass( 'mobile' ),
    … … var postboxes;  
    180205                                tolerance: 'pointer',
    181206                                forcePlaceholderSize: true,
    182207                                helper: function( event, element ) {
    183                                         // `helper: 'clone'` is equivalent to `return element.clone();`
    184                                         // Cloning a checked radio and then inserting that clone next to the original
    185                                         // radio unchecks the original radio (since only one of the two can be checked).
    186                                         // We get around this by renaming the helper's inputs' name attributes so that,
    187                                         // when the helper is inserted into the DOM for the sortable, no radios are
    188                                         // duplicated, and no original radio gets unchecked.
     208                                        /* `helper: 'clone'` is equivalent to `return element.clone();`
     209                                         * Cloning a checked radio and then inserting that clone next to the original
     210                                         * radio unchecks the original radio (since only one of the two can be checked).
     211                                         * We get around this by renaming the helper's inputs' name attributes so that,
     212                                         * when the helper is inserted into the DOM for the sortable, no radios are
     213                                         * duplicated, and no original radio gets unchecked.
     214                                         */
    189215                                        return element.clone()
    190216                                                .find( ':input' )
    191217                                                        .attr( 'name', function( i, currentName ) {
    … … var postboxes;  
    228254                },
    229255
    230256                /**
    231                  * Saves the state of the postboxes to the server. It sends two lists, one with all the closed postboxes, one
    232                  * with all the hidden postboxes.
     257                 * @summary Saves the state of the postboxes to the server.
     258                 *
     259                 * Saves the state of the postboxes to the server. It sends two lists, one with
     260                 * all the closed postboxes, one with all the hidden postboxes.
    233261                 *
    234262                 * @since 2.7.0
    235263                 * @memberof postboxes
    … … var postboxes;  
    257285                },
    258286
    259287                /**
    260                  * Saves the order of the postboxes to the server. Sends a list of all postboxes inside a sortable area to the
    261                  * server.
     288                 * @summary Saves the order of the postboxes to the server.
     289                 *
     290                 * Saves the order of the postboxes to the server. Sends a list of all postboxes
     291                 * inside a sortable area to the server.
    262292                 *
    263293                 * @since 2.8.0
    264294                 * @memberof postboxes
    … … var postboxes;  
    283313                },
    284314
    285315                /**
    286                  * Adds a message to empty sortable areas on the dashboard page. Also adds a border around the side area on the
    287                  * post edit screen if there are no postboxes present.
     316                 * @summary Marks empty postbox areas.
     317                 *
     318                 * Adds a message to empty sortable areas on the dashboard page. Also adds a
     319                 * border around the side area on the post edit screen if there are no postboxes
     320                 * present.
    288321                 *
    289322                 * @since 3.3.0
    290323                 * @memberof postboxes
    291                  * @private
     324                 * @access private
    292325                 */
    293326                _mark_area : function() {
    294327                        var visible = $('div.postbox:visible').length, side = $('#post-body #side-sortables');
    … … var postboxes;  
    314347                },
    315348
    316349                /**
    317                  * Changes the amount of columns on the post edit page.
     350                 * @summary Changes the amount of columns on the post edit page.
    318351                 *
    319352                 * @since 3.3.0
    320353                 * @memberof postboxes
    321354                 * @fires postboxes#postboxes-columnchange
    322                  * @private
     355                 * @access private
    323356                 *
    324357                 * @param {number} n The amount of columns to divide the post edit page in.
    325358                 */
    … … var postboxes;  
    333366                        /**
    334367                         * Fires when the amount of columns on the post edit page has been changed.
    335368                         *
     369                         * @since 4.0.0
    336370                         * @event postboxes#postboxes-columnchange
    337371                         */
    338372                        $( document ).trigger( 'postboxes-columnchange' );
    339373                },
    340374
    341375                /**
    342                  * Changes the postboxes based on the current orientation of the browser. Meant to be called when the
    343                  * orientation of the browser changes.
     376                 * @summary Changes the amount of columns the postboxes are in based on the
     377                 *          current orientation of the browser.
    344378                 *
    345379                 * @since 3.3.0
    346380                 * @memberof postboxes
    347                  * @private
     381                 * @access private
    348382                 */
    349383                _pb_change : function() {
    350384                        var check = $( 'label.columns-prefs-1 input[type="radio"]' );
    … … var postboxes;  
    371405
    372406                /**
    373407                 * @since 2.7.0
    374                  * @property {Function|boolean} pbshow A callback that is called when a postbox is opened.
    375408                 * @memberof postboxes
     409                 * @access public
     410                 * @property {Function|boolean} pbshow A callback that is called when a postbox
     411                 *                                     is opened.
    376412                 */
    377413                pbshow : false,
    378414
    379415                /**
    380416                 * @since 2.7.0
    381                  * @property {Function|boolean} pbhide A callback that is called when a postbox is closed.
    382417                 * @memberof postboxes
     418                 * @access public
     419                 * @property {Function|boolean} pbhide A callback that is called when a postbox
     420                 *                                     is closed.
    383421                 */
    384422                pbhide : false
    385423        };