(Note: The code for this project at this point in our progress can be downloaded from Github at commit: e55dbc2be4ab5e8ce883ad7e397654e346f5d135)

Getting Our Users and Displaying Them

Today, we are going to access our REST backend using Backbone's Collection object and display the results on screen. To do this, we'll add a link to our navigation section in the header, create a view to display the results, and update the router to include those results in our page layout.

Navigation

Let's go ahead and update /app/page/header.hbs'. Between the navbar-header div and the navbar-right div, add

<ul class="nav navbar-nav">  
    <li><a href="#users"><span class="fa fa-users"></span> Users</a></li>
</ul>  

You'll notice there are some 'fa' classes in there. That's because I added FontAwesome to the mix. Use bower to install it

bower install font-awesome --save  

then add the CSS to your index page

<link rel="stylesheet" href="components/font-awesome/css/font-awesome.css">  

For our navigation, we used a standard A anchor tag with a URL that mimics our REST API URL. There is no technical need to keep them the same (and in fact they are not - our UI does not expose the /api portion) but keeping them aligned is a useful organizational tool. You should also notice that the URL begins with a hash. Backbone, by default, uses Hash URLs. They are more backwards compatible with older browsers that do not support Push State. Normal URLs are preferred and we'll convert this one later on to take advantage of them.

Creating our Model and Collection

Backbone provides some base objects that we can use to contain our model object (a User) and a collection of them. By giving these objects a URL, they will know how to interact with a standard REST API to retrieve and persist the objects. Let's create them now.

/app/users/model.js

define(function (require) {

    'use strict';
    var Backbone = require('backbone');

    return Backbone.Model.extend({
        idAttribute: '_id',
        urlRoot: '/api/users'
    });
});

Here we are setting two properties, idAttribute, which lets Backbone know to use the MongoDB generated value _id as the id for the object, and urlRoot, which tells it the base URL to use when constructing REST calls.

/app/users/collection.js

define(function (require) {

    'use strict';
    var Backbone = require('backbone');
    var Model = require('users/model');

    return Backbone.Collection.extend({
        model: Model,
        url: '/api/users'
    });
});

Again, we are setting two properties. model is the Backbone model of the objects in the collection - in our case the User model. url is the REST API url to retrieve the collection from.

Displaying The Collection

In my apps, I have two different ways to think about displaying a collection of objects. In cases such as our User collection, it is primarily a tabular display of data. It can show all or a portion of the model's properties, and usually presents actions such as Edit or Delete. In cases such as these, I don't expect the collection to be changing underneath the user without explicit interaction.

Other collections, however, could be more dynamic. Suppose you are looking at a live stream of tweets that are getting continually updated. Perhaps the collection represent pieces in a game that are getting moved around based on rules. In cases like that, we will want to construct a collection view that delegates a lot of control to individual model views and can respond to events that they generate.

For CRUD screens like the one we are going to build, we can use the DataTables library to easily add features like sorting, pagination, and filtering to our view.

Install DataTables and a convenient plugin to mix it in with our Bootstrap theme:

bower install datatables datatables-bootstrap3-plugin --save  

update require-main.js with the following entries

"datatables": "../components/datatables/media/js/jquery.dataTables",
"datatables-bootstrap3": 
    "../components/datatables-bootstrap3-plugin/media/js/datatables-bootstrap3"

and add the CSS to index.html

    <link rel="stylesheet" href="components/datatables-bootstrap3-plugin/media/css/datatables-bootstrap3.css">

Now let's create our template and view

/app/users/list.hbs

<div class="well">  
    <h4><b>Users</b></h4>
