Simple example - Node.js, Restify, MongoDb and Mongoose:

Simple example - Node.js, Restify, MongoDb and Mongoose

Before I start, the Backbone.js parts of this tutorial will be using techniques described in "Organizing your application using Modules to construct a simple guestbook.

Getting started

To easily understand this tutorial you should jump straight into the example code base.

Example Codebase

Example Demo

This tutorial will assist you in saving data(Backbone.js Models) to MongoDb and retrieving a list(Backbone.js Collections) of them back.

The technologies

This stack is great for rapid prototyping and highly intuitive. Personal note: I love using JavaScript as my only language for the entire application (FrontEnd/BackEnd/API/Database). Restify is still in early development but is essentially just an extension of Express. So for anyone needing more stability you can easily just substitute Express in.

Node.js

"Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices."

Restify

"Restify is a node.js module built specifically to enable you to build correct REST web services. It borrows heavily from express (intentionally) as that is more or less the de facto API for writing web applications on top of node.js."

MongoDb

"MongoDB (from "humongous") is a scalable, high-performance, open source NoSQL database."

Mongoose

"Mongoose is a MongoDB object modeling tool designed to work in an asynchronous environment."

Building the server

In the example repository there is a server.js example which can be executed by running node server.js. If you use this example in your own applications make sure to update the Backbone.js Model and Collection definitions to match your server address.

Restify configuration

The first thing to do is require the Restify module. Restify will be in control of handling our restful endpoints and returning the appropriate JSON.

var restify = require('restify');  
var server = restify.createServer();
server.use(restify.bodyParser());

Note: bodyParser() takes care of turning your request data into a JavaScript object on the server automatically.

MongoDb/Mongoose configuration

We simply want to require the MongoDb module and pass it a MongoDb authentication URI e.g. mongodb://username:server@mongoserver:10059/somecollection

The code below presupposes you have another file in the same directory called config.js. Your config should never be public as it contains your credentials. So for this repository I have added config.js to my .gitignore but added in a sample config.

var mongoose = require('mongoose/');
var config = require('./config');
db = mongoose.connect(config.creds.mongoose_auth),
Schema = mongoose.Schema;

Mongoose Schema

Mongoose introduces a concept of model/schema enforcing types which allow for easier input validation etc

// Create a schema for our data
var MessageSchema = new Schema({
  message: String,
  date: Date
});
// Use the schema to register a model with MongoDb
mongoose.model('Message', MessageSchema); 
var Message = mongoose.model('Message');

Note: Message can now be used for all things CRUD related.

Setting up the routes

Just like in Backbone, Restify allows you to configure different routes and their associated callbacks. In the code below we define two routes. One for saving new messages and one for retrieving all messages. After we have created our function definitions, we attach them to either GET/POST/PUT/DELETE on a particular restful endpoint e.g. GET /messages

// This function is responsible for returning all entries for the Message model
function getMessages(req, res, next) {
  // Resitify currently has a bug which doesn't allow you to set default headers
  // This headers comply with CORS and allow us to server our response to any origin
  res.header("Access-Control-Allow-Origin", "*"); 
  res.header("Access-Control-Allow-Headers", "X-Requested-With");
  // .find() without any arguments, will return all results
  // the `-1` in .sort() means descending order
  Message.find().sort('date', -1).execFind(function (arr,data) {
    res.send(data);
  });
}



function postMessage(req, res, next) {
  res.header("Access-Control-Allow-Origin", "*");
  res.header("Access-Control-Allow-Headers", "X-Requested-With");
  // Create a new message model, fill it up and save it to Mongodb
  var message = new Message();
  message.message = req.params.message;
  message.date = new Date();
  message.save(function () {
    res.send(req.body);
  });
}

// Set up our routes and start the server
server.get('/messages', getMessages);
server.post('/messages', postMessage);

This wraps up the server side of things, if you follow the example then you should see something like

http://backbonetutorials.nodejitsu.com/messages

Note: Again you must remember to change the Model and Collection definitions to match your server address.

Setting up the client (Backbone.js)

I've actually used the latest copy of http://backboneboilerplate.com to set up the example page.

The important files you will want to check out are;

views/dashboard/page.js
views/guestbook/form.js
views/guestbook/list.js
models/message.js
collections/messages.js
templates/guestbook/

Saving a message

First of all we want to setup a template for showing our form that creates new messages.

<textarea class="message"></textarea>
<button class="post-message">Post Message</button>

This template gets inserted into the DOM by views/guestbook/form.js, this Backbone view also handles the interaction of the form and the posting of the new data.

Let us create a Backbone Model that has the correct URL for our restful interface.

