Collection

Collections are ordered sets of models. As in Backbone, you can use collections to delegate events for a group of models, listen to the addition or removal of models from the set, and sync those sets with a server. Rendr provides two main additions over Backbone: the Collection Store and the ability to sync the collection in the same fashion on client or server.

See Backbone.Collection for all of the neat functions this object ships with.

api Collection.api

api is a configuration that allows you to change to a different API. These APIs are configured to the dataAdapterConfig. The configuration key for the host/protocol will automatically be set on the collection in the API-Proxy layer. This allows you to talk directly to third party sites without having to worry about cross-site scripting.

// DataAdapterConfig
dataAdapterConfig: {
  'github': {
    host: 'api.github.com',
    protocol: 'https'
  },
  'default': {
    host: 'my.site.com',
    protocol: 'https'
  }
}


// collection
module.exports = Base.extend({
  api: 'github',
  url: '/test'
});
// URL result: https://api.github.com/test?<params for collection>

If you don't provide an api it will automatically use the default key in the dataAdapterConfig.

constructor new Collection([models], [options])

The constructor creates a new instance of a Collection. To customize your constructor, create an initialize function on the child class, this function will be invoked once the parents constructor method is completed. See Backbone's documentation for more information.

The models parameter is an array of Models.

The options are the same as the standard Backbone.Collection, but in Rendr it also expects an app object. The Rendr App instance must be passed, in order to sync data to the API.

defaultParams Collection.defaultParams

An object of parameters that will be sent by default every time this collection makes a sync request. Individual parameters may be overwritten by setting them in this.params.

fetch Collection.fetch([options])

Accepts options with a data object to override parameters. Will invoke the Syncer's fetch method. If an options.data is not provided it will use the original params of the collection.

// override
Collection.fetch({
  data: {
    ids: [1, 2]
  }
})


// use previously defined params
Collection.fetch()

jsonKey Collection.jsonKey

jsonKey is the JSON root of the response from the API. An API response with a root key will automatically be parsed.

Collection.jsonKey = 'user';
// expected data format from the API
// this will then be parsed and set the models attribute to the array
{
  users: [{
    id: 1,
    name: 'Tester'
  }]
}

meta Collection.meta

The meta attribute is a special attribute on a Collection which allows you to store additional information about the Collection instance. For example, you can save pagination data in meta.

The meta information is part of the information that is stored in the object when you call Collection.toJSON.

params Collection.params

params stores the parameters that will be used to query for the models in the Collection. These parameters are used to identify Collections in the CollectionStore. When you call Collection.fetch, it will apply these parameters to the GET request to the API.

You can automatically set parameters to the Collection as the .params attribute by passing them in the options of the Collection's constructor.

parse Collection.parse([response], [modifyInstance])

Parse the data that is returned from an API fetch. If you set a jsonKey attribute on the collection, it will parse the objects as you would expect without having to override this function. This calls the parseModels method by default.

parseModels Collection.parseModels(response)

Loops over each Model in the Collection's response. Each Model object will then be returned by the Model's parse function.

If the jsonKey is set, Backbone can automatically parse Models returned from an API that are formatted using the root keys.

// user model has jsonKey set to 'user'
// API response
[{
  user: {
    id: 1,
    name: 'Han Solo'
  },
}, {
  user: {
    id: 2,
    name: 'Chewbacca'
  }
}]

// result
[{
  id: 1,
  name: 'Han Solo'
}, {
  id: 2,
  name: 'Chewbacca'
}]

store Collection.store()

Stores the collection in the Collection Store, and each of the models in the Model Store.

The lookup key is set to the collectionName:params: in the store, so that any set of parameters will only be requested from the server once. This function also automatically populates the model store, thus eliminating any additional requests for those models.