</div>  
<table class="table table-bordered table-striped">  
    <thead>
    <th>ID</th>
    <th>Email</th>
    <th>Name</th>
    </thead>
    <tbody>
    {{#each users}}
        <tr>
            <td>{{_id}}</td>
            <td>{{email}}</td>
            <td>{{name}}</td>
        </tr>
    {{/each}}
    </tbody>
</table>  

A fairly straightforward table template. We'll use Handlebars #each directive to loop over the users and display a row for each.

/app/users/listView.js

define(function (require) {

    'use strict';
    var Backbone = require('backbone');
    var template = require('hbs!users/list');
    require('datatables');
    require('datatables-bootstrap3');

    return Backbone.View.extend({
        el: '#content',
        render: function(){
            this.$el.html(template({users: this.collection.toJSON()}));
            this.$('table').DataTable();
            return this;
        }
    });

});

Some differences to call out. We've required our DataTables related libraries but did not assign them to a variable. Since they are plugins to jQuery, we won't need to access them on their own.

In our render method, we take our collection of users, convert them to JSON and pass that in as users to our template to render. This is the object that the #each directive is looping on in our template.

Finally, we activate the DataTables functionality by attaching it to the table in our view.

The only thing that may not be clear is where the collection we convert to JSON is coming from since we did not define it in this view. We could have instantiated it here, and asked it to fetch itself. We would then have to coordinate with our Page view to tell it that the collection was ready, and to rerender it. In some cases, such as when many different backend calls will need to be made to display a page, this will be an appropriate solution. For this simple case, we'll have the router grab the collection and prepare the view before we hand it off to the main Page. This way, it will be ready to render right away. Let's take a look at that:

/app/router.js

routes: {  
    '': 'home',
    'home': 'home',
    'users': 'users'
},

users: function() {  
    console.log('routing - users');
    require(['users/collection', 'users/listView'], function(Collection, View) {
        var collection = new Collection();
        collection.fetch().done(function(){
            mediator.trigger('page:displayView', new View({collection: collection}));
        });
    });
},

We've added a route for users that is handled by a users method and the users method itself. We require the users view and collection. We instantiate the collection and fetch the contents. When the contents are retrieved we add them a new view and send a message off to the page to render the view.

Next Steps

In the next installment, we'll some actions to add, edit, and delete users.

(Note: The code for this series is available on Github - To get the code in preparation for this installment, checkout commit: d82adb485a608278b2003415cab536503c40d5d2)

Database Integration

A lot of tutorials wave their hands at this point and assume you have a database connected. Worse, some will have you write stubs and timeouts to simulate connection delays. If you know what you're doing, these can be a quick way to get a screen or feature running. If you're building from the ground up, you're just delaying the inevitable. Plus, if you've never done it before, figuring out how to wire it in later can be a challenge.

MongoDB and mongoose

Earlier in this series we installed MongoDB. Ensure that you have a running copy before continuing. For a GUI front end, I like using MongoHub. Mongoose is an object modeling solution that lets you write simple schema based objects to work between your Node server and your Mongo database. It has hooks for validation, query building and more, and with a healthy plugin ecosystem can do nearly anything you throw at it. We'll only scratch the surface of its feature set.

To install mongoose, run:

npm install mongoose --save  

We'll need to tell our app how to connect to MongoDB. In our server.js file, add

var mongoose = require('mongoose');  

to the dependencies section at the top. Then underneath that, add

mongoose.connect('mongodb://localhost:27017/rlbb');  

If you configured MongoDB to run on another port, edit the above the string. rlbb is the name of our database and will be created if not present. Here is also where we would add things like database username, password, and the like if we had them.

Now, let's create a User model. Under app/models, create user.js

var mongoose = require('mongoose');  
var Schema = mongoose.Schema;

var UserSchema = new Schema({  
    name: String,
    email: {type: String, required: true, index: {unique: true}},
    password: {type: String, required: true, select: false}
});

module.exports = mongoose.model('User', UserSchema);  

Here, we've pulled in our mongoose dependency and created a User Schema object. Mongoose uses the Schema as representation of a MongoDB collection and the base of its functionality. We've defined a name, an email, and a password. Along with the property names, we've defined their SchemaType, in this case, they are all Strings. For email and password, we've also included some additional properties. required indicates that the field must be present to be valid. Other validators include min, max, match, and custom validators can be created. For email, which we will use as our username, we create an index for it, and put a unique constraint on it. For password, we indicate that normal retrieval of this object from the collection should not include the password field. This prevents it from going across the network. When we add authentication later, we will explicitly ask for the password. Finally, we create a mongoose model from the schema and export it.

Our First REST Endpoints

So, we have a model of our User data. We now need a way to retrieve it from and write it to the database. In this app, all of our API URLs will start with /api/ and then follow with the appropriate REST endpoints. For user, we will end up creating:

/api/users

POST - With a POST request, a new user will be created.
GET - With a GET request, this will return all users.

/api/users/:user_id

GET - With a GET request, this will return a single user with an ID that matches :user_id.
PUT - With a PUT request, the user indicated will be updated.
DELETE - With a DELETE request, the user indicated will be deleted.

With just two endpoints, and using the HTTP verbs, we can satisfy our basic CRUD requirements. To define these, we will create an Express router and then have Express use it, much like we did with the static assets directory and the catch all request handler.

Under app/routes, create user.js ¹.

var bodyParser = require('body-parser');  
var User = require('../models/user');

module.exports = function (app, express) {  
    var userRouter = express.Router();

    userRouter.get('/', function (req, res) {
        res.json({message: 'api is loaded'});
    });

    userRouter.route('/users')
        .post(function (req, res) {
            var user = new User();
            user.name = req.body.name;
            user.username = req.body.username;
            user.password = req.body.password;

            user.save(function (err) {
                if (err) {
                    if (err.code === 11000) {
                        return res.json({success: false, message: 'Duplicate username.'});
                    } else {
                        return res.send(err);
                    }
                } else {
                    res.json({message: 'user created'});
                }

            });
        })
        .get(function (req, res) {
            User.find(function (err, users) {
                if (err) {
                    res.send(err);
                }
                res.json(users);
            })
        });

    userRouter.route('/users/:user_id')
        .get(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);
                res.json(user);
            })
        })
        .put(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);

                if (req.body.name) user.name = req.body.name;
                if (req.body.email) user.email = req.body.email;
                if (req.body.password) user.password = req.body.password;

                user.save(function (err) {
                    if (err)res.send(err);
                    res.json({message: 'user updated'});
                });
            });
        })
        .delete(function (req, res) {
            User.remove({_id: req.params.user_id}, function (err, user) {
                if (err) res.send(err);
                res.json({message: 'user deleted'});
            })
        });

    return userRouter;
};

