WordPress.org
Get WordPress

Make WordPress Core

Ticket #35465: 35465.5.diff

File 35465.5.diff, 16.7 KB (added by atimmer, 5 years ago)

Patch with all @since tags.

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

     
    99         */
    1010        wp.Backbone = {};
    1111
    12 
    13         // wp.Backbone.Subviews
    14         // --------------------
    15         //
    16         // A subview manager.
     12        /**
     13         * A backbone subview manager.
     14         *
     15         * @since 3.5.0
     16         * @since 3.6.0 Moved wp.media.Views to wp.Subviews
     17         * @since 3.6.0 Moved Subviews to wp.Backbone namespace.
     18         *
     19         * @memberOf wp.Backbone
     20         *
     21         * @class
     22         *
     23         * @param  {wp.Backbone.View} view  The main view.
     24         * @param  {array|Object}     views The subviews for the main view.
     25         */
    1726        wp.Backbone.Subviews = function( view, views ) {
    1827                this.view = view;
    1928                this._views = _.isArray( views ) ? { '': views } : views || {};
    … …  
    2231        wp.Backbone.Subviews.extend = Backbone.Model.extend;
    2332
    2433        _.extend( wp.Backbone.Subviews.prototype, {
    25                 // ### Fetch all of the subviews
    26                 //
    27                 // Returns an array of all subviews.
     34                /**
     35                 * Fetches all of the subviews.
     36                 *
     37                 * @since 3.5.0
     38                 *
     39                 * @return {array} All the subviews.
     40                 */
    2841                all: function() {
    29                         return _.flatten( _.values( this._views ) ); 
     42                        return _.flatten( _.values( this._views ) );
    3043                },
    3144
    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.
     45                /**
     46                 * Fetches all subviews that match a given `selector`.
     47                 *
     48                 * If no `selector` is provided, it will grab all subviews attached
     49                 * to the view's root.
     50                 *
     51                 * @since 3.5.0
     52                 *
     53                 * @param {string} selector A jQuery selector.
     54                 *
     55                 * @return {array}
     56                 */
    3857                get: function( selector ) {
    3958                        selector = selector || '';
    4059                        return this._views[ selector ];
    4160                },
    4261
    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.
     62                /**
     63                 * Fetches the first subview that matches a given `selector`.
     64                 *
     65                 * If no `selector` is provided, it will grab the first subview attached to the
     66                 * view's root.
     67                 *
     68                 * Useful when a selector only has one subview at a time.
     69                 *
     70                 * @since 3.5.0
     71                 *
     72                 * @param {string} selector A jQuery selector.
     73                 *
     74                 * @return {Backbone.View} The view.
     75                 */
    5176                first: function( selector ) {
    5277                        var views = this.get( selector );
    5378                        return views && views.length ? views[0] : null;
    5479                },
    5580
    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.
     81                /**
     82                 * Registers subview(s).
     83                 *
     84                 * Registers any number of `views` to a `selector`.
     85                 *
     86                 * When no `selector` is provided, the root selector (the empty string)
     87                 * is used. `views` accepts a `Backbone.View` instance or an array of
     88                 * `Backbone.View` instances.
     89                 *
     90                 * ---
     91                 *
     92                 * Accepts an `options` object, which has a significant effect on the
     93                 * resulting behavior.
     94                 *
     95                 * `options.silent` – *boolean, `false`*
     96                 * > If `options.silent` is true, no DOM modifications will be made.
     97                 *
     98                 * `options.add` – *boolean, `false`*
     99                 * > Use `Views.add()` as a shortcut for setting `options.add` to true.
     100                 *
     101                 * > By default, the provided `views` will replace
     102                 * any existing views associated with the selector. If `options.add`
     103                 * is true, the provided `views` will be added to the existing views.
     104                 *
     105                 * `options.at` – *integer, `undefined`*
     106                 * > When adding, to insert `views` at a specific index, use
     107                 * `options.at`. By default, `views` are added to the end of the array.
     108                 *
     109                 * @since 3.5.0
     110                 *
     111                 * @param {string}       selector A jQuery selector.
     112                 * @param {array|Object} views    The subviews for the main view.
     113                 * @param {Object}       options  Options for call. If `options.silent` is true,
     114                 *                                no DOM  modifications will be made. Use
     115                 *                                `Views.add()` as a shortcut for setting
     116                 *                                `options.add` to true. If `options.add` is
     117                 *                                true, the provided `views` will be added to
     118                 *                                the existing views. When adding, to insert
     119                 *                                `views` at a specific index, use `options.at`.
     120                 *
     121                 * @return wp.Backbone.Subviews
     122                 */
    82123                set: function( selector, views, options ) {
    83124                        var existing, next;
    84125
    … …  
    134175                        return this;
    135176                },
    136177
    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()`.
     178                /**
     179                 * Add subview(s) to existing subviews.
     180                 *
     181                 * An alias to `Views.set()`, which defaults `options.add` to true.
     182                 *
     183                 * Adds any number of `views` to a `selector`.
     184                 *
     185                 * When no `selector` is provided, the root selector (the empty string)
     186                 * is used. `views` accepts a `Backbone.View` instance or an array of
     187                 * `Backbone.View` instances.
     188                 *
     189                 * Uses `Views.set()` when setting `options.add` to `false`.
     190                 *
     191                 * Accepts an `options` object. By default, provided `views` will be
     192                 * inserted at the end of the array of existing views. To insert
     193                 * `views` at a specific index, use `options.at`. If `options.silent`
     194                 * is true, no DOM modifications will be made.
     195                 *
     196                 * For more information on the `options` object, see `Views.set()`.
     197                 *
     198                 * @since 3.5.0
     199                 *
     200                 * @param {string}       selector A jQuery selector.
     201                 * @param {array|object} views    The subviews for the main view.
     202                 * @param {Object}       options  Options for call.  To insert `views` at a
     203                 *                                specific index, use `options.at`. If
     204                 *                                `options.silent` is true, no DOM modifications
     205                 *                                will be made.
     206                 *
     207                 * @return wp.Backbone.Subviews
     208                 */
    155209                add: function( selector, views, options ) {
    156210                        if ( ! _.isString( selector ) ) {
    157211                                options  = views;
    … …  
    162216                        return this.set( selector, views, _.extend({ add: true }, options ) );
    163217                },
    164218
    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.
     219                /**
     220                 * Removes an added subview.
     221                 *
     222                 * Stops tracking `views` registered to a `selector`. If no `views` are
     223                 * set, then all of the `selector`'s subviews will be unregistered and
     224                 * removed.
     225                 *
     226                 * Accepts an `options` object. If `options.silent` is set, `remove`
     227                 * will *not* be triggered on the unregistered views.
     228                 *
     229                 * @since 3.5.0
     230                 *
     231                 * @param {string}       selector A jQuery selector.
     232                 * @param {array|object} views    The subviews for the main view.
     233                 * @param {Object}       options  Options for call. If `options.silent` is set,
     234                 *                                `remove` will *not* be triggered on the
     235                 *                                unregistered views.
     236                 *
     237                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     238                 */
    173239                unset: function( selector, views, options ) {
    174240                        var existing;
    175241
    … …  
    192258                        return this;
    193259                },
    194260
    195                 // ### Detach all subviews
    196                 //
    197                 // Detaches all subviews from the DOM.
    198                 //
    199                 // Helps to preserve all subview events when re-rendering the master
    200                 // view. Used in conjunction with `Views.render()`.
     261                /**
     262                 * Detaches all subviews.
     263                 *
     264                 * Helps to preserve all subview events when re-rendering the master
     265                 * view. Used in conjunction with `Views.render()`.
     266                 *
     267                 * @since 3.5.0
     268                 *
     269                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     270                 */
    201271                detach: function() {
    202272                        $( _.pluck( this.all(), 'el' ) ).detach();
    203273                        return this;
    204274                },
    205275
    206                 // ### Render all subviews
    207                 //
    208                 // Renders all subviews. Used in conjunction with `Views.detach()`.
     276                /**
     277                 * Renders all subviews
     278                 *
     279                 * Used in conjunction with `Views.detach()`.
     280                 *
     281                 * @since 3.5.0
     282                 *
     283                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     284                */
    209285                render: function() {
    210286                        var options = {
    211287                                        ready: this._isReady()
    … …  
    219295                        return this;
    220296                },
    221297
    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.
     298                /**
     299                 * Removes all subviews
     300                 *
     301                 * Triggers the `remove()` method on all subviews. Detaches the master
     302                 * view from its parent. Resets the internals of the views manager.
     303                 *
     304                 * Accepts an `options` object. If `options.silent` is set, `unset`
     305                 * will *not* be triggered on the master view's parent.
     306                 *
     307                 * @since 3.6.0
     308                 *
     309                 * @param {Object}  options        Options for call.
     310                 * @param {boolean} options.silent If true, `unset` wil *not* be triggered on
     311                 *                                 the master views' parent.
     312                 *
     313                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     314                */
    229315                remove: function( options ) {
    230316                        if ( ! options || ! options.silent ) {
    231317                                if ( this.parent && this.parent.views )
    … …  
    239325                        return this;
    240326                },
    241327
    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.
     328                /**
     329                 * Replaces a selector's subviews
     330                 *
     331                 * By default, sets the `$target` selector's html to the subview `els`.
     332                 *
     333                 * Can be overridden in subclasses.
     334                 *
     335                 * @since 3.5.0
     336                 *
     337                 * @param {string} $target Selector where to put the elements.
     338                 * @param {*} els HTML or elements to put into the selector's HTML.
     339                 *
     340                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     341                 */
    247342                replace: function( $target, els ) {
    248343                        $target.html( els );
    249344                        return this;
    250345                },
    251346
    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.
     347                /**
     348                 * Insert subviews into a selector
     349                 *
     350                 * By default, appends the subview `els` to the end of the `$target`
     351                 * selector. If `options.at` is set, inserts the subview `els` at the
     352                 * provided index.
     353                 *
     354                 * Can be overridden in subclasses.
     355                 *
     356                 * @since 3.5.0
     357                 *
     358                 * @param {string}  $target    Selector where to put the elements.
     359                 * @param {*}       els        HTML or elements to put at the end of the
     360                 *                             $target.
     361                 * @param {?Object} options    Options for call.
     362                 * @param {?number} options.at At which index to put the elements.
     363                 *
     364                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     365                 */
    259366                insert: function( $target, els, options ) {
    260367                        var at = options && options.at,
    261368                                $children;
    … …  
    268375                        return this;
    269376                },
    270377
    271                 // ### Trigger the ready event
    272                 //
    273                 // **Only use this method if you know what you're doing.**
    274                 // For performance reasons, this method does not check if the view is
    275                 // actually attached to the DOM. It's taking your word for it.
    276                 //
    277                 // Fires the ready event on the current view and all attached subviews.
     378                /**
     379                 * Triggers the ready event.
     380                 *
     381                 * Only use this method if you know what you're doing. For performance reasons,
     382                 * this method does not check if the view is actually attached to the DOM. It's
     383                 * taking your word for it.
     384                 *
     385                 * Fires the ready event on the current view and all attached subviews.
     386                 *
     387                 * @since 3.5.0
     388                 */
    278389                ready: function() {
    279390                        this.view.trigger('ready');
    280391
    … …  
    283394                                return view.views;
    284395                        }).flatten().where({ attached: true }).invoke('ready');
    285396                },
    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.
     397                /**
     398                 * Attaches a series of views to a selector. Internal.
     399                 *
     400                 * Checks to see if a matching selector exists, renders the views,
     401                 * performs the proper DOM operation, and then checks if the view is
     402                 * attached to the document.
     403                 *
     404                 * @since 3.5.0
     405                 *
     406                 * @private
     407                 *
     408                 * @param {string}       selector A jQuery selector.
     409                 * @param {array|object} views    The subviews for the main view.
     410                 * @param {Object}       options  Options for call.
     411                 * @param {boolean}      options.add  If true the provided views will be added.
     412                 *
     413                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     414                 */
    292415                _attach: function( selector, views, options ) {
    293416                        var $selector = selector ? this.view.$( selector ) : this.view.$el,
    294417                                managers;
    … …  
    323446                        return this;
    324447                },
    325448
    326                 // #### Internal. Checks if the current view is in the DOM.
     449                /**
     450                 * Determines whether or not the current view is in the DOM.
     451                 *
     452                 * @since 3.5.0
     453                 *
     454                 * @private
     455                 *
     456                 * @returns {boolean} Whether or not the current view is in the DOM.
     457                 */
    327458                _isReady: function() {
    328459                        var node = this.view.el;
    329460                        while ( node ) {
    … …  
    336467                }
    337468        });
    338469
     470        wp.Backbone.View = Backbone.View.extend({
    339471
    340         // wp.Backbone.View
    341         // ----------------
    342         //
    343         // The base view class.
    344         wp.Backbone.View = Backbone.View.extend({
    345472                // The constructor for the `Views` manager.
    346473                Subviews: wp.Backbone.Subviews,
    347474
     475                /**
     476                 * The base view class.
     477                 *
     478                 * This extends the backbone view to have a build-in way to use subviews. This
     479                 * makes it easier to have nested views.
     480                 *
     481                 * @since 3.5.0
     482                 * @since 3.6.0 Moved wp.media.View to wp.View
     483                 * @since 3.6.0 Moved View to wp.Backbone namespace.
     484                 *
     485                 * @memberOf wp.Backbone
     486                 *
     487                 * @constructs
     488                 * @augments Backbone.View
     489                 *
     490                 * @param {Object} options The options for this view.
     491                 */
    348492                constructor: function( options ) {
    349493                        this.views = new this.Subviews( this, this.views );
    350494                        this.on( 'ready', this.ready, this );
    … …  
    354498                        Backbone.View.apply( this, arguments );
    355499                },
    356500
     501                /**
     502                 * @since 3.5.0
     503                 *
     504                 * Removes this view and all subviews.
     505                 */
    357506                remove: function() {
    358507                        var result = Backbone.View.prototype.remove.apply( this, arguments );
    359508
    … …  
    364513                        return result;
    365514                },
    366515
     516                /**
     517                 * Renders this view and all subviews.
     518                 *
     519                 * @since 3.5.0
     520                 *
     521                 * @returns {wp.Backbone.View} The current instance of the view.
     522                 */
    367523                render: function() {
    368524                        var options;
    369525
    … …  
    382538                        return this;
    383539                },
    384540
     541                /**
     542                 * Returns the options for this view.
     543                 *
     544                 * @since 3.5.0
     545                 *
     546                 * @returns {Object} The options for this view.
     547                 */
    385548                prepare: function() {
    386549                        return this.options;
    387550                },
    388551
     552                /**
     553                 * Method that is called when the ready event is triggered.
     554                 *
     555                 * @since 3.5.0
     556                 */
    389557                ready: function() {}
    390558        });
    391559}(jQuery));