1/** 2 * @output wp-includes/js/wp-backbone.js 3 */ 4 5/** @namespace wp */ 6window.wp = window.wp || {}; 7 8(function ($) { 9 /** 10 * Create the WordPress Backbone namespace. 11 * 12 * @namespace wp.Backbone 13 */ 14 wp.Backbone = {}; 15 16 /** 17 * A backbone subview manager. 18 * 19 * @since 3.5.0 20 * @since 3.6.0 Moved wp.media.Views to wp.Backbone.Subviews. 21 * 22 * @memberOf wp.Backbone 23 * 24 * @class 25 * 26 * @param {wp.Backbone.View} view The main view. 27 * @param {Array|Object} views The subviews for the main view. 28 */ 29 wp.Backbone.Subviews = function( view, views ) { 30 this.view = view; 31 this._views = _.isArray( views ) ? { '': views } : views || {}; 32 }; 33 34 wp.Backbone.Subviews.extend = Backbone.Model.extend; 35 36 _.extend( wp.Backbone.Subviews.prototype, { 37 /** 38 * Fetches all of the subviews. 39 * 40 * @since 3.5.0 41 * 42 * @return {Array} All the subviews. 43 */ 44 all: function() { 45 return _.flatten( _.values( this._views ) ); 46 }, 47 48 /** 49 * Fetches all subviews that match a given `selector`. 50 * 51 * If no `selector` is provided, it will grab all subviews attached 52 * to the view's root. 53 * 54 * @since 3.5.0 55 * 56 * @param {string} selector A jQuery selector. 57 * 58 * @return {Array} All the subviews that match the selector. 59 */ 60 get: function( selector ) { 61 selector = selector || ''; 62 return this._views[ selector ]; 63 }, 64 65 /** 66 * Fetches the first subview that matches a given `selector`. 67 * 68 * If no `selector` is provided, it will grab the first subview attached to the 69 * view's root. 70 * 71 * Useful when a selector only has one subview at a time. 72 * 73 * @since 3.5.0 74 * 75 * @param {string} selector A jQuery selector. 76 * 77 * @return {Backbone.View} The view. 78 */ 79 first: function( selector ) { 80 var views = this.get( selector ); 81 return views && views.length ? views[0] : null; 82 }, 83 84 /** 85 * Registers subview(s). 86 * 87 * Registers any number of `views` to a `selector`. 88 * 89 * When no `selector` is provided, the root selector (the empty string) 90 * is used. `views` accepts a `Backbone.View` instance or an array of 91 * `Backbone.View` instances. 92 * 93 * --- 94 * 95 * Accepts an `options` object, which has a significant effect on the 96 * resulting behavior. 97 * 98 * `options.silent` - *boolean, `false`* 99 * If `options.silent` is true, no DOM modifications will be made. 100 * 101 * `options.add` - *boolean, `false`* 102 * Use `Views.add()` as a shortcut for setting `options.add` to true. 103 * 104 * By default, the provided `views` will replace any existing views 105 * associated with the selector. If `options.add` is true, the provided 106 * `views` will be added to the existing views. 107 * 108 * `options.at` - *integer, `undefined`* 109 * When adding, to insert `views` at a specific index, use `options.at`. 110 * By default, `views` are added to the end of the array. 111 * 112 * @since 3.5.0 113 * 114 * @param {string} selector A jQuery selector. 115 * @param {Array|Object} views The subviews for the main view. 116 * @param {Object} options Options for call. If `options.silent` is true, 117 * no DOM modifications will be made. Use 118 * `Views.add()` as a shortcut for setting 119 * `options.add` to true. If `options.add` is 120 * true, the provided `views` will be added to 121 * the existing views. When adding, to insert 122 * `views` at a specific index, use `options.at`. 123 * 124 * @return {wp.Backbone.Subviews} The current Subviews instance. 125 */ 126 set: function( selector, views, options ) { 127 var existing, next; 128 129 if ( ! _.isString( selector ) ) { 130 options = views; 131 views = selector; 132 selector = ''; 133 } 134 135 options = options || {}; 136 views = _.isArray( views ) ? views : [ views ]; 137 existing = this.get( selector ); 138 next = views; 139 140 if ( existing ) { 141 if ( options.add ) { 142 if ( _.isUndefined( options.at ) ) { 143 next = existing.concat( views ); 144 } else { 145 next = existing; 146 next.splice.apply( next, [ options.at, 0 ].concat( views ) ); 147 } 148 } else { 149 _.each( next, function( view ) { 150 view.__detach = true; 151 }); 152 153 _.each( existing, function( view ) { 154 if ( view.__detach ) 155 view.$el.detach(); 156 else 157 view.remove(); 158 }); 159 160 _.each( next, function( view ) { 161 delete view.__detach; 162 }); 163 } 164 } 165 166 this._views[ selector ] = next; 167 168 _.each( views, function( subview ) { 169 var constructor = subview.Views || wp.Backbone.Subviews, 170 subviews = subview.views = subview.views || new constructor( subview ); 171 subviews.parent = this.view; 172 subviews.selector = selector; 173 }, this ); 174 175 if ( ! options.silent ) 176 this._attach( selector, views, _.extend({ ready: this._isReady() }, options ) ); 177 178 return this; 179 }, 180 181 /** 182 * Add subview(s) to existing subviews. 183 * 184 * An alias to `Views.set()`, which defaults `options.add` to true. 185 * 186 * Adds any number of `views` to a `selector`. 187 * 188 * When no `selector` is provided, the root selector (the empty string) 189 * is used. `views` accepts a `Backbone.View` instance or an array of 190 * `Backbone.View` instances. 191 * 192 * Uses `Views.set()` when setting `options.add` to `false`. 193 * 194 * Accepts an `options` object. By default, provided `views` will be 195 * inserted at the end of the array of existing views. To insert 196 * `views` at a specific index, use `options.at`. If `options.silent` 197 * is true, no DOM modifications will be made. 198 * 199 * For more information on the `options` object, see `Views.set()`. 200 * 201 * @since 3.5.0 202 * 203 * @param {string} selector A jQuery selector. 204 * @param {Array|Object} views The subviews for the main view. 205 * @param {Object} options Options for call. To insert `views` at a 206 * specific index, use `options.at`. If 207 * `options.silent` is true, no DOM modifications 208 * will be made. 209 * 210 * @return {wp.Backbone.Subviews} The current subviews instance. 211 */ 212 add: function( selector, views, options ) { 213 if ( ! _.isString( selector ) ) { 214 options = views; 215 views = selector; 216 selector = ''; 217 } 218 219 return this.set( selector, views, _.extend({ add: true }, options ) ); 220 }, 221 222 /** 223 * Removes an added subview. 224 * 225 * Stops tracking `views` registered to a `selector`. If no `views` are 226 * set, then all of the `selector`'s subviews will be unregistered and 227 * removed. 228 * 229 * Accepts an `options` object. If `options.silent` is set, `remove` 230 * will *not* be triggered on the unregistered views. 231 * 232 * @since 3.5.0 233 * 234 * @param {string} selector A jQuery selector. 235 * @param {Array|Object} views The subviews for the main view. 236 * @param {Object} options Options for call. If `options.silent` is set, 237 * `remove` will *not* be triggered on the 238 * unregistered views. 239 * 240 * @return {wp.Backbone.Subviews} The current Subviews instance. 241 */ 242 unset: function( selector, views, options ) { 243 var existing; 244 245 if ( ! _.isString( selector ) ) { 246 options = views; 247 views = selector; 248 selector = ''; 249 } 250 251 views = views || []; 252 253 if ( existing = this.get( selector ) ) { 254 views = _.isArray( views ) ? views : [ views ]; 255 this._views[ selector ] = views.length ? _.difference( existing, views ) : []; 256 } 257 258 if ( ! options || ! options.silent ) 259 _.invoke( views, 'remove' ); 260 261 return this; 262 }, 263 264 /** 265 * Detaches all subviews. 266 * 267 * Helps to preserve all subview events when re-rendering the master 268 * view. Used in conjunction with `Views.render()`. 269 * 270 * @since 3.5.0 271 * 272 * @return {wp.Backbone.Subviews} The current Subviews instance. 273 */ 274 detach: function() { 275 $( _.pluck( this.all(), 'el' ) ).detach(); 276 return this; 277 }, 278 279 /** 280 * Renders all subviews. 281 * 282 * Used in conjunction with `Views.detach()`. 283 * 284 * @since 3.5.0 285 * 286 * @return {wp.Backbone.Subviews} The current Subviews instance. 287 */ 288 render: function() { 289 var options = { 290 ready: this._isReady() 291 }; 292 293 _.each( this._views, function( views, selector ) { 294 this._attach( selector, views, options ); 295 }, this ); 296 297 this.rendered = true; 298 return this; 299 }, 300 301 /** 302 * Removes all subviews. 303 * 304 * Triggers the `remove()` method on all subviews. Detaches the master 305 * view from its parent. Resets the internals of the views manager. 306 * 307 * Accepts an `options` object. If `options.silent` is set, `unset` 308 * will *not* be triggered on the master view's parent. 309 * 310 * @since 3.6.0 311 * 312 * @param {Object} options Options for call. 313 * @param {boolean} options.silent If true, `unset` will *not* be triggered on 314 * the master views' parent. 315 * 316 * @return {wp.Backbone.Subviews} The current Subviews instance. 317 */ 318 remove: function( options ) { 319 if ( ! options || ! options.silent ) { 320 if ( this.parent && this.parent.views ) 321 this.parent.views.unset( this.selector, this.view, { silent: true }); 322 delete this.parent; 323 delete this.selector; 324 } 325 326 _.invoke( this.all(), 'remove' ); 327 this._views = []; 328 return this; 329 }, 330 331 /** 332 * Replaces a selector's subviews 333 * 334 * By default, sets the `$target` selector's html to the subview `els`. 335 * 336 * Can be overridden in subclasses. 337 * 338 * @since 3.5.0 339 * 340 * @param {string} $target Selector where to put the elements. 341 * @param {*} els HTML or elements to put into the selector's HTML. 342 * 343 * @return {wp.Backbone.Subviews} The current Subviews instance. 344 */ 345 replace: function( $target, els ) { 346 $target.html( els ); 347 return this; 348 }, 349 350 /** 351 * Insert subviews into a selector. 352 * 353 * By default, appends the subview `els` to the end of the `$target` 354 * selector. If `options.at` is set, inserts the subview `els` at the 355 * provided index. 356 * 357 * Can be overridden in subclasses. 358 * 359 * @since 3.5.0 360 * 361 * @param {string} $target Selector where to put the elements. 362 * @param {*} els HTML or elements to put at the end of the 363 * $target. 364 * @param {?Object} options Options for call. 365 * @param {?number} options.at At which index to put the elements. 366 * 367 * @return {wp.Backbone.Subviews} The current Subviews instance. 368 */ 369 insert: function( $target, els, options ) { 370 var at = options && options.at, 371 $children; 372 373 if ( _.isNumber( at ) && ($children = $target.children()).length > at ) 374 $children.eq( at ).before( els ); 375 else 376 $target.append( els ); 377 378 return this; 379 }, 380 381 /** 382 * Triggers the ready event. 383 *
384 * Only use this method if you know what you're doing. For performance reasons, 385 * this method does not check if the view is actually attached to the DOM. It's 386 * taking your word for it. 387 * 388 * Fires the ready event on the current view and all attached subviews. 389 * 390 * @since 3.5.0 391 */ 392 ready: function() { 393 this.view.trigger('ready'); 394 395 // Find all attached subviews, and call ready on them. 396 _.chain( this.all() ).map( function( view ) { 397 return view.views; 398 }).flatten().where({ attached: true }).invoke('ready'); 399 }, 400 /** 401 * Attaches a series of views to a selector. Internal. 402 * 403 * Checks to see if a matching selector exists, renders the views, 404 * performs the proper DOM operation, and then checks if the view is 405 * attached to the document. 406 * 407 * @since 3.5.0 408 * 409 * @private 410 * 411 * @param {string} selector A jQuery selector. 412 * @param {Array|Object} views The subviews for the main view. 413 * @param {Object} options Options for call. 414 * @param {boolean} options.add If true the provided views will be added. 415 * 416 * @return {wp.Backbone.Subviews} The current Subviews instance. 417 */ 418 _attach: function( selector, views, options ) { 419 var $selector = selector ? this.view.$( selector ) : this.view.$el, 420 managers; 421 422 // Check if we found a location to attach the views. 423 if ( ! $selector.length ) 424 return this; 425 426 managers = _.chain( views ).pluck('views').flatten().value(); 427 428 // Render the views if necessary. 429 _.each( managers, function( manager ) { 430 if ( manager.rendered ) 431 return; 432 433 manager.view.render(); 434 manager.rendered = true; 435 }, this ); 436 437 // Insert or replace the views. 438 this[ options.add ? 'insert' : 'replace' ]( $selector, _.pluck( views, 'el' ), options ); 439 440 /* 441 * Set attached and trigger ready if the current view is already 442 * attached to the DOM. 443 */ 444 _.each( managers, function( manager ) { 445 manager.attached = true; 446 447 if ( options.ready ) 448 manager.ready(); 449 }, this ); 450 451 return this; 452 }, 453 454 /** 455 * Determines whether or not the current view is in the DOM. 456 * 457 * @since 3.5.0 458 * 459 * @private 460 * 461 * @return {boolean} Whether or not the current view is in the DOM. 462 */ 463 _isReady: function() { 464 var node = this.view.el; 465 while ( node ) { 466 if ( node === document.body ) 467 return true; 468 node = node.parentNode; 469 } 470 471 return false; 472 } 473 }); 474 475 wp.Backbone.View = Backbone.View.extend({ 476 477 // The constructor for the `Views` manager. 478 Subviews: wp.Backbone.Subviews, 479 480 /** 481 * The base view class. 482 * 483 * This extends the backbone view to have a build-in way to use subviews. This 484 * makes it easier to have nested views. 485 * 486 * @since 3.5.0 487 * @since 3.6.0 Moved wp.media.View to wp.Backbone.View 488 * 489 * @constructs 490 * @augments Backbone.View 491 * 492 * @memberOf wp.Backbone 493 * 494 * 495 * @param {Object} options The options for this view. 496 */ 497 constructor: function( options ) { 498 this.views = new this.Subviews( this, this.views ); 499 this.on( 'ready', this.ready, this ); 500 501 this.options = options || {}; 502 503 Backbone.View.apply( this, arguments ); 504 }, 505 506 /** 507 * Removes this view and all subviews. 508 * 509 * @since 3.5.0 510 * 511 * @return {wp.Backbone.Subviews} The current Subviews instance. 512 */ 513 remove: function() { 514 var result = Backbone.View.prototype.remove.apply( this, arguments ); 515 516 // Recursively remove child views. 517 if ( this.views ) 518 this.views.remove(); 519 520 return result; 521 }, 522 523 /** 524 * Renders this view and all subviews. 525 * 526 * @since 3.5.0 527 * 528 * @return {wp.Backbone.View} The current instance of the view. 529 */ 530 render: function() { 531 var options; 532 533 if ( this.prepare ) 534 options = this.prepare(); 535 536 this.views.detach(); 537 538 if ( this.template ) { 539 options = options || {}; 540 this.trigger( 'prepare', options ); 541 this.$el.html( this.template( options ) ); 542 } 543 544 this.views.render(); 545 return this; 546 }, 547 548 /** 549 * Returns the options for this view. 550 * 551 * @since 3.5.0 552 * 553 * @return {Object} The options for this view. 554 */ 555 prepare: function() { 556 return this.options; 557 }, 558 559 /** 560 * Method that is called when the ready event is triggered. 561 * 562 * @since 3.5.0 563 */ 564 ready: function() {} 565 }); 566}(jQuery));
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.