This looks like a lot, but it's fairly straightforward. Let's tackle it a chunk at a time.

var bodyParser = require('body-parser');  
var User = require('../models/user');  

Here will pull in our dependencies. We will use body-parser to get the data that comes with the PUT and POST requests and User is the user model we just created.

    var userRouter = express.Router();

    userRouter.get('/', function (req, res) {
        res.json({message: 'api is loaded'});
    });

Here we create an instance of an Express router. To give us a way to verify our routes have been initialized properly, we create a default route api/ that will respond with a canned message. If there are problems we can use this to see if it is a server or database issue.

userRouter.route('/users')  
        .post(function (req, res) {
            var user = new User();
            user.name = req.body.name;
            user.email = req.body.email;
            user.password = req.body.password;

            user.save(function (err) {
                if (err) {
                    if (err.code === 11000) {
                        return res.json({success: false, message: 'Duplicate username.'});
                    } else {
                        return res.send(err);
                    }
                } else {
                    res.json({message: 'user created'});
                }

            });
        })
        .get(function (req, res) {
            User.find(function (err, users) {
                if (err) {
                    res.send(err);
                }
                res.json(users);
            })
        });

Here we create the api/users route and handle both the POST and the GET cases. In the POST block, we create a new User, set the fields with data from the request body, and save it. Mongoose handles the heavy lifting of creating the query and talking to the database. We perform some basic error-handling, and return an appropriate message to the client.

In the GET block, we call a static model method on User to retrieve all the stored users and return them. Once again, mongoose takes care of the details.

userRouter.route('/users/:user_id')  
        .get(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);
                res.json(user);
            })
        })
        .put(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);

                if (req.body.name) user.name = req.body.name;
                if (req.body.username) user.username = req.body.username;
                if (req.body.password) user.password = req.body.password;

                user.save(function (err) {
                    if (err)res.send(err);
                    res.json({message: 'user updated'});
                });
            });
        })
        .delete(function (req, res) {
            User.remove({_id: req.params.user_id}, function (err, user) {
                if (err) res.send(err);
                res.json({message: 'user deleted'});
            })
        });

Here we create the api/users/:user_id route. Express will take the value in the request that maps to the :user_id section and create a request parameter that we can use. In the GET block, we use mongoose's findById method to retrieve a specific user. In the PUT block, we again retrieve the requested user, update its information with data from the request body, then save it. Finally, in the DELETE block, we use mongoose's remove function to delete the specified user.

Now it's time to wire the router into the server. In server.js, after the static directory declaration, add the following

// already in our file
app.use(express.static(__dirname + '/public'));

// ADD THESE TWO LINES
var userRoutes = require('./app/routes/user')(app, express);  
app.use('/api', userRoutes);

// already in our file
app.get('*', function(req,res){  
    res.sendFile(path.join(__dirname + '/public/index.html'));
});

First we create the routes, by requiring the file and passing it the two needed fields, app and express. (Go back and look at how we declared our router definition and you will see we have these two params listed). Then, we tell our server to use the routes. Remember, order is important. First our static files, then our API routes, and finally the catch all to serve up our home page. If we added our routes after the catch all, they would never be hit.

If we were to run our server now, with nodemon server.js we would be able to get and set users via HTTP. But... we don't have any users yet, and we don't have screens to input data. Any easy solution is to use something like Postman - REST Client for Chrome (all the browsers have similar tools). In the URL field, enter localhost:1337/api and make sure GET is selected in the dropdown. When you hit send, you should see our test message returned in JSON format.

We can do a similar task to add a user. Set the URL to localhost:1337/api/users, the method to POST, select raw for our input data and add

{ "email" : "hireme@brianmajewski.com", name: "Brian M", password: "123456Secure!"}

These are the fields we defined on our User model.

