Installation
Download and include in your projects.
<script src="/js/backbone.iosync.js"></script>
<script src="/js/backbone.iobind.js"></script>
Or use the minimized versions.
<script src="/js/backbone.iosync.min.js"></script>
<script src="/js/backbone.iobind.min.js"></script>
Dependancies
Backbone.sync Replacement
The Backbone.sync replacement for socket.io, backbone.iosync.js
, is a drop-in replacement for Backbone.sync that
will make Backbone use socket.io for all normal CRUD operations. By this, anytime you save
a model,
fetch
a collection, remove
a model, or other database operation, socket.io will be used as the
transport.
Namespaces / Urls
Backbone has a dedicated attribute, urlRoot
for models, and url
for collections, that is used
by the default sync method to direct AJAX request. ioSync uses this same attribute to create a
namespace tag for that model.
For Example: If your collection url is 'posts' or '/posts', the events to listen for server-side will be:
posts:create
posts:read
posts:update
posts:delete
As with the default sync method, for a given model, ioSync will default to the url
of the collection
that model is a part of, else it will use the models urlRoot
.
If your url has a depth of more than one, only the first will be used. Example: /posts/comments
will still only have a namespace of posts
.*
RPC / Callbacks
This replacement assumes that you are using socket.io's RPC (callback) formula for these events. Examine this psuedo-code:
socket.on('posts:read', function (data, callback) {
db.query({_id: data.id}, function (err, model) {
if (err) {
callback(err);
} else {
// ... some data scrubbing
callback(null, model);
}
});
});
The callback accepts two parameters: error
and model
. If no error has occurred, send null
for error
.
The model
should be a JSON representation of the client-side model's attributes.
Binding Custom Events
The primary function for Backbone.ioBind is to make it easy to create client-side listeners for server-side socket.io events. The most likely use case for this is to broadcast changes made by one client to all other clients watching a particular data object.
The following samples are from the example app that demonstrates a very basic usage scenario.
ioBind
The ioBind function is available for both Models and Collections, and behaves identically in both scenarios.
// Example Model.extend
urlRoot: 'todo',
socket: window.socket,
initialize: function () {
_.bindAll(this, 'serverChange', 'serverDelete', 'modelCleanup');
this.ioBind('update', this.serverChange, this);
this.ioBind('delete', this.serverDelete, this);
}
// Example Collection.extend
url: 'todos',
socket: window.socket,
initialize: function () {
_.bindAll(this, 'serverCreate', 'collectionCleanup');
this.ioBind('create', this.serverCreate, this);
}
The primary difference between ioBind
on Models and Collection is the event string that is listened for.
On models, the event string includes the Model id
, whereas on collection it is simply the collection namespace.
The above example will respond to the following socket.io events.
// Model events
socket.emit('todo/' + todo_obj.id + ':update', todo_obj);
socket.emit('todo/' + todo_obj.id + ':delete', todo_obj);
// Collection events
socket.emit('todos:create', todo_obj);
Usage Guideline
Model binding without ID: Do NOT bind to Models that do NOT have an id
assigned. This will cause for extra listeners
and cause potentially large memory leak problems. See the example app for one possible workaround.
Namespace construction: When constructing the namespace, as with the the ioSync method, for a given model ioBind
will default to the url
of the collectionthat model is a part of, else it will use the models urlRoot
.
Reserved events: Do NOT bind to reserved backbone events, such as change
, remove
, and add
. Proxy these
events using different event tags such as update
, delete
, and create
.
Example App
Overview
Done. is a task application that keeps itself synchronized across all browser instances. This app was built to demonstrate the basic usage of Backbone.ioBind and ioSync. The code is intended to be easy to follow and is heavily commented.
Installation
To start off, you are going to need to clone the repo.
$ git clone https://github.com/logicalparadox/backbone.iobind.git
Before you can run anything you need to install the dev dependancies, such as Express, Seed, and Socket.io.
$ cd backbone.iobind
$ npm install
Optionally, you should install the build tool, should you want to make changes to backbone.iobind or backbone.sync for socket.io. The tool used is jake
and it should be installed in the global npm space.
$ [sudo] npm -g install jake
If you installed jake, then simply run the following command to start up the example app.
$ jake serve
Note: jake -T
shows you a list of all available commands.
If you did not install jake, then start up the example app using node.
$ node example/app.js
For Contributors
Please avoid making changes to the dist
versions of backbone.iobind. All changes to the library are to be
made to lib/*.js
and then packaged for the browser using the build tools.
Building
Build tool is built in jake.
[sudo] npm install jake -g
Clone this repo:
git clone https://github.com/logicalparadox/backbone.iobind
Install development/build dependancies (Ie: folio.:
npm install
Run jake
jake
for detailed information, jake build:all
to build all files.