Backbone-relational.js

When developing any medium to large-scale web application, you often get to the point where an action by a user can cause a number of different models to change on the client and the server.

You can try to keep updating both sides of a relation manually for every action, and individually call save or fetch on each of the changed models to sync with the server, but that quickly turns into a tedious process and results in multiple requests.

Using Backbone-relational, we can configure relationships between our models, and sync the model and all of its related models with a single call to save, getAsync or fetch() after setting up a model's relations.

Backbone-relational is hosted on GitHub, and is available under the MIT license.

Thanks to Progressive Planning for allowing me the time to work on Backbone-relational!

Downloads & Dependencies (Right-click, and use "Save As")

Backbone-relational depends on Backbone.js (>= 1.2.1), which itself requires Underscore.js (> 1.7.0) and jQuery (> 1.7.0) or Zepto.

Introduction

Backbone-relational.js provides one-to-one, one-to-many and many-to-one relations between models for Backbone. To use relations, extend Backbone.RelationalModel (instead of a regular Backbone.Model) and define a relations property, containing an array of option objects. Each relation must define (at least) the type, key, and relatedModel. Available relation types are Backbone.HasOne and Backbone.HasMany.

Backbone-relational's main features include:

• Bidirectional relations, which notify related models of changes through events.
• Control how relations are serialized using the includeInJSON option.
• Automatically convert nested objects in a model's attributes into model instances (using the createModels option, which is true by default).
• Lazily retrieve a set of related models through the getAsync method.
• Determine the type of HasMany collections with collectionType.

You can also bind new events to a Backbone.RelationalModel for an:

• addition to a HasMany relation with add:<key>.
• removal from a HasMany relation with remove:<key>.
• reset of a HasMany relation with reset:<key>.
• changes to the contents of a HasMany or HasOne relations with change: <key>.

Installation

Backbone-relational depends on Backbone.js (and thus on Underscore.js). Include Backbone-relational right after Backbone and Underscore:

<script type="text/javascript" src="./js/underscore.js"></script>
<script type="text/javascript" src="./js/backbone.js"></script>
<script type="text/javascript" src="./js/backbone-relational.js"></script>

Note for CoffeeScript users: due to the way the extends keyword is implemented in CoffeeScript, you may have to make an extra call to setup for your models. See the setup documentation for details.

Backbone.RelationalModel

When using Backbone-relational, each model defining (or receiving) relations must extend Backbone.RelationalModel in order to function. Backbone.RelationalModel introduces a couple of new methods, events and properties. It's important to know which are properties, which are methods of an instance, and which operate on the type itself. These three categories are detailed below.

Properties can be defined when extending Backbone.RelationalModel, or a subclass thereof.

• relations
• subModelTypes
• subModelTypeAttribute

Instance methods operate on an instance of a type.

• getAsync
• getIdsToFetch
• getRelation
• getRelations
• set
• toJSON

Static methods operate on the type itself, as opposed to operating on model instances.

• setup
• build
• findOrCreate
• find
• findModel

Properties

relationsrelation[]

A Backbone.RelationalModel may contain an array of relation definitions. Each relation supports a number of options, of which key and type are mandatory. You'll also need to specifiy relatedModel if you want to reference another model. A relation could look like the following:

Zoo = Backbone.RelationalModel.extend({
	relations: [{
		type: Backbone.HasMany,
		key: 'animals',
		relatedModel: 'Animal',
		collectionType: 'AnimalCollection',
		reverseRelation: {
			key: 'livesIn',
			includeInJSON: 'id'
			// 'relatedModel' is automatically set to 'Zoo'; the 'relationType' to 'HasOne'.
		}
	}]
});

Animal = Backbone.RelationalModel.extend({
	urlRoot: '/animal/'
});

AnimalCollection = Backbone.Collection.extend({
	model: Animal
});

// We've now created a fully managed relation. When you add or remove model from `zoo.animals`,
// or update `animal.livesIn`, the other side of the relation will automatically be updated.
var artis = new Zoo( { name: 'Artis' } );
var lion = new Animal( { species: 'Lion', livesIn: artis } );

