halo

Halo

This library makes it quick and easy to build a real-time node backend for Backbone.js clients using Socket.io as the communication protocol.

Installation

npm install halo

Quick Start/Example

Back-end

First, require halo

var Halo = require("halo");

Next, create a model by calling the extend method on Halo.model. You can give it an any properties and classProperties you'd like. You can also give it a constructor (called an initializer). If you override the default constructor of Halo.model, make sure to call the parent constructor using this.parent(Halo.Model).constructor somewhere in your function.

var MyModel = Halo.Model.extend({
  initializer : function(options) {
    
    // Call the parent pseudo-class's constructor.
    this.parent(Halo.Model).constructor(options);
    
    // Initialize your model
  },

  properties : {
    defaults : {
      someProperty : "a default value"
    },

    someMethod : function() {
      // Do some stuff
    },
    
    someOtherMethod : function() {
      // Do some other stuff
    }
  }
});

Assign a collection to the new model class. Anytime this model is instantiated, that instance will be added to the collection you specify here.

MyModel.collection = new Halo.Collection({contains: MyModel});    

Next, create a View for this model. The View specifies how your model is represented to front-end clients and how those clients are permitted to interact with the model.

var MyModelView = Halo.views.socket.Model.extend({
  properties : {
    
    // The name string should be used as your Backbone.js Model's URL.
    name : "MyModels", 
    obj : MyModel,
    
    // This dictionary defines what your front-end clients have 
    // permission to do. Possible values include: 
    // create, read, update, destroy, list
    routes : {
      'create'  : 'create',
      'read'    : 'read',
      'update'  : 'update',
      'list'    : 'list'
    },

    // If you have custom logic for a given action, just
    // provide a function with the name of the action.
    update : function(client, data) {
      
      var myModel = MyModel.collection.get(data.id);

      if (!myModel.get('someProperty' !== "a default value")) {
        
        // When setting properties on a model, you can pass in
        // an array limiting the names of the properties to set.
        myModel.set(data, ['someProperty']);
      }
      return this.render(client, myModel, data);
    }
  }
});

To allow front-end clients to interact with the view, you must create a router and register the view with it.

var router = new Halo.Router();
router.addView(new MyModelView());
router.listen(80);

Front-end

In your front-end app, include Socket.io and the Halo.sync.js Backbone extension using the following URLs. These URLs are automatically made available once router.listen() is invoked.

<script src="/socket.io/socket.io.js"></script>
<script src="/halo/halo.sync.js"></script>

Now your Backbone models and collections can be bound to any Halo models or collection that have view objects registered with the Halo router.

var MyBackboneModel = Backbone.Model.extend({
  url: function() { return "MyModels"; }
});

For example, if you created a Backbone model that returned "MyModels" as the URL, which corresponds to the "name" property of the MyModelView, any time a client saved a change to a MyModel instance, that change will get pushed to all other clients who have a copy of that instance of MyModel. Similarly, creating new MyModels will add that new instance to any Backbone collection connected to MyModels.

Attribution/Credits

The code for Halo.sync was heavily borrowed from Backbone.ioBind, created by Jake Luer, and distributed under the MIT license. You can find his original library at http://alogicalparadox.com/backbone.iobind/ https://github.com/logicalparadox/backbone.iobind

License

Released under the MIT license. See file called LICENSE for more details.