Add some `@since` annotations to `media-views.js`.

Props DrewAPicture.
See #28459.

Built from https://develop.svn.wordpress.org/trunk@29739


git-svn-id: http://core.svn.wordpress.org/trunk@29513 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Scott Taylor 2014-09-12 03:36:16 +00:00
parent 613571202c
commit 836e0f8cd5
1 changed files with 169 additions and 0 deletions

View File

@ -96,6 +96,8 @@
/** /**
* Activate a mode. * Activate a mode.
* *
* @since 3.5.0
*
* @param {string} mode * @param {string} mode
* *
* @fires this.view#{this.id}:activate:{this._mode} * @fires this.view#{this.id}:activate:{this._mode}
@ -137,6 +139,8 @@
/** /**
* Render a mode. * Render a mode.
* *
* @since 3.5.0
*
* @param {string} mode * @param {string} mode
* *
* @fires this.view#{this.id}:create:{this._mode} * @fires this.view#{this.id}:create:{this._mode}
@ -184,6 +188,8 @@
/** /**
* Get the region's view. * Get the region's view.
* *
* @since 3.5.0
*
* @returns {wp.media.View} * @returns {wp.media.View}
*/ */
get: function() { get: function() {
@ -193,6 +199,8 @@
/** /**
* Set the region's view as a subview of the frame. * Set the region's view as a subview of the frame.
* *
* @since 3.5.0
*
* @param {Array|Object} views * @param {Array|Object} views
* @param {Object} [options={}] * @param {Object} [options={}]
* @returns {wp.Backbone.Subviews} Subviews is returned to allow chaining * @returns {wp.Backbone.Subviews} Subviews is returned to allow chaining
@ -207,6 +215,8 @@
/** /**
* Trigger regional view events on the frame. * Trigger regional view events on the frame.
* *
* @since 3.5.0
*
* @param {string} event * @param {string} event
* @returns {undefined|wp.media.controller.Region} Returns itself to allow chaining. * @returns {undefined|wp.media.controller.Region} Returns itself to allow chaining.
*/ */
@ -234,6 +244,8 @@
/** /**
* wp.media.controller.StateMachine * wp.media.controller.StateMachine
* *
* @since 3.5.0
*
* @constructor * @constructor
* @augments Backbone.Model * @augments Backbone.Model
* @mixin * @mixin
@ -259,6 +271,8 @@
* Ensure that the `states` collection exists so the `StateMachine` * Ensure that the `states` collection exists so the `StateMachine`
* can be used as a mixin. * can be used as a mixin.
* *
* @since 3.5.0
*
* @param {string} id * @param {string} id
* @returns {wp.media.controller.State} Returns a State model * @returns {wp.media.controller.State} Returns a State model
* from the StateMachine collection * from the StateMachine collection
@ -282,6 +296,8 @@
* created the `states` collection, or are trying to select a state * created the `states` collection, or are trying to select a state
* that does not exist. * that does not exist.
* *
* @since 3.5.0
*
* @param {string} id * @param {string} id
* *
* @fires wp.media.controller.State#deactivate * @fires wp.media.controller.State#deactivate
@ -313,6 +329,8 @@
* Call the `state()` method with no parameters to retrieve the current * Call the `state()` method with no parameters to retrieve the current
* active state. * active state.
* *
* @since 3.5.0
*
* @returns {wp.media.controller.State} Returns a State model * @returns {wp.media.controller.State} Returns a State model
* from the StateMachine collection * from the StateMachine collection
*/ */
@ -349,6 +367,11 @@
* @augments Backbone.Model * @augments Backbone.Model
*/ */
media.controller.State = Backbone.Model.extend({ media.controller.State = Backbone.Model.extend({
/**
* Constructor.
*
* @since 3.5.0
*/
constructor: function() { constructor: function() {
this.on( 'activate', this._preActivate, this ); this.on( 'activate', this._preActivate, this );
this.on( 'activate', this.activate, this ); this.on( 'activate', this.activate, this );
@ -366,34 +389,47 @@
}, },
/** /**
* @abstract * @abstract
* @since 3.5.0
*/ */
ready: function() {}, ready: function() {},
/** /**
* @abstract * @abstract
* @since 3.5.0
*/ */
activate: function() {}, activate: function() {},
/** /**
* @abstract * @abstract
* @since 3.5.0
*/ */
deactivate: function() {}, deactivate: function() {},
/** /**
* @abstract * @abstract
* @since 3.5.0
*/ */
reset: function() {}, reset: function() {},
/** /**
* @access private * @access private
* @since 4.0.0
*/ */
_ready: function() { _ready: function() {
this._updateMenu(); this._updateMenu();
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_preActivate: function() { _preActivate: function() {
this.active = true; this.active = true;
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_postActivate: function() { _postActivate: function() {
this.on( 'change:menu', this._menu, this ); this.on( 'change:menu', this._menu, this );
@ -409,8 +445,10 @@
this._content(); this._content();
this._router(); this._router();
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_deactivate: function() { _deactivate: function() {
this.active = false; this.active = false;
@ -422,20 +460,26 @@
this.off( 'change:content', this._content, this ); this.off( 'change:content', this._content, this );
this.off( 'change:toolbar', this._toolbar, this ); this.off( 'change:toolbar', this._toolbar, this );
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_title: function() { _title: function() {
this.frame.title.render( this.get('titleMode') || 'default' ); this.frame.title.render( this.get('titleMode') || 'default' );
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_renderTitle: function( view ) { _renderTitle: function( view ) {
view.$el.text( this.get('title') || '' ); view.$el.text( this.get('title') || '' );
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_router: function() { _router: function() {
var router = this.frame.router, var router = this.frame.router,
@ -454,8 +498,10 @@
view.select( this.frame.content.mode() ); view.select( this.frame.content.mode() );
} }
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_menu: function() { _menu: function() {
var menu = this.frame.menu, var menu = this.frame.menu,
@ -474,8 +520,10 @@
view.select( this.id ); view.select( this.id );
} }
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_updateMenu: function() { _updateMenu: function() {
var previous = this.previous('menu'), var previous = this.previous('menu'),
@ -489,8 +537,10 @@
this.frame.on( 'menu:render:' + menu, this._renderMenu, this ); this.frame.on( 'menu:render:' + menu, this._renderMenu, this );
} }
}, },
/** /**
* @access private * @access private
* @since 3.5.0
*/ */
_renderMenu: function( view ) { _renderMenu: function( view ) {
var menuItem = this.get('menuItem'), var menuItem = this.get('menuItem'),
@ -526,6 +576,9 @@
}); });
media.selectionSync = { media.selectionSync = {
/**
* @since 3.5.0
*/
syncSelection: function() { syncSelection: function() {
var selection = this.get('selection'), var selection = this.get('selection'),
manager = this.frame._selection; manager = this.frame._selection;
@ -553,6 +606,8 @@
* of the selection's attachments and the set of selected * of the selection's attachments and the set of selected
* attachments that this specific selection considered invalid. * attachments that this specific selection considered invalid.
* Reset the difference and record the single attachment. * Reset the difference and record the single attachment.
*
* @since 3.5.0
*/ */
recordSelection: function() { recordSelection: function() {
var selection = this.get('selection'), var selection = this.get('selection'),
@ -607,6 +662,8 @@
/** /**
* If a library isn't provided, query all media items. * If a library isn't provided, query all media items.
* If a selection instance isn't provided, create one. * If a selection instance isn't provided, create one.
*
* @since 3.5.0
*/ */
initialize: function() { initialize: function() {
var selection = this.get('selection'), var selection = this.get('selection'),
@ -637,6 +694,9 @@
this.resetDisplays(); this.resetDisplays();
}, },
/**
* @since 3.5.0
*/
activate: function() { activate: function() {
this.syncSelection(); this.syncSelection();
@ -650,6 +710,9 @@
} }
}, },
/**
* @since 3.5.0
*/
deactivate: function() { deactivate: function() {
this.recordSelection(); this.recordSelection();
@ -662,12 +725,18 @@
wp.Uploader.queue.off( null, null, this ); wp.Uploader.queue.off( null, null, this );
}, },
/**
* @since 3.5.0
*/
reset: function() { reset: function() {
this.get('selection').reset(); this.get('selection').reset();
this.resetDisplays(); this.resetDisplays();
this.refreshContent(); this.refreshContent();
}, },
/**
* @since 3.5.0
*/
resetDisplays: function() { resetDisplays: function() {
var defaultProps = media.view.settings.defaultProps; var defaultProps = media.view.settings.defaultProps;
this._displays = []; this._displays = [];
@ -679,6 +748,8 @@
}, },
/** /**
* @since 3.5.0
*
* @param {wp.media.model.Attachment} attachment * @param {wp.media.model.Attachment} attachment
* @returns {Backbone.Model} * @returns {Backbone.Model}
*/ */
@ -692,6 +763,8 @@
}, },
/** /**
* @since 3.6.0
*
* @param {wp.media.model.Attachment} attachment * @param {wp.media.model.Attachment} attachment
* @returns {Object} * @returns {Object}
*/ */
@ -704,6 +777,8 @@
}, },
/** /**
* @since 3.6.0
*
* @param {wp.media.model.Attachment} attachment * @param {wp.media.model.Attachment} attachment
* @returns {Boolean} * @returns {Boolean}
*/ */
@ -724,6 +799,8 @@
* If the state is active, no items are selected, and the current * If the state is active, no items are selected, and the current
* content mode is not an option in the state's router (provided * content mode is not an option in the state's router (provided
* the state has a router), reset the content mode to the default. * the state has a router), reset the content mode to the default.
*
* @since 3.5.0
*/ */
refreshContent: function() { refreshContent: function() {
var selection = this.get('selection'), var selection = this.get('selection'),
@ -745,6 +822,8 @@
* limit themselves to one attachment (in this case, the last * limit themselves to one attachment (in this case, the last
* attachment in the upload queue). * attachment in the upload queue).
* *
* @since 3.5.0
*
* @param {wp.media.model.Attachment} attachment * @param {wp.media.model.Attachment} attachment
*/ */
uploading: function( attachment ) { uploading: function( attachment ) {
@ -762,6 +841,8 @@
/** /**
* Only track the browse router on library states. * Only track the browse router on library states.
*
* @since 3.5.0
*/ */
saveContentMode: function() { saveContentMode: function() {
if ( 'browse' !== this.get('router') ) { if ( 'browse' !== this.get('router') ) {
@ -800,11 +881,19 @@
priority: 60 priority: 60
}, media.controller.Library.prototype.defaults ), }, media.controller.Library.prototype.defaults ),
/**
* @since 3.9.0
*
* @param options Attributes
*/
initialize: function( options ) { initialize: function( options ) {
this.image = options.image; this.image = options.image;
media.controller.State.prototype.initialize.apply( this, arguments ); media.controller.State.prototype.initialize.apply( this, arguments );
}, },
/**
* @since 3.9.0
*/
activate: function() { activate: function() {
this.frame.modal.$el.addClass('image-details'); this.frame.modal.$el.addClass('image-details');
} }
@ -844,6 +933,9 @@
syncSelection: false syncSelection: false
}, },
/**
* @since 3.9.0
*/
initialize: function() { initialize: function() {
// If we haven't been provided a `library`, create a `Selection`. // If we haven't been provided a `library`, create a `Selection`.
if ( ! this.get('library') ) if ( ! this.get('library') )
@ -855,6 +947,9 @@
media.controller.Library.prototype.initialize.apply( this, arguments ); media.controller.Library.prototype.initialize.apply( this, arguments );
}, },
/**
* since 3.9.0
*/
activate: function() { activate: function() {
var library = this.get('library'); var library = this.get('library');
@ -869,6 +964,9 @@
media.controller.Library.prototype.activate.apply( this, arguments ); media.controller.Library.prototype.activate.apply( this, arguments );
}, },
/**
* @since 3.9.0
*/
deactivate: function() { deactivate: function() {
// Stop watching for uploaded attachments. // Stop watching for uploaded attachments.
this.get('library').unobserve( wp.Uploader.queue ); this.get('library').unobserve( wp.Uploader.queue );
@ -878,6 +976,11 @@
media.controller.Library.prototype.deactivate.apply( this, arguments ); media.controller.Library.prototype.deactivate.apply( this, arguments );
}, },
/**
* @since 3.9.0
*
* @param browser
*/
gallerySettings: function( browser ) { gallerySettings: function( browser ) {
if ( ! this.get('displaySettings') ) { if ( ! this.get('displaySettings') ) {
return; return;
@ -936,6 +1039,9 @@
syncSelection: false syncSelection: false
}, media.controller.Library.prototype.defaults ), }, media.controller.Library.prototype.defaults ),
/**
* @since 3.9.0
*/
initialize: function() { initialize: function() {
// If we haven't been provided a `library`, create a `Selection`. // If we haven't been provided a `library`, create a `Selection`.
if ( ! this.get('library') ) if ( ! this.get('library') )
@ -944,6 +1050,9 @@
media.controller.Library.prototype.initialize.apply( this, arguments ); media.controller.Library.prototype.initialize.apply( this, arguments );
}, },
/**
* @since 3.9.0
*/
activate: function() { activate: function() {
var library = this.get('library'), var library = this.get('library'),
edit = this.frame.state('gallery-edit').get('library'); edit = this.frame.state('gallery-edit').get('library');
@ -998,6 +1107,9 @@
syncSelection: false syncSelection: false
}, },
/**
* @since 3.9.0
*/
initialize: function() { initialize: function() {
var collectionType = this.get('collectionType'); var collectionType = this.get('collectionType');
@ -1019,6 +1131,9 @@
media.controller.Library.prototype.initialize.apply( this, arguments ); media.controller.Library.prototype.initialize.apply( this, arguments );
}, },
/**
* @since 3.9.0
*/
activate: function() { activate: function() {
var library = this.get('library'); var library = this.get('library');
@ -1033,6 +1148,9 @@
media.controller.Library.prototype.activate.apply( this, arguments ); media.controller.Library.prototype.activate.apply( this, arguments );
}, },
/**
* @since 3.9.0
*/
deactivate: function() { deactivate: function() {
// Stop watching for uploaded attachments. // Stop watching for uploaded attachments.
this.get('library').unobserve( wp.Uploader.queue ); this.get('library').unobserve( wp.Uploader.queue );
@ -1042,6 +1160,11 @@
media.controller.Library.prototype.deactivate.apply( this, arguments ); media.controller.Library.prototype.deactivate.apply( this, arguments );
}, },
/**
* @since 3.9.0
*
* @param browser
*/
renderSettings: function( browser ) { renderSettings: function( browser ) {
var library = this.get('library'), var library = this.get('library'),
collectionType = this.get('collectionType'), collectionType = this.get('collectionType'),
@ -1100,6 +1223,9 @@
syncSelection: false syncSelection: false
}, media.controller.Library.prototype.defaults ), }, media.controller.Library.prototype.defaults ),
/**
* @since 3.9.0
*/
initialize: function() { initialize: function() {
var collectionType = this.get('collectionType'); var collectionType = this.get('collectionType');
@ -1118,6 +1244,9 @@
media.controller.Library.prototype.initialize.apply( this, arguments ); media.controller.Library.prototype.initialize.apply( this, arguments );
}, },
/**
* @since 3.9.0
*/
activate: function() { activate: function() {
var library = this.get('library'), var library = this.get('library'),
editLibrary = this.get('editLibrary'), editLibrary = this.get('editLibrary'),
@ -1167,6 +1296,9 @@
syncSelection: true syncSelection: true
}, media.controller.Library.prototype.defaults ), }, media.controller.Library.prototype.defaults ),
/**
* @since 3.5.0
*/
initialize: function() { initialize: function() {
var library, comparator; var library, comparator;
@ -1200,6 +1332,9 @@
library.observe( this.get('selection') ); library.observe( this.get('selection') );
}, },
/**
* @since 3.5.0
*/
activate: function() { activate: function() {
this.updateSelection(); this.updateSelection();
this.frame.on( 'open', this.updateSelection, this ); this.frame.on( 'open', this.updateSelection, this );
@ -1207,12 +1342,18 @@
media.controller.Library.prototype.activate.apply( this, arguments ); media.controller.Library.prototype.activate.apply( this, arguments );
}, },
/**
* @since 3.5.0
*/
deactivate: function() { deactivate: function() {
this.frame.off( 'open', this.updateSelection, this ); this.frame.off( 'open', this.updateSelection, this );
media.controller.Library.prototype.deactivate.apply( this, arguments ); media.controller.Library.prototype.deactivate.apply( this, arguments );
}, },
/**
* @since 3.5.0
*/
updateSelection: function() { updateSelection: function() {
var selection = this.get('selection'), var selection = this.get('selection'),
id = media.view.settings.post.featuredImageId, id = media.view.settings.post.featuredImageId,
@ -1251,6 +1392,11 @@
syncSelection: true syncSelection: true
}, media.controller.Library.prototype.defaults ), }, media.controller.Library.prototype.defaults ),
/**
* @since 3.9.0
*
* @param options
*/
initialize: function( options ) { initialize: function( options ) {
var library, comparator; var library, comparator;
@ -1285,11 +1431,17 @@
library.observe( this.get('selection') ); library.observe( this.get('selection') );
}, },
/**
* @since 3.9.0
*/
activate: function() { activate: function() {
this.updateSelection(); this.updateSelection();
media.controller.Library.prototype.activate.apply( this, arguments ); media.controller.Library.prototype.activate.apply( this, arguments );
}, },
/**
* @since 3.9.0
*/
updateSelection: function() { updateSelection: function() {
var selection = this.get('selection'), var selection = this.get('selection'),
attachment = this.image.attachment; attachment = this.image.attachment;
@ -1317,14 +1469,23 @@
url: '' url: ''
}, },
/**
* @since 3.9.0
*/
activate: function() { activate: function() {
this.listenTo( this.frame, 'toolbar:render:edit-image', this.toolbar ); this.listenTo( this.frame, 'toolbar:render:edit-image', this.toolbar );
}, },
/**
* @since 3.9.0
*/
deactivate: function() { deactivate: function() {
this.stopListening( this.frame ); this.stopListening( this.frame );
}, },
/**
* @since 3.9.0
*/
toolbar: function() { toolbar: function() {
var frame = this.frame, var frame = this.frame,
lastState = frame.lastState(), lastState = frame.lastState(),
@ -1368,6 +1529,11 @@
syncSelection: false syncSelection: false
}, media.controller.Library.prototype.defaults ), }, media.controller.Library.prototype.defaults ),
/**
* @since 3.9.0
*
* @param options
*/
initialize: function( options ) { initialize: function( options ) {
this.media = options.media; this.media = options.media;
this.type = options.type; this.type = options.type;
@ -1376,6 +1542,9 @@
media.controller.Library.prototype.initialize.apply( this, arguments ); media.controller.Library.prototype.initialize.apply( this, arguments );
}, },
/**
* @since 3.9.0
*/
activate: function() { activate: function() {
if ( media.frame.lastMime ) { if ( media.frame.lastMime ) {
this.set( 'library', media.query({ type: media.frame.lastMime }) ); this.set( 'library', media.query({ type: media.frame.lastMime }) );