// `animals` in `artis` now contains `lion`
alert( artis.get( 'animals' ).pluck( 'species' ) );

var amersfoort = new Zoo( { name: 'Dierenpark Amersfoort', animals: [ lion ] } );

// `lion` now livesIn `amersfoort`, and `animals` in `artis` no longer contains `lion`
alert( lion.get( 'livesIn' ).get( 'name' ) + ', ' + artis.get( 'animals' ).length );

Person = Backbone.RelationalModel.extend({
	relations: [{
		type: 'HasMany',
		key: 'jobs',
		relatedModel: 'Job',
		reverseRelation: {
			key: 'person'
		}
	}]
});

// A link object between 'Person' and 'Company'
Job = Backbone.RelationalModel.extend({
	defaults: {
		'startDate': null,
		'endDate': null
	}
});

Company = Backbone.RelationalModel.extend({
	relations: [{
		type: 'HasMany',
		key: 'employees',
		relatedModel: 'Job',
		reverseRelation: {
			key: 'company'
		}
	}]
});

var Shop = Backbone.RelationalModel.extend({
	relations: [
		{
			type: Backbone.HasMany,
			key: 'customers',
			relatedModel: 'Customer',
			autoFetch: true
		},
		{
			type: Backbone.HasOne,
			key: 'address',
			relatedModel: 'Address',
			autoFetch: {
				success: function( model, response ) {
					//...
				},
				error: function( model, response ) {
					//...
				}
			}
		}
	]
});

var FarmAnimal = Animal.extend();

// This `Farm` is confused, like legacy stuff can be. It wants its data back on a completely
// different key than it supplies it on. We want to use a different one in our app as well.
var Farm = Backbone.RelationalModel.extend({
	relations: [{
		type: Backbone.HasMany,
		key: 'animals',
		keySource: 'livestock',
		keyDestination: 'pets',
		relatedModel: FarmAnimal,
		reverseRelation: {
			key: 'farm',
			includeInJSON: 'name'
		}
	}]
});

// Create a `Farm`; parse `species`, add to `animals`, output goes to `pets`.
var farm = new Farm( { name: 'Old MacDonald', livestock: [ { species: 'Sheep' } ] } );
farm.get( 'animals' ).add( { species: 'Cow' } );
alert( JSON.stringify( farm.toJSON(), null, 4 ) );

Mammal = Animal.extend({
	subModelTypes: {
		'primate': 'Primate',
		'carnivore': 'Carnivore'
	}
});

Primate = Mammal.extend();
Carnivore = Mammal.extend();

MammalCollection = AnimalCollection.extend({
	model: Mammal
});

// Create a collection that contains a 'Primate' and a 'Carnivore'.
var mammals = new MammalCollection([
	{ id: 3, species: 'chimp', type: 'primate' },
	{ id: 5, species: 'panther', type: 'carnivore' }
]);

var chimp = mammals.get( 3 );

alert( 'chimp is an animal? ' + ( chimp instanceof Animal ) + '\n' +
	'chimp is a carnivore? ' + ( chimp instanceof Carnivore ) + '\n' +
	'chimp is a primate? ' + ( chimp instanceof Primate ) );

Instance methods

Static methods

class Animal extends Backbone.RelationalModel
    urlRoot: "/animal"

class Mammal extends Animal
    subModelTypes:
        "primate": "Primate"
        "carnivore": "Carnivore"

    relations: [
        # More relations
    ]

Mammal.setup()

class Primate extends Mammal

class Carnivore extends Mammal

chimp = Mammal.build( { id: 3, species: "chimp", type: "primate" } )

var zoo = new Zoo( { id: 1, name: 'Artis', animals: [
	{ species: 'Giraffe' },
	{ species: 'Camel' }
] } );

alert( JSON.stringify( zoo.toJSON(), null, 4 ) );

Zoo.findModel = function( attributes ) {
	// Try to find an instance of 'this' model type in the store
	var model = Backbone.Relational.store.find( this, attributes );

	if ( !model && _.isObject( attributes ) ) {
		var coll = Backbone.Relational.store.getCollection( this );

		model = coll.find( function( m ) {
			return m.species === attributes.species;
		});
	}

	return model;
};

