(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 project at this point in our progress can be downloaded from Github at commit: 82df0f2fd5bdc91d5599aa1c40faacca38766327)

Deep Breath

This is going to be a lengthy installment. We've done a lot of setup, including creating a fully functioning server with REST endpoints and wiring up our front-end dependency management. Today, we are going to make a lot of small steps that when put together will give us a completely functional single page application with routing, an event bus, and dynamic views. Let's start by adding our third party dependencies.

Bower

We're going to be installing Backbone, which has a dependency on Underscore and jQuery, for our MVC framework and Handlebars for our templating framework. We'll also be adding a couple of plugins for Require that will make loading our templates easy.

To install the whole lot, run:

bower install backbone underscore jquery handlebars requirejs-text require-handlebars-plugin --save  

When complete, you'll see your bower.json file has been updated and a bunch of new libraries has been installed under public/components. These libraries all have different directory structures and since they don't live under our app directory, we are going to create shortcuts for Require to use when loading them.

In our require-main.js file, add the following entries to the paths block;

paths: {  
    "jquery": "../components/jquery/dist/jquery",
    "underscore": "../components/underscore/underscore",
    "backbone": "../components/backbone/backbone",
    "handlebars": "../components/handlebars/handlebars.amd",
    "text": "../components/requirejs-text/text",
    "hbs": "../components/require-handlebars-plugin/hbs"
}

These are the paths to the main Javascript file in each of the libraries. You'll notice each is prefixed with ../. This is because we set our baseUrl to app, so we need to adjust for that. We've also left the .js off the file name. If you look in the libraries, you'll see some come with pregenerated minified versions. At this point in development, I prefer using the full version to make debugging easier. We can worry about optimization later. Also note, we used the .amd version of Handlebars. This is the module format that Require uses so picking this flavor will let us work with it without having to create any shims.

Routing and Our Home Page

The heart of a single page application is the routing. It is responsible for interpreting the URL and displaying the correct information on the screen. Later, it will also be responsible for ensuring that our user is authenticated and redirecting them to login if needed.

To begin, we are going to create a single route, that displays our main page layout. The layout will incorporate a container for sub-views to be displayed in and a header view to contain our navigation elements. We'll also use a partial template to display a footer at the bottom of our page. To help avoid memory leaks, we'll extend the standard Backbone View with some utility methods to clean itself up when it is closed.

All of these pieces are fairly intertwined so there is no obvious place to start. Let's start with a bit of plumbing that we will use throughout our whole app, our event bus.

Event Bus

Backbone.Events is a mixin that can be added to any object and enables that object to listen to and trigger events that other objects can listen for and react to. While, most Backbone objects have this mixin already, I find it is easier to create a specific object that we can explicitly use as an event bus.

/app/mediator.js

define(function(require){

    'use strict';

    var _ = require('underscore');
    var Backbone = require('backbone');

    return _.extend({}, Backbone.Events);

});

Simple really. We create an empty object, mixin the Events, and return it. Now, anywhere in our code we want to deal with messages, we can get a reference to this mediator and use it. There are some other interesting message patterns we may be interested in down the road, such as Commands and Requests. You can look at the Backbone.Radio plugin if your app needs these features.

Home Page

Create a page directory under app to hold the related files. We'll be using the 'pods' method of organizing our files that has become popular with the Ember crowd. It will let us keep all the information for a given feature together, as opposed to organized by function(controllers, views, etc.).

Create the following files:

/app/page/pageTemplate.hbs

<div id="header"></div>  
<div id="content" class="container"></div>  
<div id="footer">{{> ./footerTemplate}}</div>  

/app/page/headerTemplate.hbs

<header>  
    <div class="navbar navbar-default">
        <div class="container">
            <div class="navbar-header">
                <a href="/" class="navbar-brand"><b>relearning backbone</b></a>
            </div>
            <ul class="nav navbar-nav navbar-right">
                [Navigation Elements]
            </ul>
        </div>
    </div>
</header>  

/app/page/footerTemplate.hbs

