backbone-relational-rails 0.5.0 → 0.6.0

data/README.md

@@ -18,7 +18,7 @@ Add the following directive to your Javascript manifest file (application.js):
 
 ## Versioning
 
-backbone-relational-rails 0.5.0 == Backbone-relational 0.5.0
+backbone-relational-rails 0.6.0 == Backbone-relational 0.6.0
 
 Every attempt is made to mirror the currently shipping Backbone-relational version number wherever possible.
 The major, minor, and patch version numbers will always represent the Backbone-relational version. Should a gem

data/lib/backbone-relational-rails/version.rb

@@ -1,7 +1,7 @@
 module Backbone
   module Relational
     module Rails
-      VERSION = "0.5.0"
+      VERSION = "0.6.0"
     end
   end
 end

data/vendor/assets/javascripts/backbone-relational.js

@@ -1,12 +1,14 @@
-/**	
- * Backbone-relational.js 0.5.0
+/**
+ * Backbone-relational.js 0.6.0
  * (c) 2011 Paul Uithol
  * 
- * Backbone-relational may be freely distributed under the MIT license.
+ * Backbone-relational may be freely distributed under the MIT license; see the accompanying LICENSE.txt.
  * For details and documentation: https://github.com/PaulUithol/Backbone-relational.
- * Depends on (as in, compeletely useless without) Backbone: https://github.com/documentcloud/backbone.
+ * Depends on Backbone (and thus on Underscore as well): https://github.com/documentcloud/backbone.
  */
 ( function( undefined ) {
+	"use strict";
+	
 	/**
 	 * CommonJS shim
 	 **/
@@ -17,15 +19,15 @@
 		exports = module.exports = Backbone;
 	}
 	else {
-		var _ = window._;
+		_ = window._;
 		Backbone = window.Backbone;
 		exports = window;
 	}
-	
+
 	Backbone.Relational = {
 		showWarnings: true
 	};
-	
+
 	/**
 	 * Semaphore mixin; can be used as both binary and counting.
 	 **/
@@ -114,37 +116,87 @@
 	 * Backbone.Store keeps track of all created (and destruction of) Backbone.RelationalModel.
 	 * Handles lookup for relations.
 	 */
-	Backbone.Store =  function() {
+	Backbone.Store = function() {
 		this._collections = [];
 		this._reverseRelations = [];
+		this._subModels = [];
+		this._modelScopes = [ exports ];
 	};
 	_.extend( Backbone.Store.prototype, Backbone.Events, {
-		_collections: null,
-		_reverseRelations: null,
+		addModelScope: function( scope ) {
+			this._modelScopes.push( scope );
+		},
+
+		/**
+		 * Add a set of subModelTypes to the store, that can be used to resolve the '_superModel'
+		 * for a model later in 'setupSuperModel'.
+		 *
+		 * @param {Backbone.RelationalModel} subModelTypes
+		 * @param {Backbone.RelationalModel} superModelType
+		 */
+		addSubModels: function( subModelTypes, superModelType ) {
+			this._subModels.push({
+				'superModelType': superModelType,
+				'subModels': subModelTypes
+			});
+		},
+
+		/**
+		 * Check if the given modelType is registered as another model's subModel. If so, add it to the super model's
+		 * '_subModels', and set the modelType's '_superModel', '_subModelTypeName', and '_subModelTypeAttribute'.
+		 *
+		 * @param {Backbone.RelationalModel} modelType
+		 */
+		setupSuperModel: function( modelType ) {
+			_.find( this._subModels, function( subModelDef ) {
+				return _.find( subModelDef.subModels, function( subModelTypeName, typeValue ) {
+					var subModelType = this.getObjectByName( subModelTypeName );
+
+					if ( modelType === subModelType ) {
+						// Set 'modelType' as a child of the found superModel
+						subModelDef.superModelType._subModels[ typeValue ] = modelType;
+
+						// Set '_superModel', '_subModelTypeValue', and '_subModelTypeAttribute' on 'modelType'.
+						modelType._superModel = subModelDef.superModelType;
+						modelType._subModelTypeValue = typeValue;
+						modelType._subModelTypeAttribute = subModelDef.superModelType.prototype.subModelTypeAttribute;
+						return true;
+					}
+				}, this );
+			}, this );
+		},
 		
 		/**
 		 * Add a reverse relation. Is added to the 'relations' property on model's prototype, and to
 		 * existing instances of 'model' in the store as well.
-		 * @param {object} relation
+		 * @param {Object} relation
 		 * @param {Backbone.RelationalModel} relation.model
 		 * @param {String} relation.type
 		 * @param {String} relation.key
-		 * @param {String|object} relation.relatedModel
+		 * @param {String|Object} relation.relatedModel
 		 */
 		addReverseRelation: function( relation ) {
 			var exists = _.any( this._reverseRelations, function( rel ) {
-				return _.all( relation, function( val, key ) {
-					return val === rel[ key ];
+					return _.all( relation, function( val, key ) {
+							return val === rel[ key ];
+						});
 				});
-			});
 			
 			if ( !exists && relation.model && relation.type ) {
 				this._reverseRelations.push( relation );
 				
-				if ( !relation.model.prototype.relations ) {
-					relation.model.prototype.relations = [];
-				}
-				relation.model.prototype.relations.push( relation );
+				var addRelation = function( model, relation ) {
+					if ( !model.prototype.relations ) {
+						model.prototype.relations = [];
+					}
+					model.prototype.relations.push( relation );
+					
+					_.each( model._subModels, function( subModel ) {
+							addRelation( subModel, relation );
+						}, this );
+				};
+				
+				addRelation( relation.model, relation );
 				
 				this.retroFitRelation( relation );
 			}
@@ -152,11 +204,15 @@
 		
 		/**
 		 * Add a 'relation' to all existing instances of 'relation.model' in the store
-		 * @param {object} relation
+		 * @param {Object} relation
 		 */
 		retroFitRelation: function( relation ) {
 			var coll = this.getCollection( relation.model );
 			coll.each( function( model ) {
+				if ( !( model instanceof relation.model ) ) {
+					return;
+				}
+
 				new relation.type( model, relation );
 			}, this);
 		},
@@ -167,13 +223,21 @@
 		 * @return {Backbone.Collection} A collection if found (or applicable for 'model'), or null
 		 */
 		getCollection: function( model ) {
-			var coll =  _.detect( this._collections, function( c ) {
-					// Check if model is the type itself (a ref to the constructor), or is of type c.model
-					return model === c.model || model.constructor === c.model;
+			if ( model instanceof Backbone.RelationalModel ) {
+				model = model.constructor;
+			}
+			
+			var rootModel = model;
+			while ( rootModel._superModel ) {
+				rootModel = rootModel._superModel;
+			}
+			
+			var coll = _.detect( this._collections, function( c ) {
+					return c.model === rootModel;
 				});
 			
 			if ( !coll ) {
-				coll = this._createCollection( model );
+				coll = this._createCollection( rootModel );
 			}
 			
 			return coll;
@@ -182,25 +246,35 @@
 		/**
 		 * Find a type on the global object by name. Splits name on dots.
 		 * @param {String} name
-		 * @return {object}
+		 * @return {Object}
 		 */
 		getObjectByName: function( name ) {
-			var type = _.reduce( name.split( '.' ), function( memo, val ) {
-				return memo[ val ];
-			}, exports);
-			return type !== exports ? type: null;
+			var parts = name.split( '.' ),
+				type = null;
+
+			_.find( this._modelScopes, function( scope ) {
+				type = _.reduce( parts, function( memo, val ) {
+					return memo[ val ];
+				}, scope );
+
+				if ( type && type !== scope ) {
+					return true;
+				}
+			}, this );
+
+			return type;
 		},
 		
 		_createCollection: function( type ) {
 			var coll;
 			
-			// If 'type' is an instance, take it's constructor
+			// If 'type' is an instance, take its constructor
 			if ( type instanceof Backbone.RelationalModel ) {
 				type = type.constructor;
 			}
 			
 			// Type should inherit from Backbone.RelationalModel.
-			if ( type.prototype instanceof Backbone.RelationalModel.prototype.constructor ) {
+			if ( type.prototype instanceof Backbone.RelationalModel ) {
 				coll = new Backbone.Collection();
 				coll.model = type;
 				
@@ -209,10 +283,53 @@
 			
 			return coll;
 		},
-		
-		find: function( type, id ) {
+
+		/**
+		 * Find the attribute that is to be used as the `id` on a given object
+		 * @param type
+		 * @param {String|Number|Object|Backbone.RelationalModel} item
+		 * @return {String|Number}
+		 */
+		resolveIdForItem: function( type, item ) {
+			var id = _.isString( item ) || _.isNumber( item ) ? item : null;
+
+			if ( id === null ) {
+				if ( item instanceof Backbone.RelationalModel ) {
+					id = item.id;
+				}
+				else if ( _.isObject( item ) ) {
+					id = item[ type.prototype.idAttribute ];
+				}
+			}
+
+			// Make all falsy values `null` (except for 0, which could be an id.. see '/issues/179')
+			if ( !id && id !== 0 ) {
+				id = null;
+			}
+
+			return id;
+		},
+
+		/**
+		 *
+		 * @param type
+		 * @param {String|Number|Object|Backbone.RelationalModel} item
+		 */
+		find: function( type, item ) {
+			var id = this.resolveIdForItem( type, item );
 			var coll = this.getCollection( type );
-			return coll && coll.get( id );
+			
+			// Because the found object could be of any of the type's superModel
+			// types, only return it if it's actually of the type asked for.
+			if ( coll ) {
+				var obj = coll.get( id );
+
+				if ( obj instanceof type ) {
+					return obj;
+				}
+			}
+
+			return null;
 		},
 		
 		/**
@@ -253,19 +370,19 @@
 	 * are used to regulate addition and removal of models from relations.
 	 *
 	 * @param {Backbone.RelationalModel} instance
-	 * @param {object} options
+	 * @param {Object} options
 	 * @param {string} options.key
 	 * @param {Backbone.RelationalModel.constructor} options.relatedModel
-	 * @param {Boolean|String} [options.includeInJSON=true] Serialize the given attribute for related model(s)' in toJSON,  or just their ids.
+	 * @param {Boolean|String} [options.includeInJSON=true] Serialize the given attribute for related model(s)' in toJSON, or just their ids.
 	 * @param {Boolean} [options.createModels=true] Create objects from the contents of keys if the object is not found in Backbone.store.
-	 * @param {object} [options.reverseRelation] Specify a bi-directional relation. If provided, Relation will reciprocate
+	 * @param {Object} [options.reverseRelation] Specify a bi-directional relation. If provided, Relation will reciprocate
 	 *    the relation to the 'relatedModel'. Required and optional properties match 'options', except that it also needs
 	 *    {Backbone.Relation|String} type ('HasOne' or 'HasMany').
 	 */
 	Backbone.Relation = function( instance, options ) {
 		this.instance = instance;
 		// Make sure 'options' is sane, and fill with defaults from subclasses and this object's prototype
-		options = ( typeof options === 'object' && options ) || {};
+		options = _.isObject( options ) ? options : {};
 		this.reverseRelation = _.defaults( options.reverseRelation || {}, this.options.reverseRelation );
 		this.reverseRelation.type = !_.isString( this.reverseRelation.type ) ? this.reverseRelation.type :
 			Backbone[ this.reverseRelation.type ] || Backbone.Relational.store.getObjectByName( this.reverseRelation.type );
@@ -273,6 +390,8 @@
 		this.options = _.defaults( options, this.options, Backbone.Relation.prototype.options );
 		
 		this.key = this.options.key;
+		this.keySource = this.options.keySource || this.key;
+		this.keyDestination = this.options.keyDestination || this.keySource || this.key;
 
 		// 'exports' should be the global object where 'relatedModel' can be found on if given as a string.
 		this.relatedModel = this.options.relatedModel;
@@ -284,8 +403,14 @@
 			return false;
 		}
 
-		if(instance) {
-			this.keyContents = this.instance.get( this.key );
+		if ( instance ) {
+			this.keyContents = this.instance.get( this.keySource );
+
+			// Explicitly clear 'keySource', to prevent a leaky abstraction if 'keySource' differs from 'key'.
+			if ( this.key !== this.keySource ) {
+				this.instance.unset( this.keySource, { silent: true } );
+			}
+
 			// Add this Relation to instance._relations
 			this.instance._relations.push( this );
 		}
@@ -304,7 +429,7 @@
 
 		_.bindAll( this, '_modelRemovedFromCollection', '_relatedModelAdded', '_relatedModelRemoved' );
 
-		if( instance ) {
+		if ( instance ) {
 			this.initialize();
 
 			// When a model in the store is destroyed, check if it is 'this.instance'.
@@ -358,64 +483,68 @@
 		 * @return {Boolean} True if pre-conditions are satisfied, false if they're not.
 		 */
 		checkPreconditions: function() {
-			var i = this.instance, k = this.key, m = this.model, rm = this.relatedModel, warn = Backbone.Relational.showWarnings;
+			var i = this.instance,
+				k = this.key,
+				m = this.model,
+				rm = this.relatedModel,
+				warn = Backbone.Relational.showWarnings && typeof console !== 'undefined';
+
 			if ( !m || !k || !rm ) {
-				warn && typeof console !== 'undefined' && console.warn( 'Relation=%o; no model, key or relatedModel (%o, %o, %o)', this, k, rm );
+				warn && console.warn( 'Relation=%o; no model, key or relatedModel (%o, %o, %o)', this, m, k, rm );
 				return false;
 			}
-			// Check if the type in 'relatedModel' inherits from Backbone.RelationalModel
-			if ( !( m.prototype instanceof Backbone.RelationalModel.prototype.constructor ) ) {
-				warn && typeof console !== 'undefined' && console.warn( 'Relation=%o; model does not inherit from Backbone.RelationalModel (%o)', this, i );
+			// Check if the type in 'model' inherits from Backbone.RelationalModel
+			if ( !( m.prototype instanceof Backbone.RelationalModel ) ) {
+				warn && console.warn( 'Relation=%o; model does not inherit from Backbone.RelationalModel (%o)', this, i );
 				return false;
 			}
 			// Check if the type in 'relatedModel' inherits from Backbone.RelationalModel
-			if ( !( rm.prototype instanceof Backbone.RelationalModel.prototype.constructor ) ) {
-				warn && typeof console !== 'undefined' && console.warn( 'Relation=%o; relatedModel does not inherit from Backbone.RelationalModel (%o)', this, rm );
+			if ( !( rm.prototype instanceof Backbone.RelationalModel ) ) {
+				warn && console.warn( 'Relation=%o; relatedModel does not inherit from Backbone.RelationalModel (%o)', this, rm );
 				return false;
 			}
 			// Check if this is not a HasMany, and the reverse relation is HasMany as well
-			if ( this instanceof Backbone.HasMany && this.reverseRelation.type === Backbone.HasMany.prototype.constructor ) {
-				warn && typeof console !== 'undefined' && console.warn( 'Relation=%o; relation is a HasMany, and the reverseRelation is HasMany as well.', this );
+			if ( this instanceof Backbone.HasMany && this.reverseRelation.type === Backbone.HasMany ) {
+				warn && console.warn( 'Relation=%o; relation is a HasMany, and the reverseRelation is HasMany as well.', this );
 				return false;
 			}
 
-			if( i ) {
-				// Check if we're not attempting to create a duplicate relationship
-				if ( i._relations.length ) {
-					var exists = _.any( i._relations, function( rel ) {
+			// Check if we're not attempting to create a duplicate relationship
+			if ( i && i._relations.length ) {
+				var exists = _.any( i._relations, function( rel ) {
 						var hasReverseRelation = this.reverseRelation.key && rel.reverseRelation.key;
 						return rel.relatedModel === rm && rel.key === k &&
 							( !hasReverseRelation || this.reverseRelation.key === rel.reverseRelation.key );
 					}, this );
 
-					if ( exists ) {
-						warn && typeof console !== 'undefined' && console.warn( 'Relation=%o between instance=%o.%s and relatedModel=%o.%s already exists',
+				if ( exists ) {
+					warn && console.warn( 'Relation=%o between instance=%o.%s and relatedModel=%o.%s already exists',
 						this, i, k, rm, this.reverseRelation.key );
-						return false;
-					}
+					return false;
 				}
 			}
+
 			return true;
 		},
-		
+
+		/**
+		 * Set the related model(s) for this relation
+		 * @param {Backbone.Mode|Backbone.Collection} related
+		 * @param {Object} [options]
+		 */
 		setRelated: function( related, options ) {
 			this.related = related;
-			var value = {};
-			value[ this.key ] = related;
+
 			this.instance.acquire();
-			this.instance.set( value, _.defaults( options || {}, { silent: true } ) );
+			this.instance.set( this.key, related, _.defaults( options || {}, { silent: true } ) );
 			this.instance.release();
 		},
 		
-		createModel: function( item ) {
-			if ( this.options.createModels && typeof( item ) === 'object' ) {
-				return new this.relatedModel( item );
-			}
-		},
-		
 		/**
 		 * Determine if a relation (on a different RelationalModel) is the reverse
 		 * relation of the current one.
+		 * @param {Backbone.Relation} relation
+		 * @return {Boolean}
 		 */
 		_isReverseRelation: function( relation ) {
 			if ( relation.instance instanceof this.relatedModel && this.reverseRelation.key === relation.key &&
@@ -429,34 +558,52 @@
 		 * Get the reverse relations (pointing back to 'this.key' on 'this.instance') for the currently related model(s).
 		 * @param {Backbone.RelationalModel} [model] Get the reverse relations for a specific model.
 		 *    If not specified, 'this.related' is used.
+		 * @return {Backbone.Relation[]}
 		 */
 		getReverseRelations: function( model ) {
 			var reverseRelations = [];
 			// Iterate over 'model', 'this.related.models' (if this.related is a Backbone.Collection), or wrap 'this.related' in an array.
 			var models = !_.isUndefined( model ) ? [ model ] : this.related && ( this.related.models || [ this.related ] );
 			_.each( models , function( related ) {
-				_.each( related.getRelations(), function( relation ) {
-					if ( this._isReverseRelation( relation ) ) {
-						reverseRelations.push( relation );
-					}
+					_.each( related.getRelations(), function( relation ) {
+							if ( this._isReverseRelation( relation ) ) {
+								reverseRelations.push( relation );
+							}
+						}, this );
 				}, this );
-			}, this );
 			
 			return reverseRelations;
 		},
 		
 		/**
-		 * Rename options.silent, so add/remove events propagate properly.
+		 * Rename options.silent to options.silentChange, so events propagate properly.
 		 * (for example in HasMany, from 'addRelated'->'handleAddition')
+		 * @param {Object} [options]
+		 * @return {Object}
 		 */
 		sanitizeOptions: function( options ) {
-			options || ( options = {} );
+			options = options ? _.clone( options ) : {};
 			if ( options.silent ) {
-				options = _.extend( {}, options, { silentChange: true } );
+				options.silentChange = true;
 				delete options.silent;
 			}
 			return options;
 		},
+
+		/**
+		 * Rename options.silentChange to options.silent, so events are silenced as intended in Backbone's
+		 * original functions.
+		 * @param {Object} [options]
+		 * @return {Object}
+		 */
+		unsanitizeOptions: function( options ) {
+			options = options ? _.clone( options ) : {};
+			if ( options.silentChange ) {
+				options.silent = true;
+				delete options.silentChange;
+			}
+			return options;
+		},
 		
 		// Cleanup. Get reverse relation, call removeRelated on each.
 		destroy: function() {
@@ -487,10 +634,9 @@
 			this.setRelated( model );
 
 			// Notify new 'related' object of the new relation.
-			var dit = this;
-			_.each( dit.getReverseRelations(), function( relation ) {
-				relation.addRelated( dit.instance );
-			} );
+			_.each( this.getReverseRelations(), function( relation ) {
+					relation.addRelated( this.instance );
+				}, this );
 		},
 		
 		findRelated: function( options ) {
@@ -500,16 +646,8 @@
 			if ( item instanceof this.relatedModel ) {
 				model = item;
 			}
-			else if ( item && ( _.isString( item ) || _.isNumber( item ) || typeof( item ) === 'object' ) ) {
-				// Try to find an instance of the appropriate 'relatedModel' in the store, or create it
-				var id = _.isString( item ) || _.isNumber( item ) ? item : item[ this.relatedModel.prototype.idAttribute ];
-				model = Backbone.Relational.store.find( this.relatedModel, id );
-				if ( model && _.isObject( item ) ) {
-					model.set( item, options );
-				}
-				else if ( !model ) {
-					model = this.createModel( item );
-				}
+			else if ( item || item === 0 ) { // since 0 can be a valid `id` as well
+				model = this.relatedModel.findOrCreate( item, { create: this.options.createModels } );
 			}
 			
 			return model;
@@ -519,7 +657,7 @@
 		 * If the key is changed, notify old & new reverse relations and initialize the new relation
 		 */
 		onChange: function( model, attr, options ) {
-			// Don't accept recursive calls to onChange (like onChange->findRelated->createModel->initializeRelations->addRelated->onChange)
+			// Don't accept recursive calls to onChange (like onChange->findRelated->findOrCreate->initializeRelations->addRelated->onChange)
 			if ( this.isLocked() ) {
 				return;
 			}
@@ -582,9 +720,9 @@
 			options = this.sanitizeOptions( options );
 			
 			var item = this.keyContents;
-			if ( item && ( _.isString( item ) || _.isNumber( item ) || typeof( item ) === 'object' ) ) {
-				var id = _.isString( item ) || _.isNumber( item ) ? item : item[ this.relatedModel.prototype.idAttribute ];
-				if ( model.id === id ) {
+			if ( item || item === 0 ) { // since 0 can be a valid `id` as well
+				var id = Backbone.Relational.store.resolveIdForItem( this.relatedModel, item );
+				if ( !_.isNull( id ) && model.id === id ) {
 					this.addRelated( model, options );
 				}
 			}
@@ -617,7 +755,8 @@
 		options: {
 			reverseRelation: { type: 'HasOne' },
 			collectionType: Backbone.Collection,
-			collectionKey: true
+			collectionKey: true,
+			collectionOptions: {}
 		},
 		
 		initialize: function() {
@@ -626,37 +765,58 @@
 			
 			// Handle a custom 'collectionType'
 			this.collectionType = this.options.collectionType;
-			if ( _( this.collectionType ).isString() ) {
+			if ( _.isString( this.collectionType ) ) {
 				this.collectionType = Backbone.Relational.store.getObjectByName( this.collectionType );
 			}
-			if ( !this.collectionType.prototype instanceof Backbone.Collection.prototype.constructor ){
+			if ( !this.collectionType.prototype instanceof Backbone.Collection ){
 				throw new Error( 'collectionType must inherit from Backbone.Collection' );
 			}
-			
-			this.setRelated( this.prepareCollection( new this.collectionType() ) );
+
+			// Handle cases where a model/relation is created with a collection passed straight into 'attributes'
+			if ( this.keyContents instanceof Backbone.Collection ) {
+				this.setRelated( this._prepareCollection( this.keyContents ) );
+			}
+			else {
+				this.setRelated( this._prepareCollection() );
+			}
+
 			this.findRelated( { silent: true } );
 		},
 		
-		prepareCollection: function( collection ) {
+		_getCollectionOptions: function() {
+			return _.isFunction( this.options.collectionOptions ) ?
+				this.options.collectionOptions( this.instance ) :
+				this.options.collectionOptions;
+		},
+
+		/**
+		 * Bind events and setup collectionKeys for a collection that is to be used as the backing store for a HasMany.
+		 * If no 'collection' is supplied, a new collection will be created of the specified 'collectionType' option.
+		 * @param {Backbone.Collection} [collection]
+		 */
+		_prepareCollection: function( collection ) {
 			if ( this.related ) {
 				this.related
 					.unbind( 'relational:add', this.handleAddition )
 					.unbind( 'relational:remove', this.handleRemoval )
 					.unbind( 'relational:reset', this.handleReset )
 			}
-			
-			collection.reset();
+
+			if ( !collection || !( collection instanceof Backbone.Collection ) ) {
+				collection = new this.collectionType( [], this._getCollectionOptions() );
+			}
+
 			collection.model = this.relatedModel;
 			
 			if ( this.options.collectionKey ) {
 				var key = this.options.collectionKey === true ? this.options.reverseRelation.key : this.options.collectionKey;
 				
-				if (collection[ key ] && collection[ key ] !== this.instance ) {
+				if ( collection[ key ] && collection[ key ] !== this.instance ) {
 					if ( Backbone.Relational.showWarnings && typeof console !== 'undefined' ) {
 						console.warn( 'Relation=%o; collectionKey=%s already exists on collection=%o', this, key, this.options.collectionKey );
 					}
 				}
-				else {
+				else if ( key ) {
 					collection[ key ] = this.instance;
 				}
 			}
@@ -671,25 +831,36 @@
 		
 		findRelated: function( options ) {
 			if ( this.keyContents ) {
-				// Handle cases the an API/user supplies just an Object/id instead of an Array
-				this.keyContents = _.isArray( this.keyContents ) ? this.keyContents : [ this.keyContents ];
+				var models = [];
 
-				// Try to find instances of the appropriate 'relatedModel' in the store
-				_.each( this.keyContents, function( item ) {
-					var id = _.isString( item ) || _.isNumber( item ) ? item : item[ this.relatedModel.prototype.idAttribute ];
-					
-					var model = Backbone.Relational.store.find( this.relatedModel, id );
-					if ( model && _.isObject( item ) ) {
-						model.set( item, options );
-					}
-					else if ( !model ) {
-						model = this.createModel( item );
-					}
-					
-					if ( model && !this.related.getByCid( model ) && !this.related.get( model ) ) {
-						this.related.add( model );
-					}
-				}, this);
+				if ( this.keyContents instanceof Backbone.Collection ) {
+					models = this.keyContents.models;
+				}
+				else {
+					// Handle cases the an API/user supplies just an Object/id instead of an Array
+					this.keyContents = _.isArray( this.keyContents ) ? this.keyContents : [ this.keyContents ];
+
+					// Try to find instances of the appropriate 'relatedModel' in the store
+					_.each( this.keyContents, function( item ) {
+							var model = null;
+							if ( item instanceof this.relatedModel ) {
+								model = item;
+							}
+							else if ( item || item === 0 ) { // since 0 can be a valid `id` as well
+								model = this.relatedModel.findOrCreate( item, { create: this.options.createModels } );
+							}
+
+							if ( model && !this.related.getByCid( model ) && !this.related.get( model ) ) {
+								models.push( model );
+							}
+						}, this );
+				}
+
+				// Add all found 'models' in on go, so 'add' will only be called once (and thus 'sort', etc.)
+				if ( models.length ) {
+					options = this.unsanitizeOptions( options );
+					this.related.add( models, options );
+				}
 			}
 		},
 		
@@ -707,14 +878,24 @@
 			
 			// Replace 'this.related' by 'attr' if it is a Backbone.Collection
 			if ( attr instanceof Backbone.Collection ) {
-				this.prepareCollection( attr );
+				this._prepareCollection( attr );
 				this.related = attr;
 			}
 			// Otherwise, 'attr' should be an array of related object ids.
-			// Re-use the current 'this.related' if it is a Backbone.Collection.
+			// Re-use the current 'this.related' if it is a Backbone.Collection, and remove any current entries.
+			// Otherwise, create a new collection.
 			else {
-				var coll = this.related instanceof Backbone.Collection ? this.related : new this.collectionType();
-				this.setRelated( this.prepareCollection( coll ) );
+				var coll;
+
+				if ( this.related instanceof Backbone.Collection ) {
+					coll = this.related;
+					coll.remove( coll.models );
+				}
+				else {
+					coll = this._prepareCollection();
+				}
+
+				this.setRelated( coll );
 				this.findRelated( options );
 			}
 			
@@ -734,9 +915,9 @@
 			if ( !this.related.getByCid( model ) && !this.related.get( model ) ) {
 				// Check if this new model was specified in 'this.keyContents'
 				var item = _.any( this.keyContents, function( item ) {
-					var id = _.isString( item ) || _.isNumber( item ) ? item : item[ this.relatedModel.prototype.idAttribute ];
-					return id && id === model.id;
-				}, this );
+						var id = Backbone.Relational.store.resolveIdForItem( this.relatedModel, item );
+						return !_.isNull( id ) && id === model.id;
+					}, this );
 				
 				if ( item ) {
 					this.related.add( model, options );
@@ -752,7 +933,7 @@
 			//console.debug('handleAddition called; args=%o', arguments);
 			// Make sure the model is in fact a valid model before continuing.
 			// (it can be invalid as a result of failing validation in Backbone.Collection._prepareModel)
-			if( !( model instanceof Backbone.Model ) ) {
+			if ( !( model instanceof Backbone.Model ) ) {
 				return;
 			}
 			
@@ -775,7 +956,7 @@
 		 */
 		handleRemoval: function( model, coll, options ) {
 			//console.debug('handleRemoval called; args=%o', arguments);
-			if( !( model instanceof Backbone.Model ) ) {
+			if ( !( model instanceof Backbone.Model ) ) {
 				return;
 			}
 
@@ -802,6 +983,7 @@
 		
 		addRelated: function( model, options ) {
 			var dit = this;
+			options = this.unsanitizeOptions( options );
 			model.queue( function() { // Queued to avoid errors for adding 'model' to the 'this.related' set twice
 				if ( dit.related && !dit.related.getByCid( model ) && !dit.related.get( model ) ) {
 					dit.related.add( model, options );
@@ -810,6 +992,7 @@
 		},
 		
 		removeRelated: function( model, options ) {
+			options = this.unsanitizeOptions( options );
 			if ( this.related.getByCid( model ) || this.related.get( model ) ) {
 				this.related.remove( model, options );
 			}
@@ -830,6 +1013,9 @@
 		_deferProcessing: false,
 		_queue: null,
 		
+		subModelTypeAttribute: 'type',
+		subModelTypes: null,
+		
 		constructor: function( attributes, options ) {
 			// Nasty hack, for cases like 'model.get( <HasMany key> ).add( item )'.
 			// Defer 'processQueue', so that when 'Relation.createModels' is used we:
@@ -861,7 +1047,7 @@
 			this._queue.block();
 			Backbone.Relational.eventQueue.block();
 			
-			Backbone.Model.prototype.constructor.apply( this, arguments );
+			Backbone.Model.apply( this, arguments );
 			
 			// Try to run the global queue holding external events
 			Backbone.Relational.eventQueue.unblock();
@@ -894,7 +1080,7 @@
 			
 			_.each( this.relations, function( rel ) {
 					var type = !_.isString( rel.type ) ? rel.type :	Backbone[ rel.type ] || Backbone.Relational.store.getObjectByName( rel.type );
-					if ( type && type.prototype instanceof Backbone.Relation.prototype.constructor ) {
+					if ( type && type.prototype instanceof Backbone.Relation ) {
 						new type( this, rel ); // Also pushes the new Relation into _relations
 					}
 					else {
@@ -906,17 +1092,18 @@
 			this.release();
 			this.processQueue();
 		},
-		
+
 		/**
 		 * When new values are set, notify this model's relations (also if options.silent is set).
 		 * (Relation.setRelated locks this model before calling 'set' on it to prevent loops)
 		 */
 		updateRelations: function( options ) {
-			if( this._isInitialized && !this.isLocked() ) {
+			if ( this._isInitialized && !this.isLocked() ) {
 				_.each( this._relations, function( rel ) {
-					var val = this.attributes[ rel.key ];
+					// Update from data in `rel.keySource` if set, or `rel.key` otherwise
+					var val = this.attributes[ rel.keySource ] || this.attributes[ rel.key ];
 					if ( rel.related !== val ) {
-						this.trigger('relational:change:' + rel.key, this, val, options || {} );
+						this.trigger( 'relational:change:' + rel.key, this, val, options || {} );
 					}
 				}, this );
 			}
@@ -962,18 +1149,19 @@
 		/**
 		 * Retrieve related objects.
 		 * @param key {string} The relation key to fetch models for.
-		 * @param options {object} Options for 'Backbone.Model.fetch' and 'Backbone.sync'.
+		 * @param options {Object} Options for 'Backbone.Model.fetch' and 'Backbone.sync'.
+		 * @param update {boolean} Whether to force a fetch from the server (updating existing models).
 		 * @return {jQuery.when[]} An array of request objects
 		 */
-		fetchRelated: function( key, options ) {
+		fetchRelated: function( key, options, update ) {
 			options || ( options = {} );
 			var setUrl,
 				requests = [],
 				rel = this.getRelation( key ),
 				keyContents = rel && rel.keyContents,
 				toFetch = keyContents && _.select( _.isArray( keyContents ) ? keyContents : [ keyContents ], function( item ) {
-					var id = _.isString( item ) || _.isNumber( item ) ? item : item[ rel.relatedModel.prototype.idAttribute ];
-					return id && !Backbone.Relational.store.find( rel.relatedModel, id );
+					var id = Backbone.Relational.store.resolveIdForItem( rel.relatedModel, item );
+					return !_.isNull( id ) && ( update || !Backbone.Relational.store.find( rel.relatedModel, id ) );
 				}, this );
 			
 			if ( toFetch && toFetch.length ) {
@@ -981,13 +1169,13 @@
 				var models = _.map( toFetch, function( item ) {
 					var model;
 
-					if ( typeof( item ) === 'object' ) {
-						model = new rel.relatedModel( item );
+					if ( _.isObject( item ) ) {
+						model = rel.relatedModel.build( item );
 					}
 					else {
 						var attrs = {};
 						attrs[ rel.relatedModel.prototype.idAttribute ] = item;
-						model = new rel.relatedModel( attrs );
+						model = rel.relatedModel.build( attrs );
 					}
 
 					return model;
@@ -1007,9 +1195,9 @@
 							error: function() {
 								var args = arguments;
 								_.each( models, function( model ) {
-									model.trigger( 'destroy', model, model.collection, options );
-									options.error && options.error.apply( model, args );
-								});
+										model.trigger( 'destroy', model, model.collection, options );
+										options.error && options.error.apply( model, args );
+									});
 							},
 							url: setUrl
 						},
@@ -1043,7 +1231,7 @@
 			
 			// Duplicate backbone's behavior to allow separate key/value parameters, instead of a single 'attributes' object
 			var attributes;
-			if (_.isObject( key ) || key == null) {
+			if ( _.isObject( key ) || key == null ) {
 				attributes = key;
 				options = value;
 			}
@@ -1054,10 +1242,12 @@
 			
 			var result = Backbone.Model.prototype.set.apply( this, arguments );
 			
-			// 'set' is called quite late in 'Backbone.Model.prototype.constructor', but before 'initialize'.
 			// Ideal place to set up relations :)
 			if ( !this._isInitialized && !this.isLocked() ) {
+				this.constructor.initializeModelHierarchy();
+
 				Backbone.Relational.store.register( this );
+
 				this.initializeRelations();
 			}
 			// Update the 'idAttribute' in Backbone.store if; we don't want it to miss an 'id' update due to {silent:true}
@@ -1104,9 +1294,9 @@
 		 * and 'previousAttributes' will be available when the event is fired.
 		 */
 		change: function( options ) {
-			var dit = this;
+			var dit = this, args = arguments;
 			Backbone.Relational.eventQueue.add( function() {
-					Backbone.Model.prototype.change.apply( dit, arguments );
+					Backbone.Model.prototype.change.apply( dit, args );
 				});
 		},
 
@@ -1117,8 +1307,8 @@
 			}
 
 			_.each( this.getRelations(), function( rel ) {
-				delete attributes[ rel.key ];
-			});
+					delete attributes[ rel.key ];
+				});
 
 			return new this.constructor( attributes );
 		},
@@ -1135,61 +1325,275 @@
 			this.acquire();
 			var json = Backbone.Model.prototype.toJSON.call( this );
 			
+			if ( this.constructor._superModel && !( this.constructor._subModelTypeAttribute in json ) ) {
+				json[ this.constructor._subModelTypeAttribute ] = this.constructor._subModelTypeValue;
+			}
+			
 			_.each( this._relations, function( rel ) {
 					var value = json[ rel.key ];
-					
-					if ( rel.options.includeInJSON === true && value && _.isFunction( value.toJSON ) ) {
-						json[ rel.key ] = value.toJSON();
+
+					if ( rel.options.includeInJSON === true) {
+						if ( value && _.isFunction( value.toJSON ) ) {
+							json[ rel.keyDestination ] = value.toJSON();
+						}
+						else {
+							json[ rel.keyDestination ] = null;
+						}
 					}
 					else if ( _.isString( rel.options.includeInJSON ) ) {
 						if ( value instanceof Backbone.Collection ) {
-							json[ rel.key ] = value.pluck( rel.options.includeInJSON );
+							json[ rel.keyDestination ] = value.pluck( rel.options.includeInJSON );
 						}
 						else if ( value instanceof Backbone.Model ) {
-							json[ rel.key ] = value.get( rel.options.includeInJSON );
+							json[ rel.keyDestination ] = value.get( rel.options.includeInJSON );
+						}	
+						else {
+							json[ rel.keyDestination ] = null;
+						}
+					}
+					else if ( _.isArray( rel.options.includeInJSON ) ) {
+						if ( value instanceof Backbone.Collection ) {
+							var valueSub = [];
+							value.each( function( model ) {
+								var curJson = {};
+								_.each( rel.options.includeInJSON, function( key ) {
+									curJson[ key ] = model.get( key );
+								});
+								valueSub.push( curJson );
+							});
+							json[ rel.keyDestination ] = valueSub;
+						}
+						else if ( value instanceof Backbone.Model ) {
+							var valueSub = {};
+							_.each( rel.options.includeInJSON, function( key ) {
+								valueSub[ key ] = value.get( key );
+							});
+							json[ rel.keyDestination ] = valueSub;
+						}
+						else {
+							json[ rel.keyDestination ] = null;
 						}
 					}
 					else {
 						delete json[ rel.key ];
 					}
-				}, this );
+
+					if ( rel.keyDestination !== rel.key ) {
+						delete json[ rel.key ];
+					}
+				});
 			
 			this.release();
 			return json;
 		}
+	},
+	{
+		setup: function( superModel ) {
+			// We don't want to share a relations array with a parent, as this will cause problems with
+			// reverse relations.
+			this.prototype.relations = ( this.prototype.relations || [] ).slice( 0 );
+
+			this._subModels = {};
+			this._superModel = null;
+
+			// If this model has 'subModelTypes' itself, remember them in the store
+			if ( this.prototype.hasOwnProperty( 'subModelTypes' ) ) {
+				Backbone.Relational.store.addSubModels( this.prototype.subModelTypes, this );
+			}
+			// The 'subModelTypes' property should not be inherited, so reset it.
+			else {
+				this.prototype.subModelTypes = null;
+			}
+
+			// Initialize all reverseRelations that belong to this new model.
+			_.each( this.prototype.relations, function( rel ) {
+					if ( !rel.model ) {
+						rel.model = this;
+					}
+
+					if ( rel.reverseRelation && rel.model === this ) {				
+						var preInitialize = true;
+						if ( _.isString( rel.relatedModel ) ) {
+							/**
+							 * The related model might not be defined for two reasons
+							 *  1. it never gets defined, e.g. a typo
+							 *  2. it is related to itself
+							 * In neither of these cases do we need to pre-initialize reverse relations.
+							 */
+							var relatedModel = Backbone.Relational.store.getObjectByName( rel.relatedModel );
+							preInitialize = relatedModel && ( relatedModel.prototype instanceof Backbone.RelationalModel );
+						}
+
+						var type = !_.isString( rel.type ) ? rel.type : Backbone[ rel.type ] || Backbone.Relational.store.getObjectByName( rel.type );
+						if ( preInitialize && type && type.prototype instanceof Backbone.Relation ) {
+							new type( null, rel );
+						}
+					}
+				}, this );
+			
+			return this;
+		},
+
+		/**
+		 * Create a 'Backbone.Model' instance based on 'attributes'.
+		 * @param {Object} attributes
+		 * @param {Object} [options]
+		 * @return {Backbone.Model}
+		 */
+		build: function( attributes, options ) {
+			var model = this;
+
+			// 'build' is a possible entrypoint; it's possible no model hierarchy has been determined yet.
+			this.initializeModelHierarchy();
+
+			// Determine what type of (sub)model should be built if applicable.
+			// Lookup the proper subModelType in 'this._subModels'.
+			if ( this._subModels && this.prototype.subModelTypeAttribute in attributes ) {
+				var subModelTypeAttribute = attributes[ this.prototype.subModelTypeAttribute ];
+				var subModelType = this._subModels[ subModelTypeAttribute ];
+				if ( subModelType ) {
+					model = subModelType;
+				}
+			}
+			
+			return new model( attributes, options );
+		},
+
+		initializeModelHierarchy: function() {
+			// If we're here for the first time, try to determine if this modelType has a 'superModel'.
+			if ( _.isUndefined( this._superModel ) || _.isNull( this._superModel ) ) {
+				Backbone.Relational.store.setupSuperModel( this );
+
+				// If a superModel has been found, copy relations from the _superModel if they haven't been
+				// inherited automatically (due to a redefinition of 'relations').
+				// Otherwise, make sure we don't get here again for this type by making '_superModel' false so we fail
+				// the isUndefined/isNull check next time.
+				if ( this._superModel ) {
+					//
+					if ( this._superModel.prototype.relations ) {
+						var supermodelRelationsExist = _.any( this.prototype.relations, function( rel ) {
+							return rel.model && rel.model !== this;
+						}, this );
+
+						if ( !supermodelRelationsExist ) {
+							this.prototype.relations = this._superModel.prototype.relations.concat( this.prototype.relations );
+						}
+					}
+				}
+				else {
+					this._superModel = false;
+				}
+			}
+
+			// If we came here through 'build' for a model that has 'subModelTypes', and not all of them have been resolved yet, try to resolve each.
+			if ( this.prototype.subModelTypes && _.keys( this.prototype.subModelTypes ).length !== _.keys( this._subModels ).length ) {
+				_.each( this.prototype.subModelTypes, function( subModelTypeName ) {
+					var subModelType = Backbone.Relational.store.getObjectByName( subModelTypeName );
+					subModelType && subModelType.initializeModelHierarchy();
+				});
+			}
+		},
+
+		/**
+		 * Find an instance of `this` type in 'Backbone.Relational.store'.
+		 * - If `attributes` is a string or a number, `findOrCreate` will just query the `store` and return a model if found.
+		 * - If `attributes` is an object, the model will be updated with `attributes` if found.
+		 *   Otherwise, a new model is created with `attributes` (unless `options.create` is explicitly set to `false`).
+		 * @param {Object|String|Number} attributes Either a model's id, or the attributes used to create or update a model.
+		 * @param {Object} [options]
+		 * @param {Boolean} [options.create=true]
+		 * @return {Backbone.RelationalModel}
+		 */
+		findOrCreate: function( attributes, options ) {
+			// Try to find an instance of 'this' model type in the store
+			var model = Backbone.Relational.store.find( this, attributes );
+
+			// If we found an instance, update it with the data in 'item'; if not, create an instance
+			// (unless 'options.create' is false).
+			if ( _.isObject( attributes ) ) {
+				if ( model ) {
+					model.set( attributes, options );
+				}
+				else if ( !options || ( options && options.create !== false ) ) {
+					model = this.build( attributes, options );
+				}
+			}
+
+			return model;
+		}
 	});
 	_.extend( Backbone.RelationalModel.prototype, Backbone.Semaphore );
 	
+	/**
+	 * Override Backbone.Collection._prepareModel, so objects will be built using the correct type
+	 * if the collection.model has subModels.
+	 */
+	Backbone.Collection.prototype.__prepareModel = Backbone.Collection.prototype._prepareModel;
+	Backbone.Collection.prototype._prepareModel = function ( model, options ) {
+		options || (options = {});
+		if ( !( model instanceof Backbone.Model ) ) {
+			var attrs = model;
+			options.collection = this;
+			
+			if ( typeof this.model.build !== 'undefined' ) {
+				model = this.model.build( attrs, options );
+			}
+			else {
+				model = new this.model( attrs, options );
+			}
+			
+			if ( !model._validate( model.attributes, options ) ) {
+				model = false;
+			}
+		}
+		else if ( !model.collection ) {
+			model.collection = this;
+		}
+		
+		return model;
+	}
+	
 	/**
 	 * Override Backbone.Collection.add, so objects fetched from the server multiple times will
 	 * update the existing Model. Also, trigger 'relational:add'.
 	 */
-	var add = Backbone.Collection.prototype.add;
+	var add = Backbone.Collection.prototype.__add = Backbone.Collection.prototype.add;
 	Backbone.Collection.prototype.add = function( models, options ) {
 		options || (options = {});
-		if (!_.isArray( models ) ) {
+		if ( !_.isArray( models ) ) {
 			models = [ models ];
 		}
 
+		var modelsToAdd = [];
+
 		//console.debug( 'calling add on coll=%o; model=%o, options=%o', this, models, options );
 		_.each( models, function( model ) {
-			if ( !( model instanceof Backbone.Model ) ) {
-				// Try to find 'model' in Backbone.store. If it already exists, set the new properties on it.
-				var existingModel = Backbone.Relational.store.find( this.model, model[ this.model.prototype.idAttribute ] );
-				if ( existingModel ) {
-					existingModel.set( model, options );
-					model = existingModel;
+				if ( !( model instanceof Backbone.Model ) ) {
+					// Try to find 'model' in Backbone.store. If it already exists, set the new properties on it.
+					var existingModel = Backbone.Relational.store.find( this.model, model[ this.model.prototype.idAttribute ] );
+					if ( existingModel ) {
+						existingModel.set( existingModel.parse ? existingModel.parse( model ) : model, options );
+						model = existingModel;
+					}
+					else {
+						model = Backbone.Collection.prototype._prepareModel.call( this, model, options );
+					}
 				}
-				else {
-					model = Backbone.Collection.prototype._prepareModel.call( this, model, options );
+
+				if ( model instanceof Backbone.Model && !this.get( model ) && !this.getByCid( model ) ) {
+					modelsToAdd.push( model );
 				}
-			}
+			}, this );
 
-			if ( model instanceof Backbone.Model && !this.get( model ) && !this.getByCid( model ) ) {
-				add.call( this, model, options );
-				this.trigger('relational:add', model, this, options);
-			}
-		}, this );
+
+		// Add 'models' in a single batch, so the original add will only be called once (and thus 'sort', etc).
+		if ( modelsToAdd.length ) {
+			add.call( this, modelsToAdd, options );
+
+			_.each( modelsToAdd, function( model ) {
+					this.trigger( 'relational:add', model, this, options );
+				}, this );
+		}
 		
 		return this;
 	};
@@ -1197,22 +1601,25 @@
 	/**
 	 * Override 'Backbone.Collection.remove' to trigger 'relational:remove'.
 	 */
-	var remove = Backbone.Collection.prototype.remove;
+	var remove = Backbone.Collection.prototype.__remove = Backbone.Collection.prototype.remove;
 	Backbone.Collection.prototype.remove = function( models, options ) {
 		options || (options = {});
-		if (!_.isArray( models ) ) {
+		if ( !_.isArray( models ) ) {
 			models = [ models ];
 		}
+		else {
+			models = models.slice( 0 );
+		}
 
 		//console.debug('calling remove on coll=%o; models=%o, options=%o', this, models, options );
 		_.each( models, function( model ) {
-			model = this.getByCid( model ) || this.get( model );
+				model = this.getByCid( model ) || this.get( model );
 
-			if ( model instanceof Backbone.Model ) {
-				remove.call( this, model, options );
-				this.trigger('relational:remove', model, this, options);
-			}
-		}, this );
+				if ( model instanceof Backbone.Model ) {
+					remove.call( this, model, options );
+					this.trigger('relational:remove', model, this, options);
+				}
+			}, this );
 		
 		return this;
 	};
@@ -1220,10 +1627,21 @@
 	/**
 	 * Override 'Backbone.Collection.reset' to trigger 'relational:reset'.
 	 */
-	var reset = Backbone.Collection.prototype.reset;
+	var reset = Backbone.Collection.prototype.__reset = Backbone.Collection.prototype.reset;
 	Backbone.Collection.prototype.reset = function( models, options ) {
 		reset.call( this, models, options );
-		this.trigger( 'relational:reset', models, options );
+		this.trigger( 'relational:reset', this, options );
+
+		return this;
+	};
+
+	/**
+	 * Override 'Backbone.Collection.sort' to trigger 'relational:reset'.
+	 */
+	var sort = Backbone.Collection.prototype.__sort = Backbone.Collection.prototype.sort;
+	Backbone.Collection.prototype.sort = function( options ) {
+		sort.call( this, options );
+		this.trigger( 'relational:reset', this, options );
 
 		return this;
 	};
@@ -1232,50 +1650,37 @@
 	 * Override 'Backbone.Collection.trigger' so 'add', 'remove' and 'reset' events are queued until relations
 	 * are ready.
 	 */
-	var _trigger = Backbone.Collection.prototype.trigger;
+	var trigger = Backbone.Collection.prototype.__trigger = Backbone.Collection.prototype.trigger;
 	Backbone.Collection.prototype.trigger = function( eventName ) {
 		if ( eventName === 'add' || eventName === 'remove' || eventName === 'reset' ) {
 			var dit = this, args = arguments;
+			
+			if (eventName === 'add') {
+				args = _.toArray(args);
+				// the fourth argument in case of a regular add is the option object.
+				// we need to clone it, as it could be modified while we wait on the eventQueue to be unblocked
+				if (_.isObject(args[3])) {
+					args[3] = _.clone(args[3]);
+				}
+			}
+			
 			Backbone.Relational.eventQueue.add( function() {
-					_trigger.apply( dit, args );
+					trigger.apply( dit, args );
 				});
 		}
 		else {
-			_trigger.apply( this, arguments );
+			trigger.apply( this, arguments );
 		}
 		
 		return this;
 	};
 
-	// Override .extend() to check for reverseRelations to initialize.
+	// Override .extend() to automatically call .setup()
 	Backbone.RelationalModel.extend = function( protoProps, classProps ) {
 		var child = Backbone.Model.extend.apply( this, arguments );
-
-		var relations = ( protoProps && protoProps.relations ) || [];
-		_.each( relations, function( rel ) {
-			if( rel.reverseRelation ) {
-				rel.model = child;
-
-				var preInitialize = true;
-				if ( _.isString( rel.relatedModel ) ) {
-					/**
-					 * The related model might not be defined for two reasons
-					 *  1. it never gets defined, e.g. a typo
-					 *  2. it is related to itself
-					 * In neither of these cases do we need to pre-initialize reverse relations.
-					 */
-					var relatedModel = Backbone.Relational.store.getObjectByName( rel.relatedModel );
-					preInitialize = relatedModel && ( relatedModel.prototype instanceof Backbone.RelationalModel.prototype.constructor );
-				}
-
-				var type = !_.isString( rel.type ) ? rel.type : Backbone[ rel.type ] || Backbone.Relational.store.getObjectByName( rel.type );
-				if ( preInitialize && type && type.prototype instanceof Backbone.Relation.prototype.constructor ) {
-					new type( null, rel );
-				}
-			}
-		});
+		
+		child.setup( this );
 
 		return child;
 	};
-
 })();