Backbone.Relation

Each relation definition on a model is used to create in instance of a Backbone.Relation; either a Backbone.HasOne or a Backbone.HasMany.

Backbone.HasOne

Defines a HasOne relation. When defining a reverseRelation, the default type will be HasMany. However, this can also be set to HasOne to define a one-to-one relation.

Backbone.HasMany

Defines a HasMany relation. When defining a reverseRelation, the type will be HasOne.

Backbone.Store

Backbone.Store is a global model cache. Per application, one instance is created (much like Backbone.History), which is accessible as Backbone.Relational.store.

addModelScopeBackbone.Relational.store.addModelScope(scope<object>)

Add a namespace on which models and collections are defined. This is especially useful when working in an environment without a shared global scope (like window is in a browser), where you'll need to tell the store where your models are defined, so it can resolve them to create and maintain relations.

removeModelScopeBackbone.Relational.store.removeModelScope()

Remove a scope. This allows you to remove a scope you added previously, or to remove the default 'global' scope (window in the browser) scope to prevent Backbone-relational from resolving objects on it.

resetBackbone.Relational.store.reset()

Reset the store to its original state. This will disable relations for all models created up to this point, remove added model scopes, and removed all internal store collections.

unregisterBackbone.Relational.store.unregister(type<Backbone.RelationalModel|Backbone.RelationalModel.constructor|Backbone.Collection>)

Unregister a single model or a collection. Unregistering a model will remove a model from any relations it's involved in. Internally, unregister is called when a model has been destroyed. It can also be called explicitly to on models you don't want Backbone-relational to consider for relations anymore, for example to free up models used as (temporary) search results.

Examples

A tutorial by antoviaque, and the accompanying git repository.

A basic working example to get you started:

var paul = new Person({
	id: 'person-1',
	name: 'Paul',
	user: { id: 'user-1', login: 'dude', email: 'me@gmail.com' }
});

// A User object is automatically created from the JSON; so 'login' returns 'dude'.
paul.get('user').get('login');

var ourHouse = new House({
	id: 'house-1',
	location: 'in the middle of the street',
	occupants: ['person-1', 'person-2', 'person-5']
});

// 'ourHouse.occupants' is turned into a Backbone.Collection of Persons.
// The first person in 'ourHouse.occupants' will point to 'paul'.
ourHouse.get('occupants').at(0); // === paul

// If a collection is created from a HasMany relation, it contains a reference
// back to the originator of the relation
ourHouse.get('occupants').livesIn; // === ourHouse

// The `occupants` relation on 'House' has been defined as a HasMany, with a reverse relation
// to `livesIn` on 'Person'. So, 'paul.livesIn' will automatically point back to 'ourHouse'.
paul.get('livesIn'); // === ourHouse

// You can control which relations get serialized to JSON, using the 'includeInJSON'
// property on a Relation. Also, each object will only get serialized once to prevent loops.
alert( JSON.stringify( paul.get('user').toJSON(), null, '\t' ) );

// Load occupants 'person-2' and 'person-5', which don't exist yet, from the server
ourHouse.getAsync( 'occupants' );

// Use the `add` and `remove` events to listen for additions/removals on a HasMany relation.
// Here, we listen for changes to `ourHouse.occupants`.
ourHouse
	.on( 'add:occupants', function( model, coll ) {
		console.log( 'add %o', model );
		// Do something. Create a View?
	})
	.on( 'remove:occupants', function( model, coll ) {
		console.log( 'remove %o', model );
		// Do somehting. Destroy a View?
	});

// Use the 'update' event to listen for changes on a HasOne relation (like 'Person.livesIn').
paul.on( 'change:livesIn', function( model, attr ) {
	console.log( 'change `livesIn` to %o', attr );
});

// Modifying either side of a bi-directional relation updates the other side automatically.
// Take `paul` out or `ourHouse`; this triggers `remove:occupants` on `ourHouse`,
// and `change:livesIn` on `paul`
ourHouse.get( 'occupants' ).remove( paul );

alert( 'paul.livesIn=' + paul.get( 'livesIn' ) );

