model-list-debug.js revision d561b35ed5a1899db0e91d791e606b951a3c1180
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassProvides an API for managing an ordered list of Model instances.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove@submodule model-list
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan GroveProvides an API for managing an ordered list of Model instances.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan GroveIn addition to providing convenient `add`, `create`, `reset`, and `remove`
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassmethods for managing the models in the list, ModelLists are also bubble targets
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassfor events on the model instances they contain. This means, for example, that
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassyou can add several models to a list, and then subscribe to the `*:change` event
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glasson the list to be notified whenever any model in the list changes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav GlassModelLists also maintain sort order efficiently as models are added and removed,
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassbased on a custom `comparator` function you may define (if no comparator is
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassdefined, models are sorted in insertion order).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass@class ModelList
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove@extends Base
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass@uses ArrayList
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Fired when a model is added to the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Listen to the `on` phase of this event to be notified before a model is
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass added to the list. Calling `e.preventDefault()` during the `on` phase will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass prevent the model from being added.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Listen to the `after` phase of this event to be notified after a model has
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass been added to the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model} model The model being added.
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove @param {Number} index The index at which the model will be added.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @preventable _defAddFn
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove Fired when an error occurs, such as when an attempt is made to add a
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove duplicate model to the list, or when a sync layer response can't be parsed.
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove @event error
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove @param {Any} error Error message, object, or exception generated by the
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove error. Calling `toString()` on this should result in a meaningful error
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove @param {String} src Source of the error. May be one of the following (or any
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove custom error source defined by a ModelList subclass):
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove * `add`: Error while adding a model (probably because it's already in the
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove list and can't be added again). The model in question will be provided
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove as the `model` property on the event facade.
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove * `parse`: An error parsing a JSON response. The response in question will
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove be provided as the `response` property on the event facade.
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove * `remove`: Error while removing a model (probably because it isn't in the
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove list and can't be removed). The model in question will be provided as
d3e7704f3fd45efa522b537b83189cd8a511e67fRyan Grove the `model` property on the event facade.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove Fired when the list is completely reset via the `reset()` method or sorted
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove via the `sort()` method.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Listen to the `on` phase of this event to be notified before the list is
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove reset. Calling `e.preventDefault()` during the `on` phase will prevent
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove the list from being reset.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Listen to the `after` phase of this event to be notified after the list has
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @event reset
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {Model[]} models Array of the list's new models after the reset.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {String} src Source of the event. May be either `'reset'` or
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @preventable _defResetFn
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Fired when a model is removed from the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Listen to the `on` phase of this event to be notified before a model is
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass removed from the list. Calling `e.preventDefault()` during the `on` phase
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass will prevent the model from being removed.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Listen to the `after` phase of this event to be notified after a model has
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass been removed from the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @event remove
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model} model The model being removed.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {int} index The index of the model being removed.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @preventable _defRemoveFn
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass ModelList.superclass.constructor.apply(this, arguments);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Public Properties ----------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass The `Model` class or subclass of the models in this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass This property is `null` by default, and is intended to be overridden in a
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass subclass or specified as a config property at instantiation time. It will be
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass used to create model instances automatically based on attribute hashes
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove passed to the `add()`, `create()`, and `reset()` methods.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @property model
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @default `null`
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Lifecycle Methods ----------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass var model = this.model = config.model || this.model;
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove this.publish(EVT_ADD, {defaultFn: this._defAddFn});
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove this.publish(EVT_RESET, {defaultFn: this._defResetFn});
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove this.publish(EVT_REMOVE, {defaultFn: this._defRemoveFn});
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Y.log('No model class specified.', 'warn', 'model-list');
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass destructor: function () {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Public Methods -------------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Adds the specified model or array of models to this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Add a single model instance.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass list.add(new Model({foo: 'bar'}));
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Add a single model, creating a new instance automatically.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass list.add({foo: 'bar'});
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Add multiple models, creating new instances automatically.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass {foo: 'bar'},
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass {baz: 'quux'}
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model|Model[]|Object|Object[]} models Models to add. May be existing
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass model instances or hashes of model attributes, in which case new model
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass instances will be created from the hashes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [options] Data to be mixed into the event facade of the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `add` event(s) for the added models.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Boolean} [options.silent=false] If `true`, no `add` event(s) will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Model|Model[]} Added model or array of added models.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Define this method to provide a function that takes a model as a parameter
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass and returns a value by which that model should be sorted relative to other
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass models in this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass By default, no comparator is defined, meaning that models will not be sorted
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass (they'll be stored in the order they're added).
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass var list = new Y.ModelList({model: Y.Model});
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass list.comparator = function (model) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return model.get('id'); // Sort models by id.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method comparator
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model} model Model being sorted.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Number|String} Value by which the model should be sorted relative
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass to other models in this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // comparator is not defined by default
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Creates or updates the specified model on the server, then adds it to this
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass list if the server indicates success.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method create
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model|Object} model Model to create. May be an existing model
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass instance or a hash of model attributes, in which case a new model instance
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass will be created from the hash.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [options] Options to be passed to the model's `sync()` and
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `set()` methods and mixed into the `add` event when the model is added
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass to the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Boolean} [options.silent=false] If `true`, no `add` event(s) will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {callback} [callback] Called when the sync operation finishes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Error} callback.err If an error occurred, this parameter will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass contain the error. If the sync operation succeeded, _err_ will be
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {mixed} callback.response The server's response.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Model} Created model.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Allow callback as second arg.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove If _name_ refers to an attribute on this ModelList instance, returns the
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove value of that attribute. Otherwise, returns an array containing the values
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove of the specified attribute from each model in this list.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @param {String} name Attribute name or object property path.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @return {Any|Array} Attribute value or array of attribute values.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @see Model.get()
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove If _name_ refers to an attribute on this ModelList instance, returns the
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove HTML-escaped value of that attribute. Otherwise, returns an array containing
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove the HTML-escaped values of the specified attribute from each model in this
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove The values are escaped using `Escape.html()`.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @method getAsHTML
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @param {String} name Attribute name or object property path.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @return {String|String[]} HTML-escaped value or array of HTML-escaped
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @see Model.getAsHTML()
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove return Y.Escape.html(AttrProto.get.apply(this, arguments));
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove If _name_ refers to an attribute on this ModelList instance, returns the
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove URL-encoded value of that attribute. Otherwise, returns an array containing
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove the URL-encoded values of the specified attribute from each model in this
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove The values are encoded using the native `encodeURIComponent()` function.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @method getAsURL
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @param {String} name Attribute name or object property path.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @return {String|String[]} URL-encoded value or array of URL-encoded values.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove @see Model.getAsURL()
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove return encodeURIComponent(AttrProto.get.apply(this, arguments));
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Returns the model with the specified _clientId_, or `null` if not found.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method getByClientId
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {String} clientId Client id.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Model} Model, or `null` if not found.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Returns the model with the specified _id_, or `null` if not found.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Note that models aren't expected to have an id until they're saved, so if
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass you're working with unsaved models, it may be safer to call
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `getByClientId()`.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method getById
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @param {String|Number} id Model id.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Model} Model, or `null` if not found.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Calls the named method on every model in the list. Any arguments provided
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass after _name_ will be passed on to the invoked method.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method invoke
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {String} name Name of the method to call on each model.
a7bf61fe73568ec8f3615c238acbe69d5986e21dRyan Grove @param {Any} [args*] Zero or more arguments to pass to the invoked method.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Array} Array of return values, indexed according to the index of
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass the model on which the method was called.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass var args = [this._items, name].concat(YArray(arguments, 1, true));
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Returns the model at the specified _index_.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method item
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @param {Number} index Index of the model to fetch.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Model} The model at the specified index, or `undefined` if there
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass isn't a model there.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // item() is inherited from ArrayList.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Loads this list of models from the server.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass This method delegates to the `sync()` method to perform the actual load
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass operation, which is an asynchronous action. Specify a _callback_ function to
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass be notified of success or failure.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove If the load operation succeeds, a `reset` event will be fired.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method load
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [options] Options to be passed to `sync()` and to
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove `reset()` when adding the loaded models. It's up to the custom sync
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass implementation to determine what options it supports or requires, if any.
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @param {Function} [callback] Called when the sync operation finishes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Error} callback.err If an error occurred, this parameter will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass contain the error. If the sync operation succeeded, _err_ will be
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @param {Any} callback.response The server's response. This value will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass be passed to the `parse()` method, which is expected to parse it and
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return an array of model attribute hashes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Allow callback as only arg.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass this.sync('read', options, function (err, response) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return this;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Executes the specified function on each model in this list and returns an
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass array of the function's collected return values.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Function} fn Function to execute on each model.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model} fn.model Current model being iterated.
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @param {Number} fn.index Index of the current model in the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model[]} fn.models Array of models being iterated.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [thisObj] `this` object to use when calling _fn_.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Array} Array of return values from _fn_.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Called to parse the _response_ when the list is loaded from the server.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass This method receives a server _response_ and is expected to return an array
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass of model attribute hashes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass The default implementation assumes that _response_ is either an array of
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass attribute hashes or a JSON string that can be parsed into an array of
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass attribute hashes. If _response_ is a JSON string and either `Y.JSON` or the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass native `JSON` object are available, it will be parsed automatically. If a
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass parse error occurs, an `error` event will be fired and the model will not be
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass You may override this method to implement custom parsing logic if necessary.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method parse
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @param {Any} response Server response.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Object[]} Array of model attribute hashes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass } catch (ex) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return null;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return response || [];
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove Removes the specified model or array of models from this list.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @method remove
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {Model|Model[]} models Models to remove.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {Object} [options] Data to be mixed into the event facade of the
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove `remove` event(s) for the removed models.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {Boolean} [options.silent=false] If `true`, no `remove` event(s)
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove will be fired.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @return {Model|Model[]} Removed model or array of removed models.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Completely replaces all models in the list with those specified, and fires a
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove single `reset` event.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove Use `reset` when you want to add or remove a large number of items at once
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass without firing `add` or `remove` events for each one.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @method reset
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {Model[]|Object[]} [models] Models to add. May be existing model
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass instances or hashes of model attributes, in which case new model instances
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove will be created from the hashes. Calling `reset()` without passing in any
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove models will clear the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [options] Data to be mixed into the event facade of the
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove `reset` event.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {Boolean} [options.silent=false] If `true`, no `reset` event will
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove // Sort the models in the facade before firing the reset event.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return this;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Forcibly re-sorts the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Usually it shouldn't be necessary to call this method since the list
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass maintains its sort order when items are added and removed, but if you change
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass the `comparator` function after items are already in the list, you'll need
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method sort
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [options] Data to be mixed into the event facade of the
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove `reset` event.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {Boolean} [options.silent=false] If `true`, no `reset` event will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return this;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return this;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Override this method to provide a custom persistence implementation for this
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass list. The default method just calls the callback without actually doing
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass This method is called internally by `load()`.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method sync
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {String} action Sync action to perform. May be one of the following:
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * `create`: Store a list of newly-created models for the first time.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * `delete`: Delete a list of existing models.
fbb8b3b8c5a0aad2d7eb5f62e4507a20696adb43Ryan Grove * `read` : Load a list of existing models.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * `update`: Update a list of existing models.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Currently, model lists only make use of the `read` action, but other
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass actions may be used in future versions.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [options] Sync options. It's up to the custom sync
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass implementation to determine what options it supports or requires, if any.
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @param {Function} [callback] Called when the sync operation finishes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Error} callback.err If an error occurred, this parameter will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass contain the error. If the sync operation succeeded, _err_ will be
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @param {Any} [callback.response] The server's response. This value will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass be passed to the `parse()` method, which is expected to parse it and
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return an array of model attribute hashes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass sync: function (/* action, options, callback */) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Returns an array containing the models in this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method toArray
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Array} Array containing the models in this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass toArray: function () {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Returns an array containing attribute hashes for each model in this list,
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass suitable for being passed to `Y.JSON.stringify()`.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Under the hood, this method calls `toJSON()` on each model in the list and
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass pushes the results into an array.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method toJSON
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Object[]} Array of model attribute hashes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @see Model.toJSON()
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass toJSON: function () {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Protected Methods ----------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Adds the specified _model_ if it isn't already in this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _add
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model|Object} model Model or object to add.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [options] Data to be mixed into the event facade of the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `add` event for the added model.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Boolean} [options.silent=false] If `true`, no `add` event will be
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Model} The added model.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass options.silent ? this._defAddFn(facade) : this.fire(EVT_ADD, facade);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Adds this list as a bubble target for the specified model's events.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _attachList
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model} model Model to attach to this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Attach this list and make it a bubble target for the model.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Clears all internal state and the internal list of models, returning this
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass list to an empty state. Automatically detaches all models in the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _clear
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass _clear: function () {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Removes this list as a bubble target for the specified model's events.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _detachList
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model} model Model to detach.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Returns the index at which the given _model_ should be inserted to maintain
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass the sort order of the list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _findIndex
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model} model The model being inserted.
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove @return {Number} Index at which the model should be inserted.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass if (!comparator || !items.length) { return items.length; }
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // Perform an iterative binary search to determine the correct position
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // based on the return value of the `comparator` function.
05077064e34396660f0e2b4e2ce06098b0edf077Ryan Grove middle = (min + max) >> 1; // Divide by two and discard remainder.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Removes the specified _model_ if it's in this list.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _remove
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Model} model Model to remove.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Object} [options] Data to be mixed into the event facade of the
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass `remove` event for the removed model.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {Boolean} [options.silent=false] If `true`, no `remove` event will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @return {Model} Removed model.
05077064e34396660f0e2b4e2ce06098b0edf077Ryan Grove Array sort function used by `sort()` to re-sort the models in the list.
05077064e34396660f0e2b4e2ce06098b0edf077Ryan Grove @method _sort
05077064e34396660f0e2b4e2ce06098b0edf077Ryan Grove @param {Model} a First model to compare.
05077064e34396660f0e2b4e2ce06098b0edf077Ryan Grove @param {Model} b Second model to compare.
05077064e34396660f0e2b4e2ce06098b0edf077Ryan Grove @return {Number} `-1` if _a_ is less than _b_, `0` if equal, `1` if greater.
05077064e34396660f0e2b4e2ce06098b0edf077Ryan Grove _sort: function (a, b) {
05077064e34396660f0e2b4e2ce06098b0edf077Ryan Grove return aValue < bValue ? -1 : (aValue > bValue ? 1 : 0);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Event Handlers -------------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Updates the model maps when a model's `id` attribute changes.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _afterIdChange
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {EventFacade} e
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass _afterIdChange: function (e) {
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove Lang.isValue(e.prevVal) && delete this._idMap[e.prevVal];
d561b35ed5a1899db0e91d791e606b951a3c1180Ryan Grove Lang.isValue(e.newVal) && (this._idMap[e.newVal] = e.target);
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Default Event Handlers -----------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Default event handler for `add` events.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _defAddFn
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {EventFacade} e
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass _defAddFn: function (e) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Default event handler for `remove` events.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @method _defRemoveFn
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass @param {EventFacade} e
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass _defRemoveFn: function (e) {
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove Default event handler for `reset` events.
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @method _defResetFn
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove @param {EventFacade} e
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove _defResetFn: function (e) {
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove // When fired from the `sort` method, we don't need to clear the list or
213abf076aeae2f3b6b834155b0a5b7dbae72d7cRyan Grove // add any models, since the existing models are sorted in place.
abe38d7e07e114761db3feb3c22ef22fce3ecccaRyan Grove}, '@VERSION@' ,{requires:['array-extras', 'array-invoke', 'arraylist', 'base-build', 'escape', 'json-parse', 'model']});