We also need to set our content type, so select Headers, and for name put Content-Type and value put application/json. If we're configured right, you should get a response back saying user created. To see our new user, hit the same URL, with GET, and you should receive a response similar to

[
    {
        "_id": "54e6b162eb2ac61c54e9b80f",
        "email": "hireme@brianmajewski.com",
        "name": "Brian M",
        "__v": 0
    }
]

Notice: Our password is not returned, as we specified in our schema. Experiment with the other routes and verify that you can update and delete users as well.

So there you have the basics for all CRUD operations for your app. Whether you are storing Widgets, Gizmos, Comments, or Reviews, you will follow the same basic pattern. Later, when we add authentication, you'll see how we can enhance mongoose's standard methods to perform extra functionality, such as encrypting the password, before saving the user.

To get the code with these updates checkout commit 18b0d51ee45d966abf9293be9a5fe25c6af8c6a6

Next Steps

With a functional backend in place, we will begin to create our front end web application. We'll look at using Bower to manage dependencies and RequireJS to load modules.

(UPDATE: There was a bug in the PUT block of the /users/:user_id route - username should have been email - This bug was fixed in the Chapter 7 version of the code on Github and in the text above)

Project Structure

We are going to start with a simple barebones structure to start with. In your project directory create both an app and a public directory. Under, public, create assets. And we're done. We'll add more as we flesh out the app. I like working iteratively, adding what we need when we need it. Remember, it's software - we can change it if we want to.

NPM (Node Package Manager)

To manage our server side dependencies, we are going to use Node's built-in package manager NPM. To start, we need a package.json file. You can read the docs and create one by hand or you can use the tool to create one. Run

npm init

in the root of your project, answer the questions, et voila, you should have a package.json file that looks something like this:

If you entered something other than server.js for the main value (and you probably did, since it isn't the default), go ahead and edit the contents. server.js will be the main file we run to launch our web server and serve up data.

For our barebones server, we are going to use the following node packages: express, body-parser, morgan, and live

express

will provide nearly all of the web server functionality along with the middleware we will need to do authentication.

body-parser

will allow us to read json from incoming request

morgan

will let us log incoming requests

Learning how to use Express would be a lesson in itself and you should dig into their documentation as needed.

To install these, run

npm install express body-parser morgan --save

from your project root. It will download the packages, and their dependencies, and save the information to your package.json file.

One last package we want to download is nodemon. When our server is running, this will watch for any changes and restart the server automatically as needed. We need to install this globally, so run:

npm install -g nodemon

server.js

This will be the heart of our web server.

var express = require('express');  
var bodyParser = require('body-parser');  
var morgan = require('morgan');

var path = require('path');

var app = express();

// Sets us up to read body content from POST requests
app.use(bodyParser.urlencoded({extended: true}));  
app.use(bodyParser.json());

// Adds request logging
app.use(morgan('dev'));

// Sets up the server to serve static files from the public directory
app.use(express.static(__dirname + '/public'));

// For all requests we do not explicitly handle (*), return index.html
app.get('*', function(req,res){  
    res.sendFile(path.join(__dirname + '/public/index.html'));
});


// Listen on port 1337
var port = 1337;  
app.listen(port);  
console.log('Server up and running on port ' + port);  

So, what's going on here?

• First we define our dependencies and create an app variable to represent the application/server.
• Then, we use the body-parser package to tell our app how to get JSON from the body of incoming requests.
• We activate morgan in dev mode, which will log our requests.
• We define a directory to serve up static resources like html, css, fonts, etc. __dirname is provided by the path package.
• Finally, for all incoming requests that have not been handled yet(*), we return index.html. So, if we ask for a specific CSS file, the static instruction above will handle it. If we ask for an HTML page that doesn't exist, this instruction will handle it. We will be adding more routes and instructions as we go on. As you can see, the order in which we define these routes is important. Express will go through each one until it comes to a handler that satisifes the request. This is a classic implementation of the chain of responsibility pattern.

That's it. That's all you need to have a basic web server. We could have left out the body-parser section for an even leaner file, but we will need it next. Run

nodemon server.js

and you should see output similar to:

We can create a simple index.html file in our public directory and view it in a browser. To ensure that static files are being served up as well, create a css folder under assets and add a styles.css file.

Sample HTML

<!DOCTYPE html>  
<html>  
<head lang="en">  
    <base href="/">
    <meta charset="UTF-8">
    <title>Relearning Backbone</title>
    <link rel="stylesheet" href="assets/css/styles.css">
</head>  
<body>  
<h3>Relearning Backbone</h3>  
</body>  
</html>  

Sample CSS

h3 {  
    color: #4169e1;
}

Next Steps

Next time, we are going to add a database connection to the server, and some User entities to it.