WordPress.org

Make WordPress Core

Ticket #35465: 35465.4.diff

File 35465.4.diff, 15.5 KB (added by atimmer, 4 years ago)

Patch with all docblocks present

  • 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         * @memberOf wp.Backbone
     16         *
     17         * @class
     18         *
     19         * @param  {wp.Backbone.View} view  The main view.
     20         * @param  {array|Object}     views The subviews for the main view.
     21         */
    1722        wp.Backbone.Subviews = function( view, views ) {
    1823                this.view = view;
    1924                this._views = _.isArray( views ) ? { '': views } : views || {};
    … …  
    2227        wp.Backbone.Subviews.extend = Backbone.Model.extend;
    2328
    2429        _.extend( wp.Backbone.Subviews.prototype, {
    25                 // ### Fetch all of the subviews
    26                 //
    27                 // Returns an array of all subviews.
     30                /**
     31                 * Fetches all of the subviews.
     32                 *
     33                 * @return {array} All the subviews.
     34                 */
    2835                all: function() {
    29                         return _.flatten( _.values( this._views ) ); 
     36                        return _.flatten( _.values( this._views ) );
    3037                },
    3138
    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.
     39                /**
     40                 * Fetches all subviews that match a given `selector`.
     41                 *
     42                 * If no `selector` is provided, it will grab all subviews attached
     43                 * to the view's root.
     44                 *
     45                 * @param {string} selector A jQuery selector.
     46                 *
     47                 * @return {array}
     48                 */
    3849                get: function( selector ) {
    3950                        selector = selector || '';
    4051                        return this._views[ selector ];
    4152                },
    4253
    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.
     54                /**
     55                 * Fetches the first subview that matches a given `selector`.
     56                 *
     57                 * If no `selector` is provided, it will grab the first subview attached to the
     58                 * view's root.
     59                 *
     60                 * Useful when a selector only has one subview at a time.
     61                 *
     62                 * @param {string} selector A jQuery selector.
     63                 *
     64                 * @return {Backbone.View} The view.
     65                 */
    5166                first: function( selector ) {
    5267                        var views = this.get( selector );
    5368                        return views && views.length ? views[0] : null;
    5469                },
    5570
    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.
     71                /**
     72                 * Registers subview(s).
     73                 *
     74                 * Registers any number of `views` to a `selector`.
     75                 *
     76                 * When no `selector` is provided, the root selector (the empty string)
     77                 * is used. `views` accepts a `Backbone.View` instance or an array of
     78                 * `Backbone.View` instances.
     79                 *
     80                 * ---
     81                 *
     82                 * Accepts an `options` object, which has a significant effect on the
     83                 * resulting behavior.
     84                 *
     85                 * `options.silent` – *boolean, `false`*
     86                 * > If `options.silent` is true, no DOM modifications will be made.
     87                 *
     88                 * `options.add` – *boolean, `false`*
     89                 * > Use `Views.add()` as a shortcut for setting `options.add` to true.
     90                 *
     91                 * > By default, the provided `views` will replace
     92                 * any existing views associated with the selector. If `options.add`
     93                 * is true, the provided `views` will be added to the existing views.
     94                 *
     95                 * `options.at` – *integer, `undefined`*
     96                 * > When adding, to insert `views` at a specific index, use
     97                 * `options.at`. By default, `views` are added to the end of the array.
     98                 *
     99                 * @param {string}       selector A jQuery selector.
     100                 * @param {array|Object} views    The subviews for the main view.
     101                 * @param {Object}       options  Options for call. If `options.silent` is true, no DOM
     102                 *                                modifications will be made. Use `Views.add()` as a
     103                 *                                shortcut for setting `options.add` to true. If `options.add`
     104                 *                                is true, the provided `views` will be added to the existing
     105                 *                                views. When adding, to insert `views` at a specific index,
     106                 *                                use `options.at`.
     107                 *
     108                 * @return wp.Backbone.Subviews
     109                 */
    82110                set: function( selector, views, options ) {
    83111                        var existing, next;
    84112
    … …  
    134162                        return this;
    135163                },
    136164
    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()`.
     165                /**
     166                 * Add subview(s) to existing subviews.
     167                 *
     168                 * An alias to `Views.set()`, which defaults `options.add` to true.
     169                 *
     170                 * Adds any number of `views` to a `selector`.
     171                 *
     172                 * When no `selector` is provided, the root selector (the empty string)
     173                 * is used. `views` accepts a `Backbone.View` instance or an array of
     174                 * `Backbone.View` instances.
     175                 *
     176                 * Uses `Views.set()` when setting `options.add` to `false`.
     177                 *
     178                 * Accepts an `options` object. By default, provided `views` will be
     179                 * inserted at the end of the array of existing views. To insert
     180                 * `views` at a specific index, use `options.at`. If `options.silent`
     181                 * is true, no DOM modifications will be made.
     182                 *
     183                 * For more information on the `options` object, see `Views.set()`.
     184                 *
     185                 * @param {string}       selector A jQuery selector.
     186                 * @param {array|object} views    The subviews for the main view.
     187                 * @param {Object}       options  Options for call.  To insert `views` at a specific index,
     188                 *                                use `options.at`. If `options.silent` is true, no DOM
     189                 *                                modifications will be made.
     190                 *
     191                 * @return wp.Backbone.Subviews
     192                 */
    155193                add: function( selector, views, options ) {
    156194                        if ( ! _.isString( selector ) ) {
    157195                                options  = views;
    … …  
    162200                        return this.set( selector, views, _.extend({ add: true }, options ) );
    163201                },
    164202
    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.
     203                /**
     204                 * Removes an added subview.
     205                 *
     206                 * Stops tracking `views` registered to a `selector`. If no `views` are
     207                 * set, then all of the `selector`'s subviews will be unregistered and
     208                 * removed.
     209                 *
     210                 * Accepts an `options` object. If `options.silent` is set, `remove`
     211                 * will *not* be triggered on the unregistered views.
     212                 *
     213                 * @param {string}       selector A jQuery selector.
     214                 * @param {array|object} views    The subviews for the main view.
     215                 * @param {}             options  Options for call. If `options.silent` is set,
     216                 *                                `remove` will *not* be triggered on the unregistered
     217                 *                                views.
     218                 *
     219                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     220                 */
    173221                unset: function( selector, views, options ) {
    174222                        var existing;
    175223
    … …  
    192240                        return this;
    193241                },
    194242
    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()`.
     243                /**
     244                 * Detaches all subviews.
     245                 *
     246                 * Helps to preserve all subview events when re-rendering the master
     247                 * view. Used in conjunction with `Views.render()`.
     248                 *
     249                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     250                 */
    201251                detach: function() {
    202252                        $( _.pluck( this.all(), 'el' ) ).detach();
    203253                        return this;
    204254                },
    205255
    206                 // ### Render all subviews
    207                 //
    208                 // Renders all subviews. Used in conjunction with `Views.detach()`.
     256                /**
     257                 * Renders all subviews
     258                 *
     259                 * Used in conjunction with `Views.detach()`.
     260                 *
     261                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     262                */
    209263                render: function() {
    210264                        var options = {
    211265                                        ready: this._isReady()
    … …  
    219273                        return this;
    220274                },
    221275
    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.
     276                /**
     277                 * Removes all subviews
     278                 *
     279                 * Triggers the `remove()` method on all subviews. Detaches the master
     280                 * view from its parent. Resets the internals of the views manager.
     281                 *
     282                 * Accepts an `options` object. If `options.silent` is set, `unset`
     283                 * will *not* be triggered on the master view's parent.
     284                 *
     285                 * @param {Object}  options        Options for call.
     286                 * @param {boolean} options.silent If true, `unset` wil *not* be triggered on
     287                 *                                 the master views' parent.
     288                 *
     289                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     290                */
    229291                remove: function( options ) {
    230292                        if ( ! options || ! options.silent ) {
    231293                                if ( this.parent && this.parent.views )
    … …  
    239301                        return this;
    240302                },
    241303
    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.
     304                /**
     305                * Replaces a selector's subviews
     306                *
     307                * By default, sets the `$target` selector's html to the subview `els`.
     308                *
     309                * Can be overridden in subclasses.
     310                *
     311                * @param {string} $target Selector where to put the elements.
     312                * @param {*} els HTML or elements to put into the selector's HTML.
     313                *
     314                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     315                */
    247316                replace: function( $target, els ) {
    248317                        $target.html( els );
    249318                        return this;
    250319                },
    251320
    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.
     321                /**
     322                 * Insert subviews into a selector
     323                 *
     324                 * By default, appends the subview `els` to the end of the `$target`
     325                 * selector. If `options.at` is set, inserts the subview `els` at the
     326                 * provided index.
     327                 *
     328                 * Can be overridden in subclasses.
     329                 *
     330                 * @param {string}  $target    Selector where to put the elements.
     331                 * @param {*}       els        HTML or elements to put at the end of the $target.
     332                 * @param {?Object} options    Options for call.
     333                 * @param {?number} options.at At which index to put the elements.
     334                 *
     335                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     336                 */
    259337                insert: function( $target, els, options ) {
    260338                        var at = options && options.at,
    261339                                $children;
    … …  
    268346                        return this;
    269347                },
    270348
    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.
     349                /**
     350                 * Triggers the ready event.
     351                 *
     352                 * Only use this method if you know what you're doing. For performance reasons,
     353                 * this method does not check if the view is actually attached to the DOM. It's
     354                 * taking your word for it.
     355                 *
     356                 * Fires the ready event on the current view and all attached subviews.
     357                 */
    278358                ready: function() {
    279359                        this.view.trigger('ready');
    280360
    … …  
    283363                                return view.views;
    284364                        }).flatten().where({ attached: true }).invoke('ready');
    285365                },
    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.
     366                /**
     367                 * Attaches a series of views to a selector. Internal.
     368                 *
     369                 * Checks to see if a matching selector exists, renders the views,
     370                 * performs the proper DOM operation, and then checks if the view is
     371                 * attached to the document.
     372                 *
     373                 * @private
     374                 *
     375                 * @param {string}       selector A jQuery selector.
     376                 * @param {array|object} views    The subviews for the main view.
     377                 * @param {Object}       options  Options for call.
     378                 * @param {boolean}      options.add  If true the provided views will be added.
     379                 *
     380                 * @return {wp.Backbone.Subviews} The current Subviews instance.
     381                 */
    292382                _attach: function( selector, views, options ) {
    293383                        var $selector = selector ? this.view.$( selector ) : this.view.$el,
    294384                                managers;
    … …  
    336426                }
    337427        });
    338428
     429        wp.Backbone.View = Backbone.View.extend({
    339430
    340         // wp.Backbone.View
    341         // ----------------
    342         //
    343         // The base view class.
    344         wp.Backbone.View = Backbone.View.extend({
    345431                // The constructor for the `Views` manager.
    346432                Subviews: wp.Backbone.Subviews,
    347433
     434                /**
     435                 * The base view class.
     436                 *
     437                 * This extends the backbone view to have a build-in way to use subviews. This makes
     438                 * it easier to have nested views.
     439                 *
     440                 * @memberOf wp.Backbone
     441                 *
     442                 * @constructs
     443                 * @augments Backbone.View
     444                 *
     445                 * @param {Object} options The options for this view.
     446                 */
    348447                constructor: function( options ) {
    349448                        this.views = new this.Subviews( this, this.views );
    350449                        this.on( 'ready', this.ready, this );
    … …  
    354453                        Backbone.View.apply( this, arguments );
    355454                },
    356455
     456                /**
     457                 * Removes this view and all subviews.
     458                 */
    357459                remove: function() {
    358460                        var result = Backbone.View.prototype.remove.apply( this, arguments );
    359461
    … …  
    364466                        return result;
    365467                },
    366468
     469                /**
     470                 * Renders this view and all subviews.
     471                 *
     472                 * @returns {wp.Backbone.View} The current instance of the view.
     473                 */
    367474                render: function() {
    368475                        var options;
    369476
    … …  
    382489                        return this;
    383490                },
    384491
     492                /**
     493                 * Returns the options for this view.
     494                 *
     495                 * @returns {Object} The options for this view.
     496                 */
    385497                prepare: function() {
    386498                        return this.options;
    387499                },
    388500
     501                /**
     502                 * Method that is called when the ready event is triggered.
     503                 */
    389504                ready: function() {}
    390505        });
    391506}(jQuery));