<div class="text-center">Relearning Backbone - http://brianmajewski.com</div>  

In the main template, we define three divs that will contain our header, main content, and footer. Since the footer is going to be static content, we could have easily included it in the page but this is a way to validate that partial templates are being included.

For now, there is no functionality in the header, so let's create a very simple Backbone view that renders the template.

/app/page/headerView.js

define(function (require) {

    'use strict';

    var Backbone = require('backbone');
    var template = require('hbs!page/headerTemplate');

    return Backbone.View.extend({
        el: '#header',

        render: function(){
            this.$el.html(template());
            return this;
        }
    });
});

There is that define(function (require){}); syntax again. I always include 'use strict'; as a matter of habit. Next, we use Require to include the Backbone library and the template. Note the syntax for the template: hbs!page/headerTemplate - hbs! tells require to use the hbs plugin we configured earlier, followed by the path to the template. It assumes a .hbs extension, but can be configured to accept others.

The rest is simple Backbone view stuff. We define the page element to attach the view to (el: '#header'), and then we define the render function, using the template as is to generate the html. As a matter of course, we will always return a reference to the view when we render it.

Now, let's create the containing Page view that will hold the header and other content views.

/app/page/pageView.hbs

define(function (require) {

    'use strict';
    var Backbone = require('backbone');
    var mediator = require('mediator');
    var template = require('hbs!page/pageTemplate');
    var HeaderView = require('page/headerView');


    return Backbone.View.extend({
        el: '#page',

        initialize: function () {
            this.contentView = null;
            this.bindPageEvents();
        },

        render: function () {
            this.$el.html(template());
            this.headerView = new HeaderView();
            this.headerView.render();
            return this;
        },

        bindPageEvents: function () {
            mediator.on('page:displayView', this.displayView, this);
        },

        displayView: function (view) {
            if (this.contentView !== null) {
                this.contentView.close();
                this.contentView = null;
            }

            this.contentView = view;
            if (this.contentView) {
                this.contentView.render();
            }
        }
    });

});

This is very similar to the header. We set it's element to #page. In our render method, we instantiate the HeaderView and render it as well. In the initialize method, we create a variable to hold our content views, and set up the view to listen to messages. In bindPageEvents, we listen on the mediator for the message page:displayView and when we get it, we call the displayView method. Here, we clean up any existing content view and render the one passed to us with the message. One non-standard thing we are doing here is calling .close on the content view. Backbone has a remove method which does something similar but we are going to be a bit more aggressive in cleaning up our code. We'll add this code in when we update our main.js file.

To test this out, we need a content view. Go ahead and create the following files to provide a simple Welcome view.

/app/welcome/template.hbs

<div class="jumbotron">  
    <h1>WELCOME TO OUR APPLICATION</h1>
</div>  

/app/welcome/view.js

define(function (require) {

    'use strict';
    var Backbone = require('backbone');
    var template = require('hbs!welcome/template');

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

});

Now we need a way for the application to display this view when we start up the app. Let's go ahead and create our router.

/app/router.js

define(function (require) {

    'use strict';
    var mediator = require('mediator');
    var Backbone = require('backbone');
    var PageView = require('page/pageView');


    return Backbone.Router.extend({
        initialize: function () {
            this.pageView = new PageView();
            this.pageView.render();
            this.bindApplicationEvents();
        },

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

        home: function () {
            console.log('routing - home');
            require(['welcome/view'], function (View) {
                mediator.trigger('page:displayView', new View());
            });
        },

        bindApplicationEvents: function () {
            mediator.on('router:navigate', this._navigate, this);
        },

        _navigate: function (context) {
            console.log('routing - trigger to ', context.route);
            this.navigate(context.route, context.options);
        }
    });

});

Let's break this down in chunks.

In our initialize function, we instantiate our Page view and render it to the screen. At this point, it has its header and footer but its content view is empty. Our router will fill in different views based on the URLs we visit. We also tell it to bindApplicationEvents. You'll see this pattern repeated. I will have the initializer of a class setup the messages/event bus for the messages it is interested in receiving. In this case, we are listening for a router:navigate message. This will allow other parts of our application to change where we are in our app without having a direct reference to the router.