// Move into `theirHouse`; triggers 'add:occupants' on ourHouse, and 'change:livesIn' on paul
theirHouse = new House( { id: 'house-2' } );
paul.set( { 'livesIn': theirHouse } );

alert( 'theirHouse.occupants=' + theirHouse.get( 'occupants' ).pluck( 'name' ) );

This is achieved using the following relations and models:

House = Backbone.RelationalModel.extend({
	// The 'relations' property, on the House's prototype. Initialized separately for each
	// instance of House. Each relation must define (as a minimum) the 'type', 'key' and
	// 'relatedModel'. Options include 'includeInJSON', 'createModels' and 'reverseRelation'.
	relations: [
		{
			type: Backbone.HasMany, // Use the type, or the string 'HasOne' or 'HasMany'.
			key: 'occupants',
			relatedModel: 'Person',
			includeInJSON: Backbone.Model.prototype.idAttribute,
			collectionType: 'PersonCollection',
			reverseRelation: {
				key: 'livesIn'
			}
		}
	]
});

Person = Backbone.RelationalModel.extend({
	relations: [
		{ // Create a (recursive) one-to-one relationship
			type: Backbone.HasOne,
			key: 'user',
			relatedModel: 'User',
			reverseRelation: {
				type: Backbone.HasOne,
				key: 'person'
			}
		}
	],

	initialize: function() {
		// do whatever you want :)
	}
});

PersonCollection = Backbone.Collection.extend({
	url: function( models ) {
		// Logic to create a url for the whole collection, or a set of models.
		// See the tests, or Backbone-tastypie, for an example.
		return '/person/' + ( models ? 'set/' + _.pluck( models, 'id' ).join(';') + '/' : '' );
	}
});

User = Backbone.RelationalModel.extend();

Change Log

Master (future) – diff – download

0.10.0 (19 August 2015) – diff – download

• 84fae6c Fix ordering problems in relations
• 0731ff3 Backbone 1.2.1 compatible (add _removeModels override)

0.9.0 (25 October 2014) – diff – download

• 42b158d Add getIdsToFetch to Backbone.RelationalModel.
• b7e7123 getAsync (the successor of fetchRelated) now return a single promise, instead of an array of request objects.
• #467: Improve lazy loading implemenatation. Add getAsync to Backbone.RelationalModel, which always return a single promise that resolves with the attribute's content, and remove fetchRelated.

0.8.8 (1 April 2014) – diff – download

• #411: Don't add models without an id to the store.
• #419: Proper return values for single models on collection methods for Backbone 1.1.0
• 4113c69 `Backbone.Relational.store.unregister` now also accepts a collection or a model type
• #427: Fix firing explicit change events
• #215 Add direct support for AMD, CommonJS, require, etc.

0.8.7 (17 January 2014) – diff – download

• 8371089: Change return types for Collection methods to match Backbone 1.1.0
• #376: Include ids of unregistered models (not fetched or otherwise) in toJSON
• 8371089: Add findModel.

0.8.6 (16 August 2013) – diff – download

• #322: Remove keySource after a set as well.
• #345: Add find, a shortcut to findOrCreate with create: false
• #345: Add lodash compatibility (doesn't have an explicit findWhere).
• #349: Event ordering: maintain the originally intended order when process gets called more than once.
• #362: Add support for deep subModelType hierarchies.
• #380: Fix pop on an empty collection.
• #370: relations can now be a property or a function.
• 7f1dc51: relatedModel and collectionType can now be defined as a function as well.

0.8.5 (10 April 2013) – diff – download

• Supports Backbone 1.0.0
• #191: if includeInJSON is equal to the model's idAttribute, "missing" models will be included in the JSON to avoid data loss.
• #201: add Backbone.Store.removeModelScope method
• #273: improve merging of relations between super/subModels.
• #295: check (and error on) duplicate ids when explicitly setting the idAttribute.
• #320: use merge: true by default on Collection.reset.

0.8.0 5 March 2013 – diff – download

