gebrits / backbone-jjrelational Goto Github PK

__________                __   ___.                         
\______   \_____    ____ |  | _\_ |__   ____   ____   ____  
 |    |  _/\__  \ _/ ___\|  |/ /| __ \ /  _ \ /    \_/ __ \ 
 |    |   \ / __ \\  \___|    < | \_\ (  <_> )   |  \  ___/ 
 |______  /(____  /\___  >__|_ \|___  /\____/|___|  /\___  >
        \/      \/     \/     \/    \/            \/     \/ 
     ____.    ____.__________       .__          __  .__                     .__   
    |    |   |    |\______   \ ____ |  | _____ _/  |_|__| ____   ____ _____  |  |  
    |    |   |    | |       _// __ \|  | \__  \\   __\  |/  _ \ /    \\__  \ |  |  
/\__|    /\__|    | |    |   \  ___/|  |__/ __ \|  | |  (  <_> )   |  \/ __ \|  |__
\________\________| |____|_  /\___  >____(____  /__| |__|\____/|___|  (____  /____/
                           \/     \/          \/                    \/     \/      

Backbone JJRelational is a plugin that provides one-to-one, one-to-many, many-to-one and many-to-many bi-directional relations between Backbone models.

Backbone JJRelational is inspired by Paul Uithol's Backbone-relational, but supports many-to-many relations out of the box.

Backbone JJRelational has been tested with Backbone 1.0.0 and Underscore 1.5.0

• Installation
• How to use
• Setup example
• Getting and setting data
• Sync - saving and fetching data
• Working with the store - prevent duplice data
• The devil in the details
• Reference
• Running the tests
• License

Backbone JJRelational depends - who would have thought - on Backbone.JS and Underscore.JS.
Simply include backbone.JJRelational.js right after Underscore and Backbone.

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

A string and mandatory. As each model registers itself in Backbone.JJStore upon creation, you have to define an identifier for a store, where instances of the model are put.
Example:

Book = Backbone.JJRelationalModel.extend({
	storeIdentifier: 'Book'
});

You can use the following options when defining relations.

mandatory
A string that defines the type of the relation (from the model's point of view!). Possible values are
has_one: for one-to-one or many-to-one relations
has_many: for one-to-many relations
many_many: for many-to-many relations

mandatory
Same as in Paul Uithol's Backbone-relational, this is a string which can be resolved to an object type on the global scope, or a reference to a Backbone.JJRelationalModel type. This - of course - defines which kind of model fills this relation.

mandatory
A string naming the attribute under which the relation is stored.
has_one relations are stored as a single Backbone.JJRelationalModel, or null when empty.
has_many relations are stored as a Backbone.Collection or an extension of it - provided collectionType has been set and the collection type has been registered with Backbone.JJRelational.registerCollectionTypes.

mandatory
A string naming the attribute of the related model's reverse relation. This is the same as key from the related model's point of view.
For every relation you specify on a model, you always have to specify a reverse relation on the related model in a fitting pattern. Remember: Each key is the same as reverseKey on the related side.
Confused? Take a look at the Setup example

A string referencing a collection type which has been registered with Backbone.JJRelational.registerCollectionTypes(). Explanation: If the relational attribute of a has_many or many_many relation should use one of your extensions of Backbone.Collection, you have to register the collection(s) with a key of your choice by using Backbone.JJRelational.registerCollectionTypes(), and then use that key within the relation's collectionType option.
Example:
javascript BooksColl = Backbone.Collection.extend({ model: Book });

Backbone.JJRelational.registerCollectionTypes({ 'Books': BooksColl // … // … })

…and then within your relation options `collectionType: 'Books'`.

#### includeInJSON
This is an array of strings defining which attributes should be included when the model is saved.
Leaving `includeInJSON` empty means that merely the related model's `id` is included.

<a name="setup-example" />
## Setup example
Here is an example of how the relations between different models could be defined:

```javascript
/*
** Author
*/

// each author can have many books, and many publishers
Author = Backbone.JJRelationalModel.extend({
	storeIdentifier: 'Author',
	relations: [
		{
			type: 'has_many',
			relatedModel: 'Book',
			key: 'books',
			reverseKey: 'author',
			collectionType: 'Books',
			includeInJSON: ['id', 'title']
		},
		{
			type: 'many_many',
			relatedModel: 'Publisher',
			key: 'publishers',
			reverseKey: 'publishedAuthors',
			collectionType: 'Publishers'
		}
	]
});

AuthorsColl = Backbone.Collection.extend({
	model: Author
});

/*
** Book
*/

// each book has one author
Book = Backbone.JJRelationalModel.extend({
	storeIdentifier: 'Book',
	relations: [{
		type: 'has_one',
		relatedModel: 'Author',
		key: 'author',
		reverseKey: 'books',
		includeInJSON: ['id', 'firstname', 'surname']
	}]
});

BooksColl = Backbone.Collection.extend({
	model: Book
});

/*
** Publisher
*/

// each publisher has many authors
Publisher = Backbone.JJRelationalModel.extend({
	storeIdentifier: 'Publisher',
	relations: [{
		type: 'many_many',
		relatedModel: 'Author',
		key: 'publishedAuthors',
		reverseKey: 'publishers',
		collectionType: 'Authors'
	}]
});

PublishersColl = Backbone.Collection.extend({
	model: Publisher
});

// register collection types
Backbone.JJRelational.registerCollectionTypes({
	'Authors': AuthorsColl,
	'Books': BooksColl,
	'Publishers': PublishersColl
});

var whichBook = function (book) {
		var a = book.get('author');
		console.log('"' + book.get('title') + '" by ' + a.get('firstname') + ' ' + a.get('surname'));
	},
	twist = new Book({
		title: 'Oliver Twist',
		author: {
			firstname: 'Charles',
			surname: 'Dickens'
		}
	});
	
whichBook(twist); // <-- logs out '"Oliver Twist" by Charles Dickens

var carroll = new Author({ name: 'Lewis Carroll' }),
	penguin = new Publisher({
		name: 'Penguin Classics',
		publishedAuthors: [caroll, dickens]
	}),
	randomHouse = new Publisher({ name: 'Random House' });
	
randomHouse.get('publishedAuthors').add([carroll, dickens]);

carroll.get('publishers').each(function (publisher) {
	console.log(publisher.get('name')); // <-- logs out 'Penguin Classics' and 'Random House'
});

carroll.get('publishers').remove(randomHouse);

randomHouse.get('publishedAuthors').each(function (author) {
	console.log(author.get('firstname')); // <-- logs out 'Charles'
});

var theRoad = new Book({ title: 'The Road', author: 1 }),	cormac = new Author({ id: 1, firstname: 'Cormac', surname: 'McCarthy' });
whichBook(theRoad); // <-- logs out '"The Road" by Cormac McCarthy'

var cormac = new Author({ id: 1, firstname: 'Cormac', surname: 'McCarthy'}),
	theRoad = new Book({ title: 'The Road', author: 1 });
	

var george = new Author({firstname: 'George', surname: 'Martin', books: [1]}),
	one = new Book({ id: 1, title: 'A Game Of Thrones' }),
	two = new Book({ id: 2, title: 'A Clash Of Kings' }),
	three = new Book({ id: 3, title: 'A Storm Of Swords' }),
	
	books = george.get('books');
	
	books.add([2, 3, {title: 'A Feast For Crows'}]).each(function (book) {
		whichBook(book);
	});
	
	// logs out all four books

var author = new Author({books: new BooksColl([{title: 'a book'}])}); // don't do that!

var author = new Author({books: [{title: 'a book'}]}); // works fine!

Backbone.JJRelational handles everything for you automatically. Nevertheless, this section should explain some of the concepts and possibilities you have when fetching from/persisting to the server. When calling save on a model, the includeInJSON property you defined for the relation is used to generate the JSON which gets persisted to the server. Going further, it is checked for you if a related model is new: If yes, the related model gets saved before! Confused? This example should make your head spin even more:

// We pretend our relational setup is the same as in the setup example.
// So Publishers include publishedAuthors.id, Authors include books.id and books.title

var publisher = new Publisher({ name: "Faber & Faber", authors: [{ firstname: "Martin", surname: "McDonagh", books: [{ title: "The Pillowman" }] }] });
publisher.save();

Okay, now what's going to happen? Publisher relies on the author's id, author relies on the book's id. So at first a save request is fired for "The Pillowman":

{
	"title": "The Pillowman"
}

Provided the book gets persisted to a database, for example, and gets an id, "Martin McDonagh"'s request is fired:

{
	"firstname": "Martin"
	"surname": "McDonagh"
	"books": [{
		"id": 1,
		"title: "The Pillowman"
	}]
}

And now, at last, the publisher will be saved:

{
	"name": "Faber & Faber"
	"authors": [1]
}

When fetching data from the server, Backbone.JJRelational automatically creates the needed models in a relation. Image we would call fetch on a collection of publishers and it would return:

[
{
	"id": 1,
	"name": "Faber & Faber",
	"authors": [{
		"id": 1,
		"firstname": "Martin",
		"surname": "McDonagh"
	}]
}
]

The author model "Martin McDonagh" will be created automatically. Now let's pretend, fetching the publishers would result in merely an ID array of its authors:

[
{
	"id": 1,
	"name": "Faber & Faber",
	"authors": [1,2]
},
{
	"id": 2,
	"name": "Random House",
	"authors": [3,4]
}
]

In this case, JJRelational doesn't create new author models, but stores the IDs in a queue within the relational collection. (Backbone.Collection._relational.idQueue) If faber is our first publisher model, we can call

faber.get('authors').fetchByIdQueue();

This will fetch the authors with IDs 1 and 2 and add them to the collection. (this works for one-to-one and one-to-many relations as well, of course) Or, if we want to fetch all related authors of the whole collection, we can call: (pretending pubColl is our collection of publishers):

pubColl.fetchByIdQueueOfModels('authors');

This will fetch the authors with IDs 1, 2, 3 & 4 and add them to their related publishers appropriately.

var a = new Author({ id: 1, firstname: "Jane", surname: "Doe" });
console.log("a: cid is %s and name is %s %s", a.cid, a.get('firstname'), a.get('surname'));

var b = new Author({ id: 1, surname: "Austen" });
console.log("b: cid is %s and name is %s %s", b.cid, b.get('firstname'), b.get('surname'));

>  a: cid is c1 and name is Jane Doe
>  b: cid is c2 and name is undefined Austen

> a: cid is c1 and name is Jane Doe
> b: cid is c1 and name is Jane Austen

The following Backbone methods were overridden, all other methods (like Collection.reset, Collection.set etc.) merely perform some relational actions before actually calling the core method. See Reference for more information on the overrides:

• Backbone.Model.set
• Backbone.Model.save
• Backbone.Model._validate
• Backbone.Model.toJSON
• Backbone.Collection.fetch

( Object ) Global configuration object. Possible values are:

• url_id_appendix: used for fetchByIdQueue- and fetchByIdQueueOfModels-calls. Default value is '?ids=' , the needed ids are then added comma separated.
• work_with_store: Default is true. This option indicates whether you want Backbone.JJStore to prevent duplication of models. See Working with the store for more information.

Registers one or many collection types, in order to build a correct collection instance for many-relations.

This is pretty much the most important override. Of course it does the same as Backbone core, although it filters relational values and handles them accordingly.
Example:

author.set({ publishers: [2, 3, publisherObj, { name: 'new publisher' }] });

Backbone's original save-method wrapped in relational stuff. The concept is: When saving a model, it is checked whether it has any relations containing a new model. If yes, the new model is saved first. When all new models have been saved, only then is the calling model saved.
Relational collections are saved as an array of models + idQueue.
Concerning relations, the includeInJSON property is used for serializing to JSON. See Sync - saving and fetching data for detailed information.

The difference to Backbone core's _validate method is that this one flattens relational collections down to its model array. We've found that this is more convenient for more general validation functions.

If it's for saving ( options.isSave == true ) then the includeInJSON option of the relation is used. That can go down as many levels as required. If isSave is false, the related models are serialized regularly with their relations represented only by ids, however.

Returns a JSON of the model with all relations represented only by ids.

Fetches missing models of a relation, if their ids are known. See Sync - saving and fetching data for detailed information.

$ npm update

$ node server.js