In our routes object, we set up two paths, '' and 'home' that will route us to the home function.

In our home function, we require our Welcome view, which is the content view we want to display when someone hits our home page, then fire off a message, with the view attached, that our page is listening for.

Turning It On

The last step we need to take is to turn on the router. Let's update our main.js file.

/app/main.js

define(function (require) {

    var Router = require('router');
    var mediator = require('mediator');

    var router = new Router();
    Backbone.history.start({pushState: false});

    if (Backbone.history.fragment === '') {
        mediator.trigger('router:navigate', {route: 'home', options: {trigger: true}});
    }
});

Here we simply instantiate our Router, and tell Backbone to start managing our history. We've also added a little helper to ensure that when a user comes in the first time, with no URL fragment, such as /users/123, that we send them to the home page.

Fire up the server and refresh your page. You should see our fully composed page.

Extending Backbone
Remember, we wanted to add some functionality to ensure that Views we close release all their objects and events as to avoid memory leaks.

In our main.js file, under our require declarations, add the following code:

_.extend(Backbone.View.prototype, {  
        // Handle cleanup of view.
        close: function () {
            if (this.beforeClose) {
                // Perform any cleanup specific to this view.
                this.beforeClose();
            }

            if (this.model) {
                // Remove all callbacks for this view's model.
                this.model.off(null, null, this);
                this.model = null;
            }

            // Something else might be named 'collection' so also check for the
            // existence of `off`
            if (this.collection && this.collection.off) {
                // Remove all callbacks for this view's collection.
                this.collection.off(null, null, this);
                this.collection = null;
            }

            // Remove all delegated events.
            this.undelegateEvents();
            this.off(null, null, this);

            // Remove all markup.
            this.$el.empty();
        }
    });

Here we extend the base View definition to add our close method. This will call a beforeClose method on a view, if it has one, for view specific cleanup. If the view has a model or collection associated with it, it turns off the model/collections's events and clears the model/collection. It then turns off the view's events and removes the contents from the DOM.

Next Steps

In our next installment, we'll create a view that retrieves our users from our REST backend and displays the results.

(The code at this state in the project can be checked out at commit: e55dbc2be4ab5e8ce883ad7e397654e346f5d135)

(The current code base can be checked out here)

Front End Build

Often at this point in a project, I will get derailed. I'll start thinking about dependency management, should I use Grunt or Gulp or Broccoli or ... to build the project, module definitions, and the like. The combination of all these options just multiplies and I'll spin until I lose interest in the project for awhile.

Tasks like minification and image optimization and static analysis are important parts of a production application but we still haven't written one line of front end code. In the spirit of XP, I did the simplest thing possible that still works.

My requirements: I wanted to declare my Javascript dependencies on the fly. I always forget to add them individually to my index.html file. I want to declare them explicitly so that different sections of the code could be loaded independently when it comes time to optimize the app. This also has the side benefit of allowing my IDE to perform better autocompletion. I wanted all of my assets to be accessible from the simple web server we created earlier without a separate deploy step. Once we have a working app, we can then go back and figure out how to serve up the bare minimum.

To accomplish all of these tasks, we are going to use two tools: Bower and RequireJS. Bower will handle the management of third-party libraries and RequireJS will handle our dependency management and loading of files. There are other options, especially for RequireJS, such as Browserify. Feel free to explore them and pick one you are comfortable. The way you modularize your code will be a part of every file you write, so be happy with your choice.

Bower

Bower, like Node's NPM, allows you to automatically retrieve libraries from the net, and manage them and their dependencies. To install it, run

npm install -g bower  

One quick customization we are going to make is where Bower stores its dependencies. Typically, we would keep them at the same level as our node_modules dependencies, and use a build tool to copy the specific JS and CSS files we need into our app. To avoid this, we will store our dependencies under our public directory so that our Node server can serve them up directly. This has the side effect that ALL files that come with the packages are accessible, such as READMEs and package files, but until we have a working app, this is a reasonable trade off. In your project directory, create a file called .bowerrc with the following contents:

