backbone-relation
Backbone does not support relations by default. This is a simple package that adds relations to Backbone.
The idea is simple: you can define relations like you define defaults. A relation can be either a Model or a Collection and attributes can be set recursively through the parent.
Why use this over backbone-relational? We found backbone-relational too complex. Itʼs basically an ORM in the frontend. We didnʼt need that, hence this package.
Vision
- 100% compatible with original Backbone codebase. All Backbone test must pass when tested using backbone-relation.
- Extend Backbone, don't patch it.
- Make it clear. Only add well defined and tested features, leaving as little as possible open to interpretation.
Use case
Imagine an API-endpoint gives the following response when hitting api/user/1
:
{
id: 1,
username: 'witchhunter',
profile: {
id: 7,
first_name: 'Michelle',
last_name: 'Velvet'
}
}
You can define 2 models, one called MProfile
and the other MUser
:
MProfile = MRelation.extend();
MUser = MRelation.extend({
relations: {
profile: MProfile
}
})
Now you can do a fetch and the profile model will be filled with data on the user model:
mUser = new MUser({id: 1});
mUser.fetch();
...
mUser.get('profile').get('first_name'); // 'Michelle'
When setting data, you can do the following:
mUser.set({
profile: {first_name: 'Vera'}
});
mUser.get('profile').get('first_name'); // 'Vera'
Defining relations
You can define relations using the relations
attribute. It can either be a hash or a function that returns a hash. There are a few different ways to define relations:
Simple
The simplest form without any options. Example:
var MAuthor = Model
Advanced
With this form you can add a bit more configuration options. These are the options at the moment:
Key | Description |
---|---|
relationClass |
The constructor for the relation. This can either be a Backbone.Model or a Backbone.Collection . |
Example:
var MAuthor = Model
Setting related data
The most basic form of setting a related data is getting it first:
mAuthor;mAuthor;
Another way of setting related data is using the attribute name on the parent. These lines do exactly the same:
mAuthor;mAuthor;mAuthor;
This implies that once a relation is set, it cannot be overridden with another value. If you do really want to set another instance for a relation, then first use unset
:
mAuthor;mAuthor;
Bottom line: if a relation exists, set
is proxied.
Getting related data
You can use vanilla Backbone to get related data:
mAuther; // -> Instance of MUser.mAuther // -> Get the id of the related user.
Model.dot
Shorthand for getting nested attributes. Example:
model ;
can be written like:
model;
This depends on that the nested relation has a get
function defined. That function is called each time a dot is found. If you try to use dot
on a value that does not have the function get
defined, it will return undefined
.
Returns undefined
because of someString
is a string without a get
function defined:
model;
Returns undefined
because of object
is an object without a get
function defined:
model;
Returns undefined
because of nonExistingModelOrCollection
is undefined
and thus without a get
function defined:
model;
Returns undefined
because of nonExistingId
is undefined
and thus without a get
function defined:
model;
Itʼs not possible to retrieve attributes with a .
in the name. You can use get
instead:
model;
Options
Key | Default | Description |
---|---|---|
createRelations | true |
true : create relations while initializing model. false : skip creating relations upon initialization. |