enmi-conf.org: comparison wp/wp-includes/js/media-models.js

Mercurial Mercurial > enmi-conf.org / comparison

summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help

wp/wp-includes/js/media-models.js

changeset 16	a86126ab1dd4
parent 9	177826044cd9
child 18	be944660c56a

equal deleted inserted replaced

-:3d4e9c994f10
+:a86126ab1dd4
 *
 * @alias wp.media
 * @memberOf wp
 * @namespace
 *
-* @param  {object} attributes The properties passed to the main media controller.
+* @param {Object} attributes The properties passed to the main media controller.
 * @return {wp.media.view.MediaFrame} A media workflow.
 */
 media = wp.media = function( attributes ) {
 	var MediaFrame = media.view.MediaFrame,
 		frame;
 /**
 * A basic equality comparator for Backbone models.
 *
 * Used to order models within a collection - @see wp.media.model.Attachments.comparator().
 *
-* @param  {mixed}  a  The primary parameter to compare.
+* @param {mixed}  a  The primary parameter to compare.
-* @param  {mixed}  b  The primary parameter to compare.
+* @param {mixed}  b  The primary parameter to compare.
-* @param  {string} ac The fallback parameter to compare, a's cid.
+* @param {string} ac The fallback parameter to compare, a's cid.
-* @param  {string} bc The fallback parameter to compare, b's cid.
+* @param {string} bc The fallback parameter to compare, b's cid.
-* @return {number}    -1: a should come before b.
+* @return {number} -1: a should come before b.
-*                      0: a and b are of the same rank.
+*                   0: a and b are of the same rank.
-*                      1: b should come before a.
+*                   1: b should come before a.
 */
 media.compare = function( a, b, ac, bc ) {
 	if ( _.isEqual( a, b ) ) {
 		return ac === bc ? 0 : (ac > bc ? -1 : 1);
 	} else {
 	/**
 	 * Scales a set of dimensions to fit within bounding dimensions.
 	 *
 	 * @param {Object} dimensions
-	 * @returns {Object}
+	 * @return {Object}
 	 */
 	fit: function( dimensions ) {
 		var width     = dimensions.width,
 			height    = dimensions.height,
 			maxWidth  = dimensions.maxWidth,
 			maxHeight = dimensions.maxHeight,
 			constraint;
-		// Compare ratios between the two values to determine which
+		/*
-		// max to constrain by. If a max value doesn't exist, then the
+		 * Compare ratios between the two values to determine
-		// opposite side is the constraint.
+		 * which max to constrain by. If a max value doesn't exist,
+		 * then the opposite side is the constraint.
+		 */
 		if ( ! _.isUndefined( maxWidth ) && ! _.isUndefined( maxHeight ) ) {
 			constraint = ( width / height > maxWidth / maxHeight ) ? 'width' : 'height';
 		} else if ( _.isUndefined( maxHeight ) ) {
 			constraint = 'width';
 		} else if (  _.isUndefined( maxWidth ) && height > maxHeight ) {
 	},
 	/**
 	 * Truncates a string by injecting an ellipsis into the middle.
 	 * Useful for filenames.
 	 *
-	 * @param {String} string
+	 * @param {string} string
-	 * @param {Number} [length=30]
+	 * @param {number} [length=30]
-	 * @param {String} [replacement=&hellip;]
+	 * @param {string} [replacement=&hellip;]
-	 * @returns {String} The string, unless length is greater than string.length.
+	 * @return {string} The string, unless length is greater than string.length.
 	 */
 	truncate: function( string, length, replacement ) {
 		length = length || 30;
 		replacement = replacement || '&hellip;';
 */
 /**
 * wp.media.attachment
 *
 * @static
-* @param {String} id A string used to identify a model.
+* @param {string} id A string used to identify a model.
-* @returns {wp.media.model.Attachment}
+* @return {wp.media.model.Attachment}
 */
 media.attachment = function( id ) {
 	return Attachment.get( id );
 };
 /**
 * wp.media.query
 *
 * Shorthand for creating a new Attachments Query.
 *
-* @param {object} [props]
+* @param {Object} [props]
-* @returns {wp.media.model.Attachments}
+* @return {wp.media.model.Attachments}
 */
 media.query = function( props ) {
 	return new Attachments( null, {
 		props: _.extend( _.defaults( props || {}, { orderby: 'date' } ), { query: true } )
 	});
 };
-// Clean up. Prevents mobile browsers caching
+// Clean up. Prevents mobile browsers caching.
 $(window).on('unload', function(){
 	window.wp = null;
 });
 	 *
 	 * @param {string} method
 	 * @param {wp.media.model.Attachment} model
 	 * @param {Object} [options={}]
 	 *
-	 * @returns {Promise}
+	 * @return {Promise}
 	 */
 	sync: function( method, model, options ) {
 		// If the attachment does not yet have an `id`, return an instantly
 		// rejected promise. Otherwise, all of our requests will fail.
 		if ( _.isUndefined( this.id ) ) {
 			});
 			return wp.media.ajax( options );
 		// Overload the `update` request so properties can be saved.
 		} else if ( 'update' === method ) {
-			// If we do not have the necessary nonce, fail immeditately.
+			// If we do not have the necessary nonce, fail immediately.
 			if ( ! this.get('nonces') || ! this.get('nonces').update ) {
 				return $.Deferred().rejectWith( this ).promise();
 			}
 			options = options || {};
 	},
 	/**
 	 * Convert date strings into Date objects.
 	 *
 	 * @param {Object} resp The raw response object, typically returned by fetch()
-	 * @returns {Object} The modified response object, which is the attributes hash
+	 * @return {Object} The modified response object, which is the attributes hash
-	 *    to be set on the model.
+	 *                  to be set on the model.
 	 */
 	parse: function( resp ) {
 		if ( ! resp ) {
 			return resp;
 		}
 	 * @param {Object} data The properties to be saved.
 	 * @param {Object} options Sync options. e.g. patch, wait, success, error.
 	 *
 	 * @this Backbone.Model
 	 *
-	 * @returns {Promise}
+	 * @return {Promise}
 	 */
 	saveCompat: function( data, options ) {
 		var model = this;
-		// If we do not have the necessary nonce, fail immeditately.
+		// If we do not have the necessary nonce, fail immediately.
 		if ( ! this.get('nonces') || ! this.get('nonces').update ) {
 			return $.Deferred().rejectWith( this ).promise();
 		}
 		return wp.media.post( 'save-attachment-compat', _.defaults({
 	 * Create a new model on the static 'all' attachments collection and return it.
 	 *
 	 * @static
 	 *
 	 * @param {Object} attrs
-	 * @returns {wp.media.model.Attachment}
+	 * @return {wp.media.model.Attachment}
 	 */
 	create: function( attrs ) {
 		var Attachments = wp.media.model.Attachments;
 		return Attachments.all.push( attrs );
 	},
 	 * it returns the specified attachment.
 	 *
 	 * @static
 	 * @param {string} id A string used to identify a model.
 	 * @param {Backbone.Model|undefined} attachment
-	 * @returns {wp.media.model.Attachment}
+	 * @return {wp.media.model.Attachment}
 	 */
 	get: _.memoize( function( id, attachment ) {
 		var Attachments = wp.media.model.Attachments;
 		return Attachments.all.push( attachment || { id: id } );
 	})
 	 * the `props` values, and sync the results to this collection.
 	 *
 	 * @access private
 	 *
 	 * @param {Backbone.Model} model
-	 * @param {Boolean} query
+	 * @param {boolean} query
 	 */
 	_changeQuery: function( model, query ) {
 		if ( query ) {
 			this.props.on( 'change', this._requery, this );
 			this._requery();
 		if ( ! changed ) {
 			return;
 		}
-		// If no `Attachments` model is provided to source the searches
+		// If no `Attachments` model is provided to source the searches from,
-		// from, then automatically generate a source from the existing
+		// then automatically generate a source from the existing models.
-		// models.
 		if ( ! this._source ) {
 			this._source = new Attachments( this.models );
 		}
 		this.reset( this._source.filter( this.validator, this ) );
 	validateDestroyed: false,
 	/**
 	 * Checks whether an attachment is valid.
 	 *
 	 * @param {wp.media.model.Attachment} attachment
-	 * @returns {Boolean}
+	 * @return {boolean}
 	 */
 	validator: function( attachment ) {
 		// Filter out contextually created attachments (e.g. headers, logos, etc.).
 		if (
 	/**
 	 * Add or remove an attachment to the collection depending on its validity.
 	 *
 	 * @param {wp.media.model.Attachment} attachment
 	 * @param {Object} options
-	 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
+	 * @return {wp.media.model.Attachments} Returns itself to allow chaining.
 	 */
 	validate: function( attachment, options ) {
 		var valid = this.validator( attachment ),
 			hasAttachment = !! this.get( attachment.cid );
 	/**
 	 * Add or remove all attachments from another collection depending on each one's validity.
 	 *
 	 * @param {wp.media.model.Attachments} attachments
-	 * @param {object} [options={}]
+	 * @param {Object} [options={}]
 	 *
 	 * @fires wp.media.model.Attachments#reset
 	 *
-	 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
+	 * @return {wp.media.model.Attachments} Returns itself to allow chaining.
 	 */
 	validateAll: function( attachments, options ) {
 		options = options || {};
 		_.each( attachments.models, function( attachment ) {
 	/**
 	 * Start observing another attachments collection change events
 	 * and replicate them on this collection.
 	 *
 	 * @param {wp.media.model.Attachments} The attachments collection to observe.
-	 * @returns {wp.media.model.Attachments} Returns itself to allow chaining.
+	 * @return {wp.media.model.Attachments} Returns itself to allow chaining.
 	 */
 	observe: function( attachments ) {
 		this.observers = this.observers || [];
 		this.observers.push( attachments );
 	},
 	/**
 	 * Stop replicating collection change events from another attachments collection.
 	 *
 	 * @param {wp.media.model.Attachments} The attachments collection to stop observing.
-	 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
+	 * @return {wp.media.model.Attachments} Returns itself to allow chaining.
 	 */
 	unobserve: function( attachments ) {
 		if ( attachments ) {
 			attachments.off( null, null, this );
 			this.observers = _.without( this.observers, attachments );
 	 *
 	 * @param {wp.media.model.Attachments} attachment
 	 * @param {wp.media.model.Attachments} attachments
 	 * @param {Object} options
 	 *
-	 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
+	 * @return {wp.media.model.Attachments} Returns itself to allow chaining.
 	 */
 	_validateHandler: function( attachment, attachments, options ) {
 		// If we're not mirroring this `attachments` collection,
 		// only retain the `silent` option.
 		options = attachments === this.mirroring ? options : {
 	/**
 	 * @access private
 	 *
 	 * @param {wp.media.model.Attachments} attachments
 	 * @param {Object} options
-	 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
+	 * @return {wp.media.model.Attachments} Returns itself to allow chaining.
 	 */
 	_validateAllHandler: function( attachments, options ) {
 		return this.validateAll( attachments, options );
 	},
 	/**
 	 * Start mirroring another attachments collection, clearing out any models already
 	 * in the collection.
 	 *
 	 * @param {wp.media.model.Attachments} The attachments collection to mirror.
-	 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
+	 * @return {wp.media.model.Attachments} Returns itself to allow chaining.
 	 */
 	mirror: function( attachments ) {
 		if ( this.mirroring && this.mirroring === attachments ) {
 			return this;
 		}
 		// Clear the collection silently. A `reset` event will be fired
 		// when `observe()` calls `validateAll()`.
 		this.reset( [], { silent: true } );
 		this.observe( attachments );
+		// Used for the search results.
+		this.trigger( 'attachments:received', this );
 		return this;
 	},
 	/**
 	 * Stop mirroring another attachments collection.
 	 */
 	 *
 	 * Only works if the collection is mirroring a Query Attachments collection,
 	 * and forwards to its `more` method. This collection class doesn't have
 	 * server persistence by itself.
 	 *
-	 * @param {object} options
+	 * @param {Object} options
-	 * @returns {Promise}
+	 * @return {Promise}
 	 */
 	more: function( options ) {
 		var deferred = jQuery.Deferred(),
 			mirroring = this.mirroring,
 			attachments = this;
 		if ( ! mirroring || ! mirroring.more ) {
 			return deferred.resolveWith( this ).promise();
 		}
-		// If we're mirroring another collection, forward `more` to
+		/*
-		// the mirrored collection. Account for a race condition by
+		 * If we're mirroring another collection, forward `more` to
-		// checking if we're still mirroring that collection when
+		 * the mirrored collection. Account for a race condition by
-		// the request resolves.
+		 * checking if we're still mirroring that collection when
+		 * the request resolves.
+		 */
 		mirroring.more( options ).done( function() {
 			if ( this === attachments.mirroring ) {
 				deferred.resolveWith( this );
 			}
+			// Used for the search results.
+			attachments.trigger( 'attachments:received', this );
 		});
 		return deferred.promise();
 	},
 	/**
 	 *
 	 * Only works if the collection is mirroring a Query Attachments collection,
 	 * and forwards to its `hasMore` method. This collection class doesn't have
 	 * server persistence by itself.
 	 *
-	 * @returns {boolean}
+	 * @return {boolean}
 	 */
 	hasMore: function() {
 		return this.mirroring ? this.mirroring.hasMore() : false;
 	},
 	/**
-	 * A custom AJAX-response parser.
+	 * A custom Ajax-response parser.
 	 *
 	 * See trac ticket #24753
 	 *
 	 * @param {Object|Array} resp The raw response Object/Array.
 	 * @param {Object} xhr
-	 * @returns {Array} The array of model attributes to be added to the collection
+	 * @return {Array} The array of model attributes to be added to the collection
 	 */
 	parse: function( resp, xhr ) {
 		if ( ! _.isArray( resp ) ) {
 			resp = [resp];
 		}
 	},
 	/**
 	 * If this collection is sorted by `menuOrder`, recalculates and saves
 	 * the menu order to the database.
 	 *
-	 * @returns {undefined|Promise}
+	 * @return {undefined|Promise}
 	 */
 	saveMenuOrder: function() {
 		if ( 'menuOrder' !== this.props.get('orderby') ) {
 			return;
 		}
-		// Removes any uploading attachments, updates each attachment's
+		/*
-		// menu order, and returns an object with an { id: menuOrder }
+		 * Removes any uploading attachments, updates each attachment's
-		// mapping to pass to the request.
+		 * menu order, and returns an object with an { id: menuOrder }
+		 * mapping to pass to the request.
+		 */
 		var attachments = this.chain().filter( function( attachment ) {
 			return ! _.isUndefined( attachment.id );
 		}).map( function( attachment, index ) {
 			// Indices start at 1.
 			index = index + 1;
 	 * and its subclasses. @see wp.media.model.Attachments._changeOrderby().
 	 *
 	 * @param {Backbone.Model} a
 	 * @param {Backbone.Model} b
 	 * @param {Object} options
-	 * @returns {Number} -1 if the first model should come before the second,
+	 * @return {number} -1 if the first model should come before the second,
-	 *    0 if they are of the same rank and
+	 *                   0 if they are of the same rank and
-	 *    1 if the first model should come after.
+	 *                   1 if the first model should come after.
 	 */
 	comparator: function( a, b, options ) {
 		var key   = this.props.get('orderby'),
 			order = this.props.get('order') || 'DESC',
 			ac    = a.cid,
 		 *
 		 * @param {wp.media.model.Attachment} attachment
 		 *
 		 * @this wp.media.model.Attachments
 		 *
-		 * @returns {Boolean}
+		 * @return {Boolean}
 		 */
 		search: function( attachment ) {
 			if ( ! this.props.get('search') ) {
 				return true;
 			}
 		 * @static
 		 * @param {wp.media.model.Attachment} attachment
 		 *
 		 * @this wp.media.model.Attachments
 		 *
-		 * @returns {Boolean}
+		 * @return {boolean}
 		 */
 		type: function( attachment ) {
 			var type = this.props.get('type'), atts = attachment.toJSON(), mime, found;
 			if ( ! type || ( _.isArray( type ) && ! type.length ) ) {
 		 * @static
 		 * @param {wp.media.model.Attachment} attachment
 		 *
 		 * @this wp.media.model.Attachments
 		 *
-		 * @returns {Boolean}
+		 * @return {boolean}
 		 */
 		uploadedTo: function( attachment ) {
 			var uploadedTo = this.props.get('uploadedTo');
 			if ( _.isUndefined( uploadedTo ) ) {
 				return true;
 		 * @static
 		 * @param {wp.media.model.Attachment} attachment
 		 *
 		 * @this wp.media.model.Attachments
 		 *
-		 * @returns {Boolean}
+		 * @return {boolean}
 		 */
 		status: function( attachment ) {
 			var status = this.props.get('status');
 			if ( _.isUndefined( status ) ) {
 				return true;
 * @param {object} [options.args]                Attachments query arguments.
 * @param {object} [options.args.posts_per_page]
 */
 Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{
 	/**
-	 * @param {array}  [models=[]]  Array of initial models to populate the collection.
+	 * @param {Array}  [models=[]]  Array of initial models to populate the collection.
-	 * @param {object} [options={}]
+	 * @param {Object} [options={}]
 	 */
 	initialize: function( models, options ) {
 		var allowed;
 		options = options || {};
 			if ( ! this.comparator ) {
 				return true;
 			}
-			// We want any items that can be placed before the last
+			/*
-			// item in the set. If we add any items after the last
+			 * We want any items that can be placed before the last
-			// item, then we can't guarantee the set is complete.
+			 * item in the set. If we add any items after the last
+			 * item, then we can't guarantee the set is complete.
+			 */
 			if ( this.length ) {
 				return 1 !== this.comparator( attachment, this.last(), { ties: true });
-			// Handle the case where there are no items yet and
+			/*
-			// we're sorting for recent items. In that case, we want
+			 * Handle the case where there are no items yet and
-			// changes that occurred after we created the query.
+			 * we're sorting for recent items. In that case, we want
+			 * changes that occurred after we created the query.
+			 */
 			} else if ( 'DESC' === order && ( 'date' === orderby || 'modified' === orderby ) ) {
 				return attachment.get( orderby ) >= this.created;
 			// If we're sorting by menu order and we have no items,
 			// accept any items that have the default menu order (0).
 			// Otherwise, we don't want any items yet.
 			return false;
 		};
-		// Observe the central `wp.Uploader.queue` collection to watch for
+		/*
-		// new matches for the query.
+		 * Observe the central `wp.Uploader.queue` collection to watch for
-		//
+		 * new matches for the query.
-		// Only observe when a limited number of query args are set. There
+		 *
-		// are no filters for other properties, so observing will result in
+		 * Only observe when a limited number of query args are set. There
-		// false positives in those queries.
+		 * are no filters for other properties, so observing will result in
+		 * false positives in those queries.
+		 */
 		allowed = [ 's', 'order', 'orderby', 'posts_per_page', 'post_mime_type', 'post_parent', 'author' ];
 		if ( wp.Uploader && _( this.args ).chain().keys().difference( allowed ).isEmpty().value() ) {
 			this.observe( wp.Uploader.queue );
 		}
 	},
 	/**
 	 * Whether there are more attachments that haven't been sync'd from the server
 	 * that match the collection's query.
 	 *
-	 * @returns {boolean}
+	 * @return {boolean}
 	 */
 	hasMore: function() {
 		return this._hasMore;
 	},
 	/**
 	 * Fetch more attachments from the server for the collection.
 	 *
-	 * @param   {object}  [options={}]
+	 * @param {Object} [options={}]
-	 * @returns {Promise}
+	 * @return {Promise}
 	 */
 	more: function( options ) {
 		var query = this;
 		// If there is already a request pending, return early with the Deferred object.
 	},
 	/**
 	 * Overrides Backbone.Collection.sync
 	 * Overrides wp.media.model.Attachments.sync
 	 *
-	 * @param {String} method
+	 * @param {string} method
 	 * @param {Backbone.Model} model
 	 * @param {Object} [options={}]
-	 * @returns {Promise}
+	 * @return {Promise}
 	 */
 	sync: function( method, model, options ) {
 		var args, fallback;
 		// Overload the read method so Attachment.fetch() functions correctly.
 			}
 			options.data.query = args;
 			return wp.media.ajax( options );
-		// Otherwise, fall back to Backbone.sync()
+		// Otherwise, fall back to `Backbone.sync()`.
 		} else {
 			/**
 			 * Call wp.media.model.Attachments.sync or Backbone.sync
 			 */
 			fallback = Attachments.prototype.sync ? Attachments.prototype : Backbone;
 	 * @param {Object} [props.post_parent]
 	 * @param {Object} [props.post_status]
 	 * @param {Object} [props.author]
 	 * @param {Object} [options]
 	 *
-	 * @returns {wp.media.model.Query} A new Attachments Query collection.
+	 * @return {wp.media.model.Query} A new Attachments Query collection.
 	 */
 	get: (function(){
 		/**
 		 * @static
 		 * @type Array
 		 */
 		var queries = [];
 		/**
-		 * @returns {Query}
+		 * @return {Query}
 		 */
 		return function( props, options ) {
 			var args     = {},
 				orderby  = Query.orderby,
 				defaults = Query.defaultProps,
 				this.dfd = this.attachment.fetch();
 			}
 			this.bindAttachmentListeners();
 		}
-		// keep url in sync with changes to the type of link
+		// Keep URL in sync with changes to the type of link.
 		this.on( 'change:link', this.updateLinkUrl, this );
 		this.on( 'change:size', this.updateSize, this );
 		this.setLinkTypeFromUrl();
 		this.setAspectRatio();
 		if ( ! linkUrl ) {
 			this.set( 'link', 'none' );
 			return;
 		}
-		// default to custom if there is a linkUrl
+		// Default to custom if there is a linkUrl.
 		type = 'custom';
 		if ( this.attachment ) {
 			if ( this.attachment.get( 'url' ) === linkUrl ) {
 				type = 'file';
 	 * If the workflow does not support multi-select, clear out the selection
 	 * before adding a new attachment to it.
 	 *
 	 * @param {Array} models
 	 * @param {Object} options
-	 * @returns {wp.media.model.Attachment[]}
+	 * @return {wp.media.model.Attachment[]}
 	 */
 	add: function( models, options ) {
 		if ( ! this.multiple ) {
 			this.remove( this.models );
 		}
 	 * @param {undefined|boolean|wp.media.model.Attachment} model
 	 *
 	 * @fires wp.media.model.Selection#selection:single
 	 * @fires wp.media.model.Selection#selection:unsingle
 	 *
-	 * @returns {Backbone.Model}
+	 * @return {Backbone.Model}
 	 */
 	single: function( model ) {
 		var previous = this._single;
 		// If a `model` is provided, use it as the single model.

enmi-conf.org