--- a/wp/wp-includes/js/media-models.js Tue Oct 22 16:11:46 2019 +0200
+++ b/wp/wp-includes/js/media-models.js Tue Dec 15 13:49:49 2020 +0100
@@ -116,7 +116,7 @@
* @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 ) {
@@ -185,13 +185,13 @@
*
* Used to order models within a collection - @see wp.media.model.Attachments.comparator().
*
- * @param {mixed} a 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} bc The fallback parameter to compare, b's cid.
- * @return {number} -1: a should come before b.
- * 0: a and b are of the same rank.
- * 1: b should come before a.
+ * @param {mixed} a 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} bc The fallback parameter to compare, b's cid.
+ * @return {number} -1: a should come before b.
+ * 0: a and b are of the same rank.
+ * 1: b should come before a.
*/
media.compare = function( a, b, ac, bc ) {
if ( _.isEqual( a, b ) ) {
@@ -237,7 +237,7 @@
* Scales a set of dimensions to fit within bounding dimensions.
*
* @param {Object} dimensions
- * @returns {Object}
+ * @return {Object}
*/
fit: function( dimensions ) {
var width = dimensions.width,
@@ -246,9 +246,11 @@
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
- // opposite side is the constraint.
+ /*
+ * Compare ratios between the two values to determine
+ * 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 ) ) {
@@ -280,10 +282,10 @@
* Truncates a string by injecting an ellipsis into the middle.
* Useful for filenames.
*
- * @param {String} string
- * @param {Number} [length=30]
- * @param {String} [replacement=…]
- * @returns {String} The string, unless length is greater than string.length.
+ * @param {string} string
+ * @param {number} [length=30]
+ * @param {string} [replacement=…]
+ * @return {string} The string, unless length is greater than string.length.
*/
truncate: function( string, length, replacement ) {
length = length || 30;
@@ -306,8 +308,8 @@
* wp.media.attachment
*
* @static
- * @param {String} id A string used to identify a model.
- * @returns {wp.media.model.Attachment}
+ * @param {string} id A string used to identify a model.
+ * @return {wp.media.model.Attachment}
*/
media.attachment = function( id ) {
return Attachment.get( id );
@@ -326,8 +328,8 @@
*
* Shorthand for creating a new Attachments Query.
*
- * @param {object} [props]
- * @returns {wp.media.model.Attachments}
+ * @param {Object} [props]
+ * @return {wp.media.model.Attachments}
*/
media.query = function( props ) {
return new Attachments( null, {
@@ -335,7 +337,7 @@
});
};
-// Clean up. Prevents mobile browsers caching
+// Clean up. Prevents mobile browsers caching.
$(window).on('unload', function(){
window.wp = null;
});
@@ -366,7 +368,7 @@
* @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
@@ -387,7 +389,7 @@
// 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();
}
@@ -448,8 +450,8 @@
* 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
- * to be set on the model.
+ * @return {Object} The modified response object, which is the attributes hash
+ * to be set on the model.
*/
parse: function( resp ) {
if ( ! resp ) {
@@ -466,12 +468,12 @@
*
* @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();
}
@@ -491,7 +493,7 @@
* @static
*
* @param {Object} attrs
- * @returns {wp.media.model.Attachment}
+ * @return {wp.media.model.Attachment}
*/
create: function( attrs ) {
var Attachments = wp.media.model.Attachments;
@@ -506,7 +508,7 @@
* @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;
@@ -611,7 +613,7 @@
* @access private
*
* @param {Backbone.Model} model
- * @param {Boolean} query
+ * @param {boolean} query
*/
_changeQuery: function( model, query ) {
if ( query ) {
@@ -657,9 +659,8 @@
return;
}
- // If no `Attachments` model is provided to source the searches
- // from, then automatically generate a source from the existing
- // models.
+ // If no `Attachments` model is provided to source the searches from,
+ // then automatically generate a source from the existing models.
if ( ! this._source ) {
this._source = new Attachments( this.models );
}
@@ -672,7 +673,7 @@
* Checks whether an attachment is valid.
*
* @param {wp.media.model.Attachment} attachment
- * @returns {Boolean}
+ * @return {boolean}
*/
validator: function( attachment ) {
@@ -696,7 +697,7 @@
*
* @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 ),
@@ -715,11 +716,11 @@
* 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 || {};
@@ -738,7 +739,7 @@
* 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 || [];
@@ -753,7 +754,7 @@
* 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 ) {
@@ -776,7 +777,7 @@
* @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,
@@ -792,7 +793,7 @@
*
* @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 );
@@ -802,7 +803,7 @@
* 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 ) {
@@ -817,6 +818,8 @@
this.reset( [], { silent: true } );
this.observe( attachments );
+ // Used for the search results.
+ this.trigger( 'attachments:received', this );
return this;
},
/**
@@ -837,8 +840,8 @@
* and forwards to its `more` method. This collection class doesn't have
* server persistence by itself.
*
- * @param {object} options
- * @returns {Promise}
+ * @param {Object} options
+ * @return {Promise}
*/
more: function( options ) {
var deferred = jQuery.Deferred(),
@@ -848,14 +851,19 @@
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
- // checking if we're still mirroring that collection when
- // the request resolves.
+ /*
+ * If we're mirroring another collection, forward `more` to
+ * the mirrored collection. Account for a race condition by
+ * 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();
@@ -868,19 +876,19 @@
* 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 ) ) {
@@ -924,16 +932,18 @@
* 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 }
- // mapping to pass to the request.
+ /*
+ * Removes any uploading attachments, updates each attachment's
+ * 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 ) {
@@ -963,9 +973,9 @@
* @param {Backbone.Model} a
* @param {Backbone.Model} b
* @param {Object} options
- * @returns {Number} -1 if the first model should come before the second,
- * 0 if they are of the same rank and
- * 1 if the first model should come after.
+ * @return {number} -1 if the first model should come before the second,
+ * 0 if they are of the same rank and
+ * 1 if the first model should come after.
*/
comparator: function( a, b, options ) {
var key = this.props.get('orderby'),
@@ -999,7 +1009,7 @@
*
* @this wp.media.model.Attachments
*
- * @returns {Boolean}
+ * @return {Boolean}
*/
search: function( attachment ) {
if ( ! this.props.get('search') ) {
@@ -1017,7 +1027,7 @@
*
* @this wp.media.model.Attachments
*
- * @returns {Boolean}
+ * @return {boolean}
*/
type: function( attachment ) {
var type = this.props.get('type'), atts = attachment.toJSON(), mime, found;
@@ -1044,7 +1054,7 @@
*
* @this wp.media.model.Attachments
*
- * @returns {Boolean}
+ * @return {boolean}
*/
uploadedTo: function( attachment ) {
var uploadedTo = this.props.get('uploadedTo');
@@ -1060,7 +1070,7 @@
*
* @this wp.media.model.Attachments
*
- * @returns {Boolean}
+ * @return {boolean}
*/
status: function( attachment ) {
var status = this.props.get('status');
@@ -1105,8 +1115,8 @@
*/
Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{
/**
- * @param {array} [models=[]] Array of initial models to populate the collection.
- * @param {object} [options={}]
+ * @param {Array} [models=[]] Array of initial models to populate the collection.
+ * @param {Object} [options={}]
*/
initialize: function( models, options ) {
var allowed;
@@ -1126,15 +1136,19 @@
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
- // item, then we can't guarantee the set is complete.
+ /*
+ * We want any items that can be placed before the last
+ * 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
- // changes that occurred after we created the query.
+ /*
+ * Handle the case where there are no items yet and
+ * 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;
@@ -1148,12 +1162,14 @@
return false;
};
- // 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
- // false positives in those queries.
+ /*
+ * 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
+ * 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 );
@@ -1163,7 +1179,7 @@
* 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;
@@ -1171,8 +1187,8 @@
/**
* Fetch more attachments from the server for the collection.
*
- * @param {object} [options={}]
- * @returns {Promise}
+ * @param {Object} [options={}]
+ * @return {Promise}
*/
more: function( options ) {
var query = this;
@@ -1199,10 +1215,10 @@
* 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;
@@ -1227,7 +1243,7 @@
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
@@ -1304,7 +1320,7 @@
* @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(){
/**
@@ -1314,7 +1330,7 @@
var queries = [];
/**
- * @returns {Query}
+ * @return {Query}
*/
return function( props, options ) {
var args = {},
@@ -1428,7 +1444,7 @@
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 );
@@ -1468,7 +1484,7 @@
return;
}
- // default to custom if there is a linkUrl
+ // Default to custom if there is a linkUrl.
type = 'custom';
if ( this.attachment ) {
@@ -1596,7 +1612,7 @@
*
* @param {Array} models
* @param {Object} options
- * @returns {wp.media.model.Attachment[]}
+ * @return {wp.media.model.Attachment[]}
*/
add: function( models, options ) {
if ( ! this.multiple ) {
@@ -1616,7 +1632,7 @@
* @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;