BackboneFire is the officially supported Backbone binding for Firebase. The bindings let you use special model and collection types that allow for synchronizing data with Firebase.
Play around with our realtime Todo App demo. This Todo App is a simple port of the TodoMVC app using BackboneFire.
Using BackboneFire collections and models is very similar to the regular ones in Backbone. To setup with BackboneFire use Backbone.Firebase
rather than just Backbone
.
Note: A Backbone.Firebase.Model
should not be used with a Backbone.Firebase.Collection
. Use a regular
Backbone.Model
with a Backbone.Firebase.Collection
.
// This is a plain old Backbone Model
var Todo = Backbone.Model.extend({
defaults: {
completed: false,
title: 'New todo'
}
});
// This is a Firebase Collection that syncs data from this url
var Todos = Backbone.Firebase.Collection.extend({
url: 'https://<your-firebase>.firebaseio.com/todos',
model: Todo
});
To get started include Firebase and BackboneFire after the usual Backbone dependencies (jQuery, Underscore, and Backbone).
<!-- jQuery -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<!-- Underscore -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.7.0/underscore.js"></script>
<!-- Backbone -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/backbone.js/1.1.2/backbone.js"></script>
<!-- Firebase -->
<script src="https://cdn.firebase.com/js/client/2.0.3/firebase.js"></script>
<!-- BackboneFire -->
<script src="https://cdn.firebase.com/libs/backbonefire/0.5.1/backbonefire.js"></script>
Use the URL above to download both the minified and non-minified versions of BackboneFire from the Firebase CDN. You can also download them from the releases page of this GitHub repository. Firebase and Backbone can be downloaded directly from their respective websites.
You can also install BackboneFire via Bower and its dependencies will be downloaded automatically:
$ bower install backbonefire --save
Once you've included BackboneFire and its dependencies into your project, you will have access to the Backbone.Firebase.Collection
, and Backbone.Firebase.Model
objects.
$ npm install git+https://github.com/deoxen0n2/backbonefire.git --save
And in the code:
var Backbone = require('backbonefire');
var Todos = Backbone.Firebase.Collection.extend({ ... });
BackboneFire requires Firebase in order to sync data. You can sign up here for a free account.
As of the 0.5 release there are two ways to sync Models
and Collections
. By specifying the property autoSync
to either true of false, you can control whether the component is synced in realtime. The autoSync
property is true by default.
var RealtimeList = Backbone.Firebase.Collection.extend({
url: 'https://<your-firebase>.firebaseio.com/todos',
autoSync: true // this is true by default
})
// this collection will immediately begin syncing data
// no call to fetch is required, and any calls to fetch will be ignored
var realtimeList = new RealtimeList();
realtimeList.on('sync', function(collection) {
console.log('collection is loaded', collection);
});
// This collection will remain empty until fetch is called
var OnetimeList = Backbone.Firebase.Collection.extend({
url: 'https://<your-firebase>.firebaseio.com/todos',
autoSync: false
})
var onetimeList = new OnetimeList();
onetimeList.on('sync', function(collection) {
console.log('collection is loaded', collection);
});
onetimeList.fetch();
This is a special collection object that will automatically synchronize its contents with Firebase.
You may extend this object, and must provide a Firebase URL or a Firebase reference as the
url
property.
Each model in the collection will have its own firebase
property that is its reference in Firebase.
For a simple example of using Backbone.Firebase.Collection
see todos.js.
var TodoList = Backbone.Firebase.Collection.extend({
model: Todo,
url: 'https://<your-firebase>.firebaseio.com/todos'
});
You may also apply an orderByChild
or some other
query on a
reference and pass it in:
var TodoList = Backbone.Firebase.Collection.extend({
url: new Firebase('https://<your-firebase>.firebaseio.com/todos').orderByChild('importance')
});
The url
property can be set with a function. This function must return a Firebase ref or a url.
var TodoList = Backbone.Firebase.Collection.extend({
url: function() {
return new Firebase(...);
}
});
Any models added to the collection will be synchronized to the provided Firebase. Any other clients
using the Backbone binding will also receive add
, remove
and changed
events on the collection
as appropriate.
You should add and remove your models to the collection as you normally would, (via add()
and
remove()
) and remote data will be instantly updated. Subsequently, the same events will fire on
all your other clients immediately.
Adds a new model to the collection. If autoSync set to true, the newly added model will be synchronized to Firebase, triggering an
add
and sync
event both locally and on all other clients. If autoSync is set to false, the add
event will only be raised locally.
todoList.add({
subject: 'Make more coffee',
importance: 1
});
todoList.on('all', function(event) {
// if autoSync is true this will log add and sync
// if autoSync is false this will only log add
console.log(event);
});
Removes a model from the collection. If autoSync is set to true this model will also be removed from Firebase, triggering a remove
event both locally and on all other clients. If autoSync is set to false, this model will only trigger a local remove
event.
todoList.remove(someModel);
todoList.on('all', function(event) {
// if autoSync is true this will log remove and sync
// if autoSync is false this will only log remove
console.log(event);
});
Creates and adds a new model to the collection. The newly created model is returned, along with an
id
property (uniquely generated by Firebase).
var model = todoList.create({bar: "foo"});
todoList.get(model.id);
todoList.on('all', function(event) {
// will log add and sync
console.log(event);
});
This is a special model object that will automatically synchronize its contents with Firebase. You
may extend this object, and must provide a Firebase URL or a Firebase reference as the url
property.
var Todo = Backbone.Firebase.Model.extend({
url: "https://<your-firebase>.firebaseio.com/mytodo"
});
You may apply query methods as with Backbone.Firebase.Collection
.
The urlRoot
property can be used to dynamically set the Firebase reference from the model's id.
var Todo = Backbone.Firebase.Model.extend({
urlRoot: 'https://<your-firebase>.firebaseio.com/todos'
});
// The url for this todo will be https://<your-firebase>.firebaseio.com/todos/1
var todo = new Todo({
id: 1
});
You do not need to call any functions that will affect remote data when autoSync
is enabled. Calling fetch()
will simply fire the sync
event.
If autoSync
is enabled, you should modify your model as you normally would, (via set()
and destroy()
) and remote data
will be instantly updated.
var RealtimeModel = Backbone.Firebase.Model({
url: 'https://<your-firebase>.firebaseio.com/mytodo',
autoSync: true // true by default
});
var realtimeModel = new RealtimeModel();
realtimeModel.on('sync', function(model) {
console.log('model loaded', model);
});
// calling .set() will sync the changes to firebase
// this will fire the sync, change, and change:name events
realtimeModel.set('name', 'Bob');
var RealtimeModel = Backbone.Firebase.Model({
url: 'https://<your-firebase>.firebaseio.com/mytodo',
autoSync: false
});
var realtimeModel = new RealtimeModel();
realtimeModel.on('sync', function(model) {
console.log('model loaded', model);
});
// this will fire off the sync event
realtimeModel.fetch();
// calling .save() will sync the changes to firebase
// this will fire the sync, change, and change:name events
realtimeModel.save('name', 'Bob');
Sets the contents of the model and updates it in Firebase.
MyTodo.set({foo: "bar"}); // Model is instantly updated in Firebase (and other clients)
Removes the model locally, and from Firebase.
MyTodo.destroy(); // Model is instantly removed from Firebase (and other clients)
If you'd like to contribute to BackboneFire, you'll need to run the following commands to get your environment set up:
$ git clone https://github.com/firebase/backbonefire.git
$ cd backbonefire # go to the backbonefire directory
$ npm install -g grunt-cli # globally install grunt task runner
$ npm install -g bower # globally install Bower package manager
$ npm install # install local npm build / test dependencies
$ bower install # install local JavaScript dependencies
$ grunt watch # watch for source file changes
grunt watch
will watch for changes to src/backbonefire.js
and lint and minify the source file when a
change occurs. The output files - backbonefire.js
and backbonefire.min.js
- are written to the /dist/
directory.
You can run the test suite via the command line using grunt test
.