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