{
    "directory":"public/components"
}

With this complete, run bower init, answer the questions and finally end up with a bower.json file that looks similar to:

{
  "name": "relearning-backbone",
  "version": "1.0.0",
  "homepage": "https://github.com/bmajewski/relearning-backbone",
  "authors": [
    "Brian M <hireme@brianmajewski.com>"
  ],
  "license": "MIT",
  "ignore": [
    "**/.*",
    "node_modules",
    "bower_components",
    "public/components",
    "test",
    "tests"
  ]
}

We're now set up to use Bower to pull in our other dependencies, including RequireJS.

RequireJS

To effectively use RequireJS, you really should go and read through the docs once or twice first. Go ahead, I'll wait. Done? Ok - It may not make a bunch of sense if you are new to this type of module management. Hopefully, as we work with it, it will become clearer.

In a nutshell, Require (I'm going to drop the JS from here on out) will allow us to specify just one Javascript requirement in our index.html file. From there out, it will dynamically load additional files as we need them without us having to explicitly add them.

To set this up, we'll update our index.html and create a configuration file for Require. To install Require, run:

 bower install requirejs --save

If you look under public/components, you'll see the newly installed package.

There are differing opinions on where to put Javascript declarations and how they effect initial download and rendering of your home page. For simplicity, we'll place our declaration in the <head> of our document, beneath our styles.

<head lang="en">  
    <base href="/">
    <meta charset="UTF-8">
    <title>Relearning Backbone</title>
    <link rel="stylesheet" href="assets/css/styles.css">
    <script src="components/requirejs/require.js" data-main="require-main.js"></script>
</head>  

As you can see, we've added a non-standard attribute to our script tag: data-main="require-main.js". This tells Require where to read its configuration information.

Go ahead and create the file require-main.js under public, with the following contents:

requirejs.config({  
    baseUrl: "app",

    paths: {

    }
});

require(['main']);  

This is (almost) as minimal of a config file we can use and have it still be useful. At the top, we call config on requirejs and set some properties. baseUrl is where require should look for all files we haven't explicitly defined. paths are those explicitly defined files (and is empty for now). Next, we invoke require with an array of files we need to load. Typically, you would declare those files, and then a function, assigning those files to variables, and do something with them, such as:

require(['moment'], function(moment){  
    moment.format();
});

which would load the Moment library and display a formatted datestamp.

In this case, we are telling it to load the file main and process its contents. Our main file won't return anything - it will actually load up our application and start it up. Since we have't defined main in the paths block above, Require will look for app/main.js, so let's create an app directory and a main.js file with the following contents:

define(function (require) {  
    console.log('require module loading working');
});

All of our Javascript files will have this basic format: a define function that takes require as an argument. We'll be able to use this parameter later to load other files.

If you reload index.html, you should be able to see our message in your console window. This let's us know that we have Require wired in and loading our modules.

Spit And Polish

Before we get into the meat of designing our home page and screens to access the user data, I want to add a little bit of styling to the app. I find that if I leave things a little too "raw" I'll waste time trying to clean them up a bit. At this point I would usually grab Bootstrap to provide a simple clean interface. But... should I use the plain CSS, or maybe the LESS or the SCSS... Do I need to add a CSS preprocessor to my build pipeline? What about all the Javascript components, should I add them in too? Will they conflict with the stuff I want to write later? Oh hey, what about trying Susy for a grid layout? And on and on it goes. Once again - DERAILED Here is what I do now. I go to Bootswatch, pick a color theme that I like in the moment, download the CSS file, put it in assets/css, add it to my index.html file and I am done with CSS until it comes time to actually build my app and its feature set.

Next Steps

With our package management and module loader in place, we're ready to start building out our client application. Next time, we'll create a simple router, a message bus, and main layout that will allow us to swap different content views in as needed.

(To grab the code at this point in the series, checkout commit: 82df0f2fd5bdc91d5599aa1c40faacca38766327 from Github)