enmi-conf.org: comparison wp/wp-includes/js/wp-api.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/wp-api.js

changeset 16	a86126ab1dd4
parent 9	177826044cd9
child 18	be944660c56a

equal deleted inserted replaced

-:3d4e9c994f10
+:a86126ab1dd4
 	wp.api.utils.parseISO8601 = function( date ) {
 		var timestamp, struct, i, k,
 			minutesOffset = 0,
 			numericKeys = [ 1, 4, 5, 6, 7, 10, 11 ];
-		// ES5 §15.9.4.2 states that the string should attempt to be parsed as a Date Time String Format string
+		/*
-		// before falling back to any implementation-specific date parsing, so that’s what we do, even if native
+		 * ES5 §15.9.4.2 states that the string should attempt to be parsed as a Date Time String Format string
-		// implementations could be faster.
+		 * before falling back to any implementation-specific date parsing, so that’s what we do, even if native
+		 * implementations could be faster.
+		 */
 		//              1 YYYY                2 MM       3 DD           4 HH    5 mm       6 ss        7 msec        8 Z 9 ±    10 tzHH    11 tzmm
 		if ( ( struct = /^(\d{4}|[+\-]\d{6})(?:-(\d{2})(?:-(\d{2}))?)?(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{3}))?)?(?:(Z)|([+\-])(\d{2})(?::(\d{2}))?)?)?$/.exec( date ) ) ) {
 			// Avoid NaN timestamps caused by “undefined” values being passed to Date.UTC.
 			for ( i = 0; ( k = numericKeys[i] ); ++i ) {
 	/**
 	 * Extract a route part based on negative index.
 	 *
 	 * @param {string}   route          The endpoint route.
-	 * @param {int}      part           The number of parts from the end of the route to retrieve. Default 1.
+	 * @param {number}   part           The number of parts from the end of the route to retrieve. Default 1.
 	 *                                  Example route `/a/b/c`: part 1 is `c`, part 2 is `b`, part 3 is `a`.
 	 * @param {string}  [versionString] Version string, defaults to `wp.api.versionString`.
 	 * @param {boolean} [reverse]       Whether to reverse the order when extracting the route part. Optional, default false.
 	 */
 	wp.api.utils.extractRoutePart = function( route, part, versionString, reverse ) {
 	};
 	/**
 	 * Add args and options to a model prototype from a route's endpoints.
 	 *
-	 * @param {array}  routeEndpoints Array of route endpoints.
+	 * @param {Array}  routeEndpoints Array of route endpoints.
 	 * @param {Object} modelInstance  An instance of the model (or collection)
 	 *                                to add the args to.
 	 */
 	wp.api.utils.decorateFromRoute = function( routeEndpoints, modelInstance ) {
 		_.each( routeEndpoints, function( routeEndpoint ) {
 			// Add post and edit endpoints as model args.
 			if ( _.includes( routeEndpoint.methods, 'POST' ) || _.includes( routeEndpoint.methods, 'PUT' ) ) {
-				// Add any non empty args, merging them into the args object.
+				// Add any non-empty args, merging them into the args object.
 				if ( ! _.isEmpty( routeEndpoint.args ) ) {
 					// Set as default if no args yet.
 					if ( _.isEmpty( modelInstance.prototype.args ) ) {
 						modelInstance.prototype.args = routeEndpoint.args;
 			} else {
 				// Add GET method as model options.
 				if ( _.includes( routeEndpoint.methods, 'GET' ) ) {
-					// Add any non empty args, merging them into the defaults object.
+					// Add any non-empty args, merging them into the defaults object.
 					if ( ! _.isEmpty( routeEndpoint.args ) ) {
 						// Set as default if no defaults yet.
 						if ( _.isEmpty( modelInstance.prototype.options ) ) {
 							modelInstance.prototype.options = routeEndpoint.args;
 				 *                        or 'date_modified_gmt'. Optional, defaults to 'date'.
 				 */
 				setDate: function( date, field ) {
 					var theField = field || 'date';
-					// Don't alter non parsable date fields.
+					// Don't alter non-parsable date fields.
 					if ( _.indexOf( parseableDates, theField ) < 0 ) {
 						return false;
 					}
 					this.set( theField, date.toISOString() );
 				 */
 				getDate: function( field ) {
 					var theField   = field || 'date',
 						theISODate = this.get( theField );
-					// Only get date fields and non null values.
+					// Only get date fields and non-null values.
 					if ( _.indexOf( parseableDates, theField ) < 0 || _.isNull( theISODate ) ) {
 						return false;
 					}
 					return new Date( wp.api.utils.parseISO8601( theISODate ) );
 			},
 			/**
 			 * Build a helper function to retrieve related model.
 			 *
-			 * @param  {string} parentModel      The parent model.
+			 * @param {string} parentModel      The parent model.
-			 * @param  {int}    modelId          The model ID if the object to request
+			 * @param {number} modelId          The model ID if the object to request
-			 * @param  {string} modelName        The model name to use when constructing the model.
+			 * @param {string} modelName        The model name to use when constructing the model.
-			 * @param  {string} embedSourcePoint Where to check the embedds object for _embed data.
+			 * @param {string} embedSourcePoint Where to check the embedds object for _embed data.
-			 * @param  {string} embedCheckField  Which model field to check to see if the model has data.
+			 * @param {string} embedCheckField  Which model field to check to see if the model has data.
 			 *
 			 * @return {Deferred.promise}        A promise which resolves to the constructed model.
 			 */
 			buildModelGetter = function( parentModel, modelId, modelName, embedSourcePoint, embedCheckField ) {
 				var getModel, embeddeds, attributes, deferred;
 			},
 			/**
 			 * Build a helper to retrieve a collection.
 			 *
-			 * @param  {string} parentModel      The parent model.
+			 * @param {string} parentModel      The parent model.
-			 * @param  {string} collectionName   The name to use when constructing the collection.
+			 * @param {string} collectionName   The name to use when constructing the collection.
-			 * @param  {string} embedSourcePoint Where to check the embedds object for _embed data.
+			 * @param {string} embedSourcePoint Where to check the embedds object for _embed data.
-			 * @param  {string} embedIndex       An addiitonal optional index for the _embed data.
+			 * @param {string} embedIndex       An addiitonal optional index for the _embed data.
 			 *
-			 * @return {Deferred.promise}        A promise which resolves to the constructed collection.
+			 * @return {Deferred.promise} A promise which resolves to the constructed collection.
 			 */
 			buildCollectionGetter = function( parentModel, collectionName, embedSourcePoint, embedIndex ) {
 				/**
 				 * Returns a promise that resolves to the requested collection
 				 *
 					deferred        = jQuery.Deferred();
 				postId    = parentModel.get( 'id' );
 				embeddeds = parentModel.get( '_embedded' ) || {};
-				// Verify that we have a valid post id.
+				// Verify that we have a valid post ID.
 				if ( ! _.isNumber( postId ) || 0 === postId ) {
 					deferred.reject();
 					return deferred;
 				}
 				/**
 				 * Get meta by key for a post.
 				 *
 				 * @param {string} key The meta key.
 				 *
-				 * @return {object} The post meta value.
+				 * @return {Object} The post meta value.
 				 */
 				getMeta: function( key ) {
 					var metas = this.get( 'meta' );
 					return metas[ key ];
 				},
 				/**
 				 * Get all meta key/values for a post.
 				 *
-				 * @return {object} The post metas, as a key value pair object.
+				 * @return {Object} The post metas, as a key value pair object.
 				 */
 				getMetas: function() {
 					return this.get( 'meta' );
 				},
 				/**
 				 * Set a group of meta key/values for a post.
 				 *
-				 * @param {object} meta The post meta to set, as key/value pairs.
+				 * @param {Object} meta The post meta to set, as key/value pairs.
 				 */
 				setMetas: function( meta ) {
 					var metas = this.get( 'meta' );
 					_.extend( metas, meta );
 					this.set( 'meta', metas );
 				/**
 				 * Set a single meta value for a post, by key.
 				 *
 				 * @param {string} key   The meta key.
-				 * @param {object} value The meta value.
+				 * @param {Object} value The meta value.
 				 */
 				setMeta: function( key, value ) {
 					var metas = this.get( 'meta' );
 					metas[ key ] = value;
 					this.set( 'meta', metas );
 				/**
 				 * Set the tags for a post.
 				 *
 				 * Accepts an array of tag slugs, or a Tags collection.
 				 *
-				 * @param {array|Backbone.Collection} tags The tags to set on the post.
+				 * @param {Array|Backbone.Collection} tags The tags to set on the post.
 				 *
 				 */
 				setTags: function( tags ) {
 					var allTags, newTag,
 						self = this,
 				/**
 				 * Set the tags for a post.
 				 *
 				 * Accepts a Tags collection.
 				 *
-				 * @param {array|Backbone.Collection} tags The tags to set on the post.
+				 * @param {Array|Backbone.Collection} tags The tags to set on the post.
 				 *
 				 */
 				setTagsWithCollection: function( tags ) {
-					// Pluck out the category ids.
+					// Pluck out the category IDs.
 					this.set( 'tags', tags.pluck( 'id' ) );
 					return this.save();
 				}
 			},
 				/**
 				 * Set the categories for a post.
 				 *
 				 * Accepts an array of category slugs, or a Categories collection.
 				 *
-				 * @param {array|Backbone.Collection} categories The categories to set on the post.
+				 * @param {Array|Backbone.Collection} categories The categories to set on the post.
 				 *
 				 */
 				setCategories: function( categories ) {
 					var allCategories, newCategory,
 						self = this,
 				/**
 				 * Set the categories for a post.
 				 *
 				 * Accepts Categories collection.
 				 *
-				 * @param {array|Backbone.Collection} categories The categories to set on the post.
+				 * @param {Array|Backbone.Collection} categories The categories to set on the post.
 				 *
 				 */
 				setCategoriesWithCollection: function( categories ) {
-					// Pluck out the category ids.
+					// Pluck out the category IDs.
 					this.set( 'categories', categories.pluck( 'id' ) );
 					return this.save();
 				}
 			},
 			 * Set nonce header before every Backbone sync.
 			 *
 			 * @param {string} method.
 			 * @param {Backbone.Model} model.
 			 * @param {{beforeSend}, *} options.
-			 * @returns {*}.
+			 * @return {*}.
 			 */
 			sync: function( method, model, options ) {
 				var beforeSend;
 				options = options || {};
 				}
 				if ( _.isFunction( model.nonce ) && ! _.isEmpty( model.nonce() ) ) {
 					beforeSend = options.beforeSend;
-					// @todo enable option for jsonp endpoints
+					// @todo Enable option for jsonp endpoints.
 					// options.dataType = 'jsonp';
 					// Include the nonce with requests.
 					options.beforeSend = function( xhr ) {
 						xhr.setRequestHeader( 'X-WP-Nonce', model.nonce() );
 			 * Set nonce header before every Backbone sync.
 			 *
 			 * @param {string} method.
 			 * @param {Backbone.Model} model.
 			 * @param {{success}, *} options.
-			 * @returns {*}.
+			 * @return {*}.
 			 */
 			sync: function( method, model, options ) {
 				var beforeSend, success,
 					self = this;
 			/**
 			 * Fetches the next page of objects if a new page exists.
 			 *
 			 * @param {data: {page}} options.
-			 * @returns {*}.
+			 * @return {*}.
 			 */
 			more: function( options ) {
 				options = options || {};
 				options.data = options.data || {};
 			},
 			/**
 			 * Returns true if there are more pages of objects available.
 			 *
-			 * @returns null|boolean.
+			 * @return {null|boolean}
 			 */
 			hasMore: function() {
 				if ( null === this.state.totalPages ||
 					 null === this.state.totalObjects ||
 					 null === this.state.currentPage ) {
 						// Include the array of route endpoints for easy reference.
 						endpoints: modelRoute.route.endpoints
 					} );
 				} else {
-					// This is a model without a parent in its route
+					// This is a model without a parent in its route.
 					modelClassName = wp.api.utils.capitalizeAndCamelCaseDashes( routeName );
 					modelClassName = mapping.models[ modelClassName ] || modelClassName;
 					loadingObjects.models[ modelClassName ] = wp.api.WPApiBaseModel.extend( {
-						// Function that returns a constructed url based on the id.
+						// Function that returns a constructed url based on the ID.
 						url: function() {
 							var url = routeModel.get( 'apiRoot' ) +
 								routeModel.get( 'versionString' ) +
 								( ( 'me' === routeName ) ? 'users/me' : routeName );
 	wp.api.endpoints = new Backbone.Collection();
 	/**
 	 * Initialize the wp-api, optionally passing the API root.
 	 *
-	 * @param {object} [args]
+	 * @param {Object} [args]
 	 * @param {string} [args.nonce] The nonce. Optional, defaults to wpApiSettings.nonce.
 	 * @param {string} [args.apiRoot] The api root. Optional, defaults to wpApiSettings.root.
 	 * @param {string} [args.versionString] The version string. Optional, defaults to wpApiSettings.root.
-	 * @param {object} [args.schema] The schema. Optional, will be fetched from API if not provided.
+	 * @param {Object} [args.schema] The schema. Optional, will be fetched from API if not provided.
 	 */
 	wp.api.init = function( args ) {
 		var endpoint, attributes = {}, deferred, promise;
 		args                      = args || {};
 			attributes.schema = wpApiSettings.schema;
 		}
 		if ( ! initializedDeferreds[ attributes.apiRoot + attributes.versionString ] ) {
-			// Look for an existing copy of this endpoint
+			// Look for an existing copy of this endpoint.
 			endpoint = wp.api.endpoints.findWhere( { 'apiRoot': attributes.apiRoot, 'versionString': attributes.versionString } );
 			if ( ! endpoint ) {
 				endpoint = new Endpoint( attributes );
 			}
 			deferred = jQuery.Deferred();

enmi-conf.org