define([
  'underscore',
  'backbone'
], function(_, Backbone) {
  var Message = Backbone.Model.extend({
      url: 'http://localhost:8080/messages'
  });
  return Message;
});

We can see how we require our predefined model for messages and also our form template.

define([
  'jquery',
  'underscore',
  'backbone',
  'models/message',
  'text!templates/guestbook/form.html'
], function($, _, Backbone, MessageModel, guestbookFormTemplate){
  var GuestbookForm = Backbone.View.extend({
    el: '.guestbook-form-container',
    render: function () {
      $(this.el).html(guestbookFormTemplate);
      
    },
    events: {
      'click .post-message': 'postMessage'
    },
    postMessage: function() {
      var that = this;

      var message = new MessageModel();
      message.save({ message: $('.message').val()}, {
        success: function () {
          that.trigger('postMessage');
        }
      });
    }
  });
  return GuestbookForm;
});

Note: trigger is from Backbone Events, I binded a listener to this view in views/dashboard/page.js so when a new message is submitted, the list is re-rendered. We are setting the date of the POST on the server so there is no need to pass it up.

Retrieving a list of messages

We setup a route on our server to generate a list of all available messages at GET /messages. So we need to define a collection with the appropriate url to fetch this data down.

define([
  'jquery',
  'underscore',
  'backbone',
  'models/message'
], function($, _, Backbone, MessageModel){
  var Messages = Backbone.Collection.extend({
    model: MessageModel, // Generally best practise to bring down a Model/Schema for your collection
    url: 'http://localhost:8080/messages'
  });

  return Messages;
});

Now that we have a collection to use we can setup our views/list.js to require the collection and trigger a fetch. Once the fetch is complete we want to render our returned data to a template and insert it into the DOM.

define([
  'jquery',
  'underscore',
  'backbone',
  'collections/messages',
  'text!templates/guestbook/list.html'
], function($, _, Backbone, MessagesCollection, guestbookListTemplate){
  var GuestbookList = Backbone.View.extend({
    el: '.guestbook-list-container',
    render: function () {
      var that = this;
      var messages = new MessagesCollection();
      messages.fetch({
        success: function(messages) {
          $(that.el).html(_.template(guestbookListTemplate, {messages: messages.models, _:_}));
        }
      });
    }
  });
  return GuestbookList;
});

The template file should iterate over messages.models which is an array and print out a HTML fragment for each model.

<% _.each(messages, function(message) { %>

<p><%= message.get('message') %></p>
<em><%= message.get('date') %></em>

<% }); %>

This actually sums up everything you need to know to implement this simple example.

Conclusion

Example Codebase

Example Demo

In this example you should really be using relative URL's in your collections/models and instead setting a baseUrl in a config file or by placing your index.html file on the restful server.

This example is hosted on GitHub therefore we had to include the absolute URL to the server which is hosted on nodejitsu.com

On a personal note, I have of recent used the Joyent, Nodejitsu, MongoDbHq stack after they have now partnered up and I have nothing but good things to say. Highly recommend you check it out!

As always I hope I made this tutorial easy to follow!

Get in touch with me on twitter, comments or GitHub!

Relevant Links

Organizing Your Backbone.js Application With Modules

Many Simple Models over One Complicated Model:

I see it again and again.
When they have invested time and energy in a model (tool, framework, method), people have a tendency to make their models more and more complicated. “Let’s add another dimension.” “Let’s deepen the domains.” “Let’s add some columns or swim lanes.” “Let’s draw an extra diagram.”
But complexity thinkers know better. They understand you need different approaches for different contexts. It is better to apply different models to different problems.

Each systems approach is useful for certain purposes and in particular types of problem situation. A diversity of approaches, therefore, heralds not a crisis but increased competence in a variety of problem contexts.

- Michael C. Jackson, Systems Thinking

This means it makes more sense to use multiple simple models instead of one complicated model. Having a toolkit of methods and frameworks, which each fail in their own way, is a smarter approach than relying on one method or framework to deal with all situations.

Complexity itself is anti-methodology. It is against "one size fits all."

- Tom Petzinger, Interaction of Complexity and Management

Of course, it’s very human to hold on to the model you had already invested in. In behavioral economics it’s called the endowment effect. We value more what we already have, because we own it. It’s irrational, but natural. And especially those who have created their own method or framework, will usually cling on to it like Bashar Hafez al-Assad to his presidential chair.

The more work you put into something, the more ownership you begin to feel for it.

- Daniel Ariely, Predictably Irrational

It makes sense to realize that holding on to your favorite method or framework is predictably irrational. The sensible thing to do is to invest in multiple models, and multiple approaches.
Don’t extend your diagram to accommodate an extra dimension. Just erase it, and start from scratch.
(image: House Democrats' Health Plan)