Question

Revised Question

the collection.reset method vs the collection.add method. Both take a list of models as input. However, reset returns on object like this when the single “reset” event is emitted.

{d,
_byCid: Object,
_byId: Object,
_callbacks: Object,
length: 3,
models: Array[3],
__proto__: x}

The add method, however, returns a simple array, which is seen above in the models:Array[n] object. It’s easy to then do something like what you see in the addRender method in my sample code below. However, when attempting to do the same thing, extra work has to be done to get at and process that same list of models.

The question to be answered: Why do these methods (add and reset) return two different kinds of objects when they do similar things? Add, add a list of models. Reset, nuke your existing collection and replace it with a list of models. What use is returning this from the reset trigger when models is what is returned from the add trigger. What good (an example please) is returning the collection object vs just the models?

—original question below—

I am learning how to use backbone.js and have been experimenting with collections. I’ve discovered it’s easy to add a lot of models to a collection by calling foo.add() where foo is a collection. I have discovered though that doing foo.reset() doesn’t take the same input as I would expect it to. EG, reset a collection with a new list of models or a hash, even according to the backbonejs documentation:

Adding and removing models one at a time is all well and good, but
sometimes you have so many models to change that you’d rather just
update the collection in bulk. Use reset to replace a collection with
a new list of models (or attribute hashes)

The key word there is list. I can send a list of models to add() and it works great. However, to do the same thing with reset, takes a different template to process that data because it gets sent different to the template. I created a jsfiddle to demonstrate:

http://jsfiddle.net/pLytF/2/

What I find frustrating is that I think reset() should behave exactly like add() does, but it doesn’t seem to and I can’t think of a good reason why it wouldn’t. Am I going about this wrong?

Update
I believe I’ve begun to answer my own question. In the source of backbone.js, at line 745 within the reset method, you’ll find:

if (!options.silent) this.trigger('reset', this, options);

And at line 631, you’ll see this in the add method:

model.trigger('add', model, this, options);

This first is from the reset method, the second is from the add method. In the case of reset, “this” is passed and it holds a different structure than what add passes. Add passes the individual model, whereas, reset passes an object that has a property that points to an array of all of the models. This explains what I saw in my jsfiddle. I’m not sure this is the behavior that is actually described in the documentation though. Hmm

Answer 1

Not sure what exactly your question is.

Post Edit

The object passed in the reset event is the Collection itself.

If you want to operate on the models in that collection, you can use get them through collection.models. You get access to all of the underscore-inherited methods on a Collection like each, map, filter, find.

Your code for handling the reset event might look something like:

resetRender: function(collection) {
  collection.each(function(model){
      this.addRender(model);
  });
  return this;
}

Original

Add adds a model to an existing collection of models, preserving any model already in the collection. Reset replaces the current set of models with the models or objects being passed into the reset, it does not preserve any existing models in the collection.

Add triggers an ‘add’ event for each model added.

Reset triggers a single ‘reset’ for the entire set.

They exist to do entirely different things.

Reset is generally used to bulk-load a collection with a set of data – for instance if you’ve delivered a bunch of bootstrapped data with your initial page load as javascript variables, and you want to populate a collection with that data. Reset is also used to populate a collection after fetching, unless the {add: true} option is specified.

Imagine the user story:

Given a collection that contains models A, B, C.

I want the collection to now contain the models X, Y, Z

Not using reset, you would have to (in pseudocode)

while collection.length
  collection.pop()
collection.add([X,Y,Z])

Using reset, you instead just do:

collection.reset([X,Y,Z])

The first triggers 6 events, the second triggers 1.

Reset is simply one more tool in the box for doing what needs doing.