backbone.js

Collection

Syntax#

  • // New custom collection

var MyCollection = Backbone.Collection.extend(properties, [classProperties]);

  • // New collection instance

var collection = new Backbone.Collection([models], [options]);

Parameters#

Parameter Details
properties Instance properties.
classProperties Optional. Properties that exist and are shared with every collection instance of this type.
models Optional. The initial array of models (or objects). If this parameter is left out, the collection will be empty.
options Optional. Object which serves to configure the collection and is then passed to the initialize function.
## Remarks#
Collections are ordered sets of models. You can bind "change" events to be notified when any model in the collection has been modified, listen for "add" and "remove" events, fetch the collection from the server, and use a full suite of Underscore.js methods.

Any event that is triggered on a model in a collection will also be triggered on the collection directly, for convenience. This allows you to listen for changes to specific attributes in any model in a collection.

Create a custom collection

To create a new collection “class”:

var Books = Backbone.Collection.extend({
    // books will be sorted by title
    comparator: "title",

    initialize: function(models, options) {
        options = options || {};

        // (Optional) you can play with the models here
        _.each(models, function(model) {
            // do things with each model
        }, this);

        this.customProperty = options.property;
    },
});

All the properties are optional and are there only as a demonstration. A Backbone.Collection can be used as-is.

Then using it is as simple as:

var myBookArray = [
    { id: 1, title: "Programming frontend application with backbone" },
    { id: 2, title: "Backbone for dummies" },
];


var myLibrary = new Books(myBookArray, {
    property: "my custom property"
});


myLibrary.each(function(book){
    console.log(book.get('title'));
});

Will output:

Programming frontend application with backbone
Backbone for dummies

Fetching and rendering data from the server

We need to define a collection with a url property. This is the url to an API endpoint which should return a json formatted array.

var Books = Backbone.Collection.extend({
    url: "/api/book",
    comparator: "title",
});

Then, within a view, we’ll fetch and render asynchronously:

var LibraryView = Backbone.View.extend({
    // simple underscore template, you could use 
    // whatever you like (mustache, handlebar, etc.)
    template: _.template("<p><%= title %></p>"),

    initialize: function(options) {
        this.collection.fetch({
            context: this,
            success: this.render,
            error: this.onError
        });
    },

    // Remember that "render" should be idempotent.
    render: function() {
        this.$el.empty();
        this.addAll();

        // Always return "this" inside render to chain calls.
        return this;
    },

    addAll: function() {
        this.collection.each(this.addOne, this);
    },

    addOne: function(model) {
        this.$el.append(this.template(model.toJSON()));
    },

    onError: function(collection, response, options) {
        // handle errors however you want
    },
});

Simplest way to use this view:

var myLibrary = new LibraryView({
    el: "body",
    collection: new Books(),
});

Collection.url()

By default, the url property is not defined. Calling fetch() (while using the default Backbone.sync) will result in a GET request to the results of url.

var Users = Backbone.Collection.extend({

  url: '/api/users',
  
  // or
  
  url: function () {
    return '/api/users'
  }

});

var users = new Users();
users.fetch() // GET https://webroot/api/users

This modified text is an extract of the original Stack Overflow Documentation created by the contributors and released under CC BY-SA 3.0 This website is not affiliated with Stack Overflow