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

• Socket.io 0.7.x || 0.8.x
• Backbone 0.5.x

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.

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);

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.

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

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.