WordPress.org
Get WordPress

Make WordPress Core

Ticket #35465: 35465.2.diff

File 35465.2.diff, 11.5 KB (added by adamsilverstein, 6 years ago)

  • src/wp-includes/js/wp-backbone.js 

    diff --git src/wp-includes/js/wp-backbone.js src/wp-includes/js/wp-backbone.js
index bf9a780916..aa9cc23882 100644
    window.wp = window.wp || {}; 
    99         */
    1010        wp.Backbone = {};
    1111
    12 
    13         // wp.Backbone.Subviews
    14         // --------------------
    15         //
    16         // A subview manager.
     12        /**
     13         * A subview manager.
     14         *
     15         * @class
     16         *
     17         * @param  {wp.Backbone.View} view  The main view.
     18         * @param  {array|object}     views The subviews for the main view.
     19         */
    1720        wp.Backbone.Subviews = function( view, views ) {
    1821                this.view = view;
    1922                this._views = _.isArray( views ) ? { '': views } : views || {};
    … … window.wp = window.wp || {}; 
    2225        wp.Backbone.Subviews.extend = Backbone.Model.extend;
    2326
    2427        _.extend( wp.Backbone.Subviews.prototype, {
    25                 // ### Fetch all of the subviews
    26                 //
    27                 // Returns an array of all subviews.
     28                /**
     29                 * Fetch all of the subviews.
     30                 *
     31                 * @return {array} All the subviews.
     32                 */
    2833                all: function() {
    2934                        return _.flatten( _.values( this._views ) );
    3035                },
    3136
    32                 // ### Get a selector's subviews
    33                 //
    34                 // Fetches all subviews that match a given `selector`.
    35                 //
    36                 // If no `selector` is provided, it will grab all subviews attached
    37                 // to the view's root.
     37                /**
     38                 * Fetches all subviews that match a given `selector`.
     39                 *
     40                 * If no `selector` is provided, it will grab all subviews attached
     41                 * to the view's root.
     42                 *
     43                 * @param {string} selector A jQuery selector.
     44                 *
     45                 * @return {array}
     46                 */
    3847                get: function( selector ) {
    3948                        selector = selector || '';
    4049                        return this._views[ selector ];
    4150                },
    4251
    43                 // ### Get a selector's first subview
    44                 //
    45                 // Fetches the first subview that matches a given `selector`.
    46                 //
    47                 // If no `selector` is provided, it will grab the first subview
    48                 // attached to the view's root.
    49                 //
    50                 // Useful when a selector only has one subview at a time.
     52                /**
     53                 * Fetches the first subview that matches a given `selector`.
     54                 *
     55                 * If no `selector` is provided, it will grab the first subview
     56                 * attached to the view's root.
     57                 *
     58                 * Useful when a selector only has one subview at a time.
     59                 *
     60                 * @param {string} selector A jQuery selector.
     61                 *
     62                 * @return {Backbone.View} The view.
     63                 */
    5164                first: function( selector ) {
    5265                        var views = this.get( selector );
    5366                        return views && views.length ? views[0] : null;
    5467                },
    55 
    56                 // ### Register subview(s)
    57                 //
    58                 // Registers any number of `views` to a `selector`.
    59                 //
    60                 // When no `selector` is provided, the root selector (the empty string)
    61                 // is used. `views` accepts a `Backbone.View` instance or an array of
    62                 // `Backbone.View` instances.
    63                 //
    64                 // ---
    65                 //
    66                 // Accepts an `options` object, which has a significant effect on the
    67                 // resulting behavior.
    68                 //
    69                 // `options.silent` – *boolean, `false`*
    70                 // > If `options.silent` is true, no DOM modifications will be made.
    71                 //
    72                 // `options.add` – *boolean, `false`*
    73                 // > Use `Views.add()` as a shortcut for setting `options.add` to true.
    74                 //
    75                 // > By default, the provided `views` will replace
    76                 // any existing views associated with the selector. If `options.add`
    77                 // is true, the provided `views` will be added to the existing views.
    78                 //
    79                 // `options.at` – *integer, `undefined`*
    80                 // > When adding, to insert `views` at a specific index, use
    81                 // `options.at`. By default, `views` are added to the end of the array.
     68                /**
     69                * Register subview(s)
     70                *
     71                * Registers any number of `views` to a `selector`.
     72                *
     73                * When no `selector` is provided, the root selector (the empty string)
     74                * is used. `views` accepts a `Backbone.View` instance or an array of
     75                * `Backbone.View` instances.
     76                *
     77                * ---
     78                *
     79                * Accepts an `options` object, which has a significant effect on the
     80                * resulting behavior.
     81                *
     82                * `options.silent` – *boolean, `false`*
     83                * > If `options.silent` is true, no DOM modifications will be made.
     84                *
     85                * `options.add` – *boolean, `false`*
     86                * > Use `Views.add()` as a shortcut for setting `options.add` to true.
     87                *
     88                * > By default, the provided `views` will replace
     89                * any existing views associated with the selector. If `options.add`
     90                * is true, the provided `views` will be added to the existing views.
     91                *
     92                * `options.at` – *integer, `undefined`*
     93                * > When adding, to insert `views` at a specific index, use
     94                * `options.at`. By default, `views` are added to the end of the array.
     95                *
     96                * @param {string}                       selector        A jQuery selector.
     97                * @param  {array|object}        views           The subviews for the main view.
     98                * @param {} options
     99                *
     100                * @return
     101                */
    82102                set: function( selector, views, options ) {
    83103                        var existing, next;
    84104
    … … window.wp = window.wp || {}; 
    133153
    134154                        return this;
    135155                },
    136 
    137                 // ### Add subview(s) to existing subviews
    138                 //
    139                 // An alias to `Views.set()`, which defaults `options.add` to true.
    140                 //
    141                 // Adds any number of `views` to a `selector`.
    142                 //
    143                 // When no `selector` is provided, the root selector (the empty string)
    144                 // is used. `views` accepts a `Backbone.View` instance or an array of
    145                 // `Backbone.View` instances.
    146                 //
    147                 // Use `Views.set()` when setting `options.add` to `false`.
    148                 //
    149                 // Accepts an `options` object. By default, provided `views` will be
    150                 // inserted at the end of the array of existing views. To insert
    151                 // `views` at a specific index, use `options.at`. If `options.silent`
    152                 // is true, no DOM modifications will be made.
    153                 //
    154                 // For more information on the `options` object, see `Views.set()`.
     156                /**
     157                * Add subview(s) to existing subviews
     158                *
     159                * An alias to `Views.set()`, which defaults `options.add` to true.
     160                *
     161                * Adds any number of `views` to a `selector`.
     162                *
     163                * When no `selector` is provided, the root selector (the empty string)
     164                * is used. `views` accepts a `Backbone.View` instance or an array of
     165                * `Backbone.View` instances.
     166                *
     167                * Use `Views.set()` when setting `options.add` to `false`.
     168                *
     169                * Accepts an `options` object. By default, provided `views` will be
     170                * inserted at the end of the array of existing views. To insert
     171                * `views` at a specific index, use `options.at`. If `options.silent`
     172                * is true, no DOM modifications will be made.
     173                *
     174                * For more information on the `options` object, see `Views.set()`.
     175                *
     176                * @param {string}                       selector A jQuery selector.
     177                * @param  {array|object}        views The subviews for the main view.
     178                * @param {} options
     179                *
     180                * @return
     181                */
    155182                add: function( selector, views, options ) {
    156183                        if ( ! _.isString( selector ) ) {
    157184                                options  = views;
    … … window.wp = window.wp || {}; 
    161188
    162189                        return this.set( selector, views, _.extend({ add: true }, options ) );
    163190                },
    164 
    165                 // ### Stop tracking subviews
    166                 //
    167                 // Stops tracking `views` registered to a `selector`. If no `views` are
    168                 // set, then all of the `selector`'s subviews will be unregistered and
    169                 // removed.
    170                 //
    171                 // Accepts an `options` object. If `options.silent` is set, `remove`
    172                 // will *not* be triggered on the unregistered views.
     191                /**
     192                * Stop tracking subviews
     193                *
     194                * Stops tracking `views` registered to a `selector`. If no `views` are
     195                * set, then all of the `selector`'s subviews will be unregistered and
     196                * removed.
     197                *
     198                * Accepts an `options` object. If `options.silent` is set, `remove`
     199                * will *not* be triggered on the unregistered views.
     200                *
     201                * @param {string}                       selector A jQuery selector.
     202                * @param  {array|object}        views The subviews for the main view.
     203                * @param {} options
     204                *
     205                * @return
     206                */
    173207                unset: function( selector, views, options ) {
    174208                        var existing;
    175209
    … … window.wp = window.wp || {}; 
    202236                        $( _.pluck( this.all(), 'el' ) ).detach();
    203237                        return this;
    204238                },
    205 
    206                 // ### Render all subviews
    207                 //
    208                 // Renders all subviews. Used in conjunction with `Views.detach()`.
     239                /**
     240                * Render all subviews
     241                *
     242                * Renders all subviews. Used in conjunction with `Views.detach()`.
     243                *
     244                * @param {array|object}         views           The subviews for the main view.
     245                * @param {string}                       selector        A jQuery selector.
     246                *
     247                * @return {array}
     248                */
    209249                render: function() {
    210250                        var options = {
    211251                                        ready: this._isReady()
    … … window.wp = window.wp || {}; 
    218258                        this.rendered = true;
    219259                        return this;
    220260                },
    221 
    222                 // ### Remove all subviews
    223                 //
    224                 // Triggers the `remove()` method on all subviews. Detaches the master
    225                 // view from its parent. Resets the internals of the views manager.
    226                 //
    227                 // Accepts an `options` object. If `options.silent` is set, `unset`
    228                 // will *not* be triggered on the master view's parent.
     261                /**
     262                * Remove all subviews
     263                *
     264                * Triggers the `remove()` method on all subviews. Detaches the master
     265                * view from its parent. Resets the internals of the views manager.
     266                *
     267                * Accepts an `options` object. If `options.silent` is set, `unset`
     268                * will *not* be triggered on the master view's parent.
     269                *
     270                * @param {} options
     271                *
     272                * @return {}
     273                */
    229274                remove: function( options ) {
    230275                        if ( ! options || ! options.silent ) {
    231276                                if ( this.parent && this.parent.views )
    … … window.wp = window.wp || {}; 
    238283                        this._views = [];
    239284                        return this;
    240285                },
    241 
    242                 // ### Replace a selector's subviews
    243                 //
    244                 // By default, sets the `$target` selector's html to the subview `els`.
    245                 //
    246                 // Can be overridden in subclasses.
     286                /**
     287                * Replace a selector's subviews
     288                *
     289                * By default, sets the `$target` selector's html to the subview `els`.
     290                *
     291                * Can be overridden in subclasses.
     292                *
     293                * @param {} target
     294                * @param {} els
     295                *
     296                * @return
     297                */
    247298                replace: function( $target, els ) {
    248299                        $target.html( els );
    249300                        return this;
    250301                },
    251 
    252                 // ### Insert subviews into a selector
    253                 //
    254                 // By default, appends the subview `els` to the end of the `$target`
    255                 // selector. If `options.at` is set, inserts the subview `els` at the
    256                 // provided index.
    257                 //
    258                 // Can be overridden in subclasses.
     302                /**
     303                * Insert subviews into a selector
     304                *
     305                * By default, appends the subview `els` to the end of the `$target`
     306                * selector. If `options.at` is set, inserts the subview `els` at the
     307                * provided index.
     308                *
     309                * Can be overridden in subclasses.
     310                *
     311                * @param {} target
     312                * @param {} els
     313                * @param {} options
     314                *
     315                * @return
     316                */
    259317                insert: function( $target, els, options ) {
    260318                        var at = options && options.at,
    261319                                $children;
    … … window.wp = window.wp || {}; 
    283341                                return view.views;
    284342                        }).flatten().where({ attached: true }).invoke('ready');
    285343                },
    286 
    287                 // #### Internal. Attaches a series of views to a selector.
    288                 //
    289                 // Checks to see if a matching selector exists, renders the views,
    290                 // performs the proper DOM operation, and then checks if the view is
    291                 // attached to the document.
     344                /**
     345                * Internal. Attaches a series of views to a selector.
     346                *
     347                * Checks to see if a matching selector exists, renders the views,
     348                * performs the proper DOM operation, and then checks if the view is
     349                * attached to the document.
     350                *
     351                * @param {string}                       selector A jQuery selector.
     352                * @param  {array|object}        views The subviews for the main view.
     353                * @param {} options
     354                *
     355                * @return
     356                */
    292357                _attach: function( selector, views, options ) {
    293358                        var $selector = selector ? this.view.$( selector ) : this.view.$el,
    294359                                managers;
    … … window.wp = window.wp || {}; 
    336401                }
    337402        });
    338403
    339 
    340         // wp.Backbone.View
    341         // ----------------
    342         //
    343         // The base view class.
     404        /**
     405         * The base view class.
     406         *
     407         * @class
     408         *
     409         */
    344410        wp.Backbone.View = Backbone.View.extend({
    345411                // The constructor for the `Views` manager.
    346412                Subviews: wp.Backbone.Subviews,