backbone-dnode

<!doctype html> <html> <head> <meta http-equiv="content-type" content="text/html;charset=UTF-8" /> <meta http-equiv="X-UA-Compatible" content="chrome=1"> <title>backbone-dnode</title> <style> body { font-size: 16px; line-height: 24px; background: #F4EBF8; color: #022; font-family: Arial; font-family: "Palatino Linotype", "Book Antiqua", Palatino, FreeSerif, serif; } div.container { width: 720px; margin: 50px 0 50px 50px; } p, li { margin: 16px 0 16px 0; width: 550px; } p.break { margin-top: 35px; } a, a:visited { padding: 0 2px; text-decoration: none; background: #EDE1F2; color: #222; } a:active, a:hover { color: #000; background: #D8C8D9; } h1, h2, h3, h4, h5, h6 { margin-top: 40px; font-weight: bold; text-shadow: 1px 1px 1px #fff; } b.header { font-size: 18px; } span.alias { font-size: 14px; font-style: italic; margin-left: 20px; } table { margin: 16px 0; padding: 0; } tr, td { margin: 0; padding: 0; } td { padding: 9px 15px 9px 0; } td.definition { line-height: 18px; font-size: 14px; } code, pre, tt { font-family: Monaco, Consolas, "Lucida Console", monospace; font-size: 12px; line-height: 18px; background-color: #EDE1F2; color: #444; } tt { border: 1px solid #D5CADA; padding: 1px 2px; } code { margin-left: 20px; } pre { font-size: 12px; padding: 2px 0 2px 12px; border-left: 6px solid #B38AB5; border-left: 6px solid #6B536D; margin: 0px 0 10px; } li pre { padding: 0; border-left: 0; margin: 6px 0 6px 0; } #diagram { margin: 20px 0 0 0; } </style> </head> <body> <div class="container"> <h1>backbone-dnode  <sub style="font-size:150%;">&clubs;</sub></h1> <p> <a href="http://github.com/sorensen/backbone-dnode/">backbone-dnode</a> is an integration package between <a href="https://github.com/documentcloud/backbone">Backbone</a> and <a href="https://github.com/substack/dnode">DNode</a>, using <a href="https://github.com/learnboost/mongoose">Mongoose</a> for persistance, providing seemless server side CRUD and Pubsub support for your Backbone.js projects. </p> <p> <a href="docs/backbone-crud.html">The complete annotated source code</a> is also available. </p> <p> <a href="#introduction">Introduction</a> | <a href="#installation">Installation</a> | <a href="#usage">Usage</a> |  </p> <h2 id="introduction">Introduction</h2> <p> Backbone-DNode is a server to client integration package for use with, you guessed it, Backbone and DNode. The package brovides both node.js server side code for CRUD and Pubsub routines, as well as the matching client (or server) side routines. </p> <p> The idea is to make writing a real-time Backbone application as simple as possible, the app is supported on the server side by using the Mongoose ORM for final validation and persistence. </p> <p> The pubsub mechanics will default to using socket.io for updating the connected clients, however, you can pass a redis server and connection options to the pubsub <tt>config</tt> method to utilize the built in redis publish and subscribe methods. </p> <h2 id="installation">Installation</h2> <p> backbone-dnode depends on <b>Node.js</b> and the <b>Node Package Manager</b> (npm). If you don't already have these installed, grab the latest. Node releases can be found on the <a href="http://www.nodejs.org/#download">download page</a>. NPM can be installed with a script:<br /> <tt>curl http://npmjs.org/install.sh | sudo sh</tt> </p> <p> Install backbone-dnode via NPM:<br /> <tt>npm install backbone-dnode</tt> </p> <p> The project can be installed via NPM, or by cloning this repo into your project. </p> <pre> npm install backbone-dnode </pre> <p> or </p> <pre> git clone git://github.com/sorensen/backbone-dnode.git </pre> <h2 id="usage">Usage</h2> <p> There are two parts to using the backbone-dnode package, one part is to be used on the server, the other the client. </p> <h3>Server side</h3> <p> Whip up a server and attatch DNode, while using the backbone-dnode methods as middleware. </p> <pre> var express = require('express'), dnode = require('dnode'), middleware = require('backbone-dnode'), browserify = require('browserify'), server = express.createServer(); </pre> <p> Bundle the client side support files with browserify, then attatch it to the express server instance. DNode can be included directly into the bundle to avoid code duplication. </p> <pre> var bundle = browserify({ require : [ 'dnode', 'backbone-dnode' ], mount : '/core.js', }); server.use(bundle); </pre> <p> Register your Mongoose schemas, and then pass the database instance to the CRUD configuration. At least one mongoose schema must be registered to use the CRUD routines. </p> <pre> var Mongoose = require('mongoose'), Schema = mongoose.Schema, ObjectId = Schema.ObjectId; database = Mongoose.connect('mongodb://localhost/db'); Foo = new Schema({ bar : { type : String, index : true }, created : { type : Date, default : Date.now } }); middleware.crud.config(database); </pre> <p> Configure the Redis connection if you would like to use Redis as the pubsub mechanics. This will allow you to use other libraries such as Cluster, letting Redis act as the message queue. </p> <pre> var redis = require('redis'), pub = redis.createClient(), sub = redis.createClient(); middleware.pubsub.config(pub, sub); </pre> <h3>Client side</h3> <p> Include DNode and the browserified bundle, as well as the Backbone and underscore dependancies. </p> <pre> <script src="underscore.js"></script> <script src="backbone.js"></script> <script src="dnode.js"></script> <script src="backbone-dnode.js"></script> </pre> <p> Use browserify to <tt>require</tt> the backbone-dnode package, which will return a JSON object containing the CRUD and Pubsub middleware for DNode. Attatch both packages and then supply them the DNode <tt>remote</tt> object for server communication. </p> <pre> var dnode = require('dnode'); var middleware = require('backbone-dnode'); dnode() .use(middleware.crud) .use(middleware.pubsub) .connect(function(remote) { }); </pre> <p> To connect to node.js and mongoose from the browser (or on the server), a model <tt>type</tt> for mongoose must be specified, as well as overriding the <tt>sync</tt> method on each model, an underscore mixin has been created to provide optional support based on the model, in case you have different persistant support in mind. </p> <pre> Foo = Backbone.Model.extend({ type : 'foo', sync : _.sync }) </pre> <p> Now create the collection, the attributes are set on both the model and collection to ensure that they will both use the same persistance, even if a model is created outside of the collection. </p> <pre> FooCollection = Backbone.Collection.extend({ url : 'foos', type : 'foo', sync : _.sync, model : Foo }) </pre> <p> You can also override the sync method globally, by overriding the default <tt>Backbone.sync</tt> method </p> <pre> Backbone.sync = _.sync; </pre> <p> Once the middleware has been established, and a model has been set to use it (or if as been overridden globally), the default Backbone methods will automatically send the changes through the socket (dnode), where they will be mapped to the corresponding Mongoose schema, and then published to the connected clients that have been subscribed to the model or collection's URL. </p> <p> Backbone Models and Collections have been extended with a <tt>subscribe</tt> and <tt>unsubscribe</tt> method, which both take <tt>options</tt> and a callback function as arguments. You can pass a specific <tt>channel</tt> name in the options, which will be used as the pubsub channel and lookup key, if omitted, the collection will default to the set URL if one can be found. The methods will trigger a Backbone event when used unless <tt>silent : true</tt> is sent with the options. </p> <pre> var options = {}; var foos = new FooCollection(); foos.subscribe(options, function() { foos.fetch({ finished : function(data) { // The server has responded with the fetched data, // and has added to the collection }, }); }) </pre> <p> When the <tt>subscribe</tt> method has returned, you are now able to use all of the default Backbone model methods and have them interact with the server. When using any of the Backbone <tt>fetch</tt>, <tt>save</tt>, <tt>create</tt>, or <tt>delete</tt> methods, a callback function will be used when the server responds, and a <tt>finished</tt> method will be executed when the middleware is done with the Backbone integration methods. Can optionally pass in an <tt>error</tt> method that will be triggered if anything goes wrong on the server side. Think of <tt>finished</tt> as the Backbone <tt>success</tt> callback when normally using these methods, the name is changed to avoid conflicts. </p> <pre> foos.create({ bar : 'something' }); </pre> <p> Backbone.fetch() has been overloaded to accept a <tt>query</tt> and <tt>sorting</tt> argument, which will be directly used on the server against the Mongoose ORM. The default behavior for passing in <tt>silent:true</tt> or <tt>add:true</tt> will still be used. </p> <pre> foos.fetch({ query : { bar : 'something' }, sorting : { sort: [['created',-1]], limit: 20 } }); </pre>  <p> <br /> A <b class="header">Beau Sorensen</b> project. </p> </div> </body> </html>