• General performance improvements, refactored HasMany.onChange to eliminate unnecessary events.
• Implemented the add, merge and remove options on Collection.add when working with RelationalModels. This also works when using set to change the key on nested relations.
• The update option on findOrCreate has been renamed to merge, since its behavior corresponds with merge on Collection.add (and not with update on Collection.reset).
• The update:<key> event has been removed, in favor of handling everything using "standard" change:<key> events.
• findOrCreate now takes a parse option, analogous to the Backbone.Model constructor. It defaults to false.
• Added a parse option to relations.

0.7.1 17 Januari 2013 – diff – download

• Compatible with Backbone >= 0.9.10
• Implemented the autoFetch property for relations.
• Added the update option to findOrCreate.

0.7.0 18 December 2012 – diff – download

• Compatible with Backbone >= 0.9.9
• #180: no longer allow multiple instances of RelationalModels with the same type, and the same id.

0.6.0 02 August 2012 – diff – download

• #60: keySource option added to relations.
• keyDestination option added to relations.
• collectionOptions option added to relations.
• Added support for super/sub models.
• Added Backbone.Store.addModelScope.

0.5.0 17 February 2012 – diff – download

• Update nested models properly on Collection.add.
• collectionKey options added to relations.
• Support new Backbone syntax for set (with separate key, value arguments).
• Initialize reverseRelations on definition, instead of on creation of the first model.

0.4.0 23 July 2011 – diff – download

• update<key> event added
• Override Backbone.Collection._add and Backbone.Collection._remove so relations update properly.
• Queue change and change<key> events, so they won't fire before relations are updated.
• Added the Backbone.RelationalModel.updateRelations method.

First commit 11 April 2011 – commit – download

The original version of Backbone-relational! This already contained much of the basics: HasOne and HasMany relations (including reverseRelation), Backbone.RelationalModel and Backbone.Store.

Under the Hood

The model Store

Each Backbone.RelationalModel registers itself with Backbone.Relational.Store upon creation, and is removed from the store when destroyed. When creating or updating an attribute that is a key in a relation, removed related objects are notified of their removal, and new related objects are looked up in the Store.

Backbone-relational only allows the existence of one model instance for each model type id. This check is there to enforce there will only be one version of a model with a certain id at any given time (which is also the reason for the existence of Backbone.Relational.Store). This is necessary to enforce consistency and integrity of relations.

If multiple versions were allowed, inadvertently manipulating or performing a save or destroy on another version of that model (which is still around on the client, and can for example still be bound to one or more views in your application, either on purpose or inadvertently) would save its state to the server, killing its relations, and the server response would set the same (incorrect) data on the 'current' version of the model on the client. By then, you'd be in trouble.

Therefore, Backbone-relational simply does not allow this situation to occur. This is much safer than putting the burden on the developer to always make sure every older version of a model is completely decoupled from every other part of your application. It might be annoying to get an error every now and then, and sometimes inconvenient to have to use the factory method findOrCreate, but it's much better than subtle bugs that can lead to major data loss later on in the life cycle of your application.

Event queuing

Most of Backbone's default events are queued by Backbone-relational. This can complicate debugging since it 'breaks' the call stack, but is a necessary part of the abstraction offered by it.

The event queuing kicks in every time (nested) relations need to be updated as the result of calling a Backbone method that modifies a model's attributes: on creation, and on set, unset, and clear.

The basic problem is that when manipulating relations, you only want the events to fire once ALL relations have been updated; also those on models one, two, or more relations away. For example, when you have an event listener on add, you want to be able to use the model you receive as the first argument and its relations fully instead of getting raw JS objects:

var p = new Person( { id: 'p1', name: 'Larry Page' } );

p.on( 'add:jobs', function( job ) {
	// Here, you want the correct person and company to be set on job, instead of plain js.
	alert( job.get( 'person' ).get( 'name' ) + ' @ ' + job.get( 'company' ).get( 'name' ) );
});

p.get( 'jobs' ).add( { company: { name: 'Google' }, person: p.id } );

To achieve this, Backbone's events are prevented from firing immediately when add is called, but are delayed until the all (nested) relations have reached a stable state again. Events are then fired at the first available opportunity; as soon as the last model updating its relations unblocks the Backbone.Relational.eventQueue.