WordPress.org

Make WordPress Core

Ticket #35465: 35465.3.diff

File 35465.3.diff, 12.8 KB (added by adamsilverstein, 4 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..40df97fc52 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() {
    29                         return _.flatten( _.values( this._views ) ); 
     34                        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                },
    5568
    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.
     69                /**
     70                * Register subview(s)
     71                *
     72                * Registers any number of `views` to a `selector`.
     73                *
     74                * When no `selector` is provided, the root selector (the empty string)
     75                * is used. `views` accepts a `Backbone.View` instance or an array of
     76                * `Backbone.View` instances.
     77                *
     78                * ---
     79                *
     80                * Accepts an `options` object, which has a significant effect on the
     81                * resulting behavior.
     82                *
     83                * `options.silent` – *boolean, `false`*
     84                * > If `options.silent` is true, no DOM modifications will be made.
     85                *
     86                * `options.add` – *boolean, `false`*
     87                * > Use `Views.add()` as a shortcut for setting `options.add` to true.
     88                *
     89                * > By default, the provided `views` will replace
     90                * any existing views associated with the selector. If `options.add`
     91                * is true, the provided `views` will be added to the existing views.
     92                *
     93                * `options.at` – *integer, `undefined`*
     94                * > When adding, to insert `views` at a specific index, use
     95                * `options.at`. By default, `views` are added to the end of the array.
     96                *
     97                * @param {string}       selector A jQuery selector.
     98                * @param {array|object} views    The subviews for the main view.
     99                * @param {}             options  Options for call. If `options.silent` is true, no DOM
     100                *                                modifications will be made. Use `Views.add()` as a
     101                *                                shortcut for setting `options.add` to true. If `options.add`
     102                *                                is true, the provided `views` will be added to the existing
     103                *                                views. When adding, to insert `views` at a specific index,
     104                *                                use `options.at`.
     105                *
     106                * @return wp.Backbone.Subviews
     107                */
    82108                set: function( selector, views, options ) {
    83109                        var existing, next;
    84110
    … … window.wp = window.wp || {}; 
    134160                        return this;
    135161                },
    136162
    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()`.
     163                /**
     164                * Add subview(s) to existing subviews
     165                *
     166                * An alias to `Views.set()`, which defaults `options.add` to true.
     167                *
     168                * Adds any number of `views` to a `selector`.
     169                *
     170                * When no `selector` is provided, the root selector (the empty string)
     171                * is used. `views` accepts a `Backbone.View` instance or an array of
     172                * `Backbone.View` instances.
     173                *
     174                * Use `Views.set()` when setting `options.add` to `false`.
     175                *
     176                * Accepts an `options` object. By default, provided `views` will be
     177                * inserted at the end of the array of existing views. To insert
     178                * `views` at a specific index, use `options.at`. If `options.silent`
     179                * is true, no DOM modifications will be made.
     180                *
     181                * For more information on the `options` object, see `Views.set()`.
     182                *
     183                * @param {string}       selector A jQuery selector.
     184                * @param {array|object} views    The subviews for the main view.
     185                * @param {}             options  Options for call.  To insert `views` at a specific index,
     186                *                                use `options.at`. If `options.silent` is true, no DOM
     187                *                                modifications will be made.
     188                *
     189                * @return wp.Backbone.Subviews
     190                */
    155191                add: function( selector, views, options ) {
    156192                        if ( ! _.isString( selector ) ) {
    157193                                options  = views;
    … … window.wp = window.wp || {}; 
    161197
    162198                        return this.set( selector, views, _.extend({ add: true }, options ) );
    163199                },
    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.
     200                /**
     201                * Stop tracking subviews
     202                *
     203                * Stops tracking `views` registered to a `selector`. If no `views` are
     204                * set, then all of the `selector`'s subviews will be unregistered and
     205                * removed.
     206                *
     207                * Accepts an `options` object. If `options.silent` is set, `remove`
     208                * will *not* be triggered on the unregistered views.
     209                *
     210                * @param {string}       selector A jQuery selector.
     211                * @param {array|object} views    The subviews for the main view.
     212                * @param {}             options  Options for call. If `options.silent` is set,
     213                *                                `remove` will *not* be triggered on the unregistered
     214                *                                views.
     215                *
     216                * @return wp.Backbone.Subviews
     217                */
    173218                unset: function( selector, views, options ) {
    174219                        var existing;
    175220
    … … window.wp = window.wp || {}; 
    203248                        return this;
    204249                },
    205250
    206                 // ### Render all subviews
    207                 //
    208                 // Renders all subviews. Used in conjunction with `Views.detach()`.
     251                /**
     252                * Render all subviews
     253                *
     254                * Renders all subviews. Used in conjunction with `Views.detach()`.
     255                *
     256                * @param {array|object} views    The subviews for the main view.
     257                * @param {string}       selector A jQuery selector.
     258                *
     259                * @return wp.Backbone.Subviews
     260                */
    209261                render: function() {
    210262                        var options = {
    211263                                        ready: this._isReady()
    … … window.wp = window.wp || {}; 
    219271                        return this;
    220272                },
    221273
    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.
     274                /**
     275                * Remove all subviews
     276                *
     277                * Triggers the `remove()` method on all subviews. Detaches the master
     278                * view from its parent. Resets the internals of the views manager.
     279                *
     280                * Accepts an `options` object. If `options.silent` is set, `unset`
     281                * will *not* be triggered on the master view's parent.
     282                *
     283                * @param {} options  Options for call. If `options.silent` is set, `unset` will *not* be
     284                *                    triggered on the master view's parent.
     285                *
     286                * @return {}
     287                */
    229288                remove: function( options ) {
    230289                        if ( ! options || ! options.silent ) {
    231290                                if ( this.parent && this.parent.views )
    … … window.wp = window.wp || {}; 
    238297                        this._views = [];
    239298                        return this;
    240299                },
    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.
     300                /**
     301                * Replace a selector's subviews
     302                *
     303                * By default, sets the `$target` selector's html to the subview `els`.
     304                *
     305                * Can be overridden in subclasses.
     306                *
     307                * @param {} target
     308                * @param {} els
     309                *
     310                * @return wp.Backbone.Subviews
     311                */
    247312                replace: function( $target, els ) {
    248313                        $target.html( els );
    249314                        return this;
    250315                },
    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.
     316                /**
     317                * Insert subviews into a selector
     318                *
     319                * By default, appends the subview `els` to the end of the `$target`
     320                * selector. If `options.at` is set, inserts the subview `els` at the
     321                * provided index.
     322                *
     323                * Can be overridden in subclasses.
     324                *
     325                * @param {} target
     326                * @param {} els
     327                * @param {} options Options for call. If `options.at` is set, inserts the subview `els` at the provided index.
     328                *
     329                * @return wp.Backbone.Subviews
     330                */
    259331                insert: function( $target, els, options ) {
    260332                        var at = options && options.at,
    261333                                $children;
    … … window.wp = window.wp || {}; 
    283355                                return view.views;
    284356                        }).flatten().where({ attached: true }).invoke('ready');
    285357                },
    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.
     358                /**
     359                * Internal. Attaches a series of views to a selector.
     360                *
     361                * Checks to see if a matching selector exists, renders the views,
     362                * performs the proper DOM operation, and then checks if the view is
     363                * attached to the document.
     364                *
     365                * @param {string}       selector A jQuery selector.
     366                * @param {array|object} views    The subviews for the main view.
     367                * @param {}             options  Options for call. If `options.add` is true, the provided
     368                *                                `views` will be added to the existing views.
     369                *
     370                * @return wp.Backbone.Subviews
     371                */
    292372                _attach: function( selector, views, options ) {
    293373                        var $selector = selector ? this.view.$( selector ) : this.view.$el,
    294374                                managers;
    … … window.wp = window.wp || {}; 
    336416                }
    337417        });
    338418
    339 
    340         // wp.Backbone.View
    341         // ----------------
    342         //
    343         // The base view class.
     419        /**
     420         * The base view class.
     421         *
     422         * @class
     423         *
     424         */
    344425        wp.Backbone.View = Backbone.View.extend({
     426
    345427                // The constructor for the `Views` manager.
    346428                Subviews: wp.Backbone.Subviews,
    347429