Thieves Like Us

(Re)Learning Backbone Part 12

Brian Majewski — Fri, 06 Mar 2015 05:14:49 GMT

Permissions
For the last piece of our application, we are going to require that a user have "admin" permissions to delete another user. We created a cheat way to add permissions to our users earlier in the series. Using that, or Mongohub, ensure we have one user with "admin" as a permission, and one user without. Let's start logged in as the user without permissions.

Update The Server

On the server, we know who the user making a request is due to the token they present on every call, but we don't have the User object. We could make a DB call to see if they have the right permissions. This could become a burden on our server. We could use a server side session to store the User, but again, this may not scale well. The easiest way to determine the permissions is to have the user tell us. We can add the permissions to the token before we encrypt it. Then when we decrypt it, which we do on every authenticated call, we can access the permissions it contains. Let's update our authenticate endpoint

/app/routes/user.js

userRouter.post('/authenticate', function (req, res) {  
    User.findOne({
        email: req.body.email
    }).select('name email password').exec(function (err, user) {
        if (err) throw err;

        if (!user) {
            res.json({success: false, message: 'User not found'});
        } else {
            var validPassword = user.comparePassword(req.body.password);
            if (!validPassword) {
                res.json({success: false, message: 'Wrong password'});
            } else {
                var token = jwt.sign({
                    name: user.name,
                    email: user.email,
                    _id: user._id,
                    permissions: user.permissions
                }, superSecret, {
                    expiresInMinutes: 1440
                });

                res.json({
                    success: true,
                    message: 'login ok',
                    token: token,
                    _id: user._id
                });
            }
        }
    });
});

We simply added the one line

permissions: user.permissions

in our signing method.

Now, let's update our DELETE route to check for admin. For convenience, and consistency with our client, let's throw underscore.js into the server.

npm install underscore --save

and add it to the top of our user routes

var _ = require('underscore');

and finally update the DELETE route

.delete(function (req, res) {
    if (_.contains(req.decoded.permissions, 'admin')){
        User.remove({_id: req.params.user_id}, function (err, user) {
            if (err) res.send(err);
                res.json({});
            })
        } else {
            return res.status(403).send({success: false, message: 'User is not authorized to delete users'});
        }
    });

We check if the permissions property of our decoded token contains "admin", and if not, throw a 403 error. Refresh the server and try to delete a user. You should see the error in the console window and the list of users remaining the same.

For this error, we don't want to redirect the user anywhere but it would be nice to let them know that the error occured. Let's trap for the 403, like we did the 401, and popup an alert. For our popups, we'll be using Toastr, so let's add it with bower, update require-main.js, and include its CSS on our index page.

bower install toastr --save

require-main.js

requirejs.config({  
    baseUrl: "app",

    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",
        "datatables": "../components/datatables/media/js/jquery.dataTables",
        "datatables-bootstrap3": "../components/datatables-bootstrap3-plugin/media/js/datatables-bootstrap3",
        "bootstrap-modal": "../components/bootstrap/js/modal",
        "backbone.bootstrap-modal": "../components/backbone.bootstrap-modal/src/backbone.bootstrap-modal",
        "stickit" : "../components/backbone.stickit/backbone.stickit",
        "toastr" : "../components/toastr/toastr"
    }
});

require(['main', 'app']);

index.html

With the library in place, let's update our error handler. Remember to require toastr at the top of the file.

app/main.js

$.ajaxSetup({
    statusCode: {
        401: function (context) {
            mediator.trigger('router:navigate', {route: 'login', options: {trigger: true}});
        },

        403: function(context){
            toastr.options = {
                "closeButton": false,
                "debug": false,
                "newestOnTop": false,
                "progressBar": false,
                "positionClass": "toast-top-center",
                "preventDuplicates": false,
                "onclick": null,
                "showDuration": "300",
                "hideDuration": "1000",
                "timeOut": "5000",
                "extendedTimeOut": "1000",
                "showEasing": "swing",
                "hideEasing": "linear",
                "showMethod": "fadeIn",
                "hideMethod": "fadeOut"
            };

            toastr["error"](context.responseJSON.message);
        }
    },
    beforeSend: function (xhr) {
        var token = window.localStorage.getItem(globals.auth.TOKEN_KEY);
        xhr.setRequestHeader('x-access-token', token);
    }
});

You can configure your popup however you like. These options are the ones generated from the library's demo site. We configure the popup, then display the error message our backend returned to us.

One last tweak is needed. Backbone is optimistic when you ask to destroy a model, and will remove it from any collections it is in. Since we may not want that to happen, we pass in a wait property to our destroy method. Let's update that

app/users/listView.js

deleteUser: function(e){  
    var self = this;
    var id = $(e.currentTarget).attr('data-id');
    var user = this.collection.get(id);
    user.destroy({wait: true}).done(function(){
        self.collection.remove(user);
        self.render();
    });
}

Now, ideally, we don't want the user to even be given the option to press the delete button. All of this error handling is neccesary to protect our data but we shouldn't be giving users options they don't have. Much like checking for authentication, we are going to create a way for our views to check for authorizations.

Let's create a simple Permissions object that we can create when the user logs in.

app/permissions.js

define(function (require) {

    'use strict';

    var _ = require('underscore');

    return function(permissions){
        this.isAdmin = function(){
            return _.contains(permissions, 'admin');
        };
    }
});

We'll pass in the permissions array from the user when we create this, then for convenience we expose an isAdmin function. This can be expanded as needed. Common patterns include 'has one of these permissions' and 'has all of these permissions'. Let's update our app object

app/app.js

var Permissions = require('permissions');  
var _permissions;

function _initializeUser() {  
    var d = $.Deferred();
    if (_isAuthenticated() && !_user) {
        _user = new User({_id: window.localStorage.getItem(globals.auth.USER_KEY)});
        _user.fetch().success(function () {
            mediator.trigger('page:updateUserInfo');
            _permissions = new Permissions(_user.get('permissions'));
            d.resolve();
        });
    } else {
        d.resolve();
    }
    return d.promise();
}

function _getPermissions() {  
    return _permissions;
}

return {  
    isAuthenticated: _isAuthenticated,
    initialize: _initialize,
    initializeUser: _initializeUser,
    getApplicationInfo: _getApplicationInfo,
    getUser: _getUser,
    getPermissions: _getPermissions
}

Now, let's update our user list template and view to not show the delete button unless the user is an admin.

app/users/list.hbs

  
    
    {{#if ../admin}}{{/if}}

Here we check the value of ../admin to conditionally show the button. We are using the ../ notation because we are inside of the users loop and we will be storing our admin value one level up.

_app/users/listView.js (render)

render: function () {  
    this.$el.html(template({
        users: this.collection.toJSON(), 
        admin: app.getPermissions().isAdmin() 
    }));
    this.$('table').DataTable({
        "aoColumns": [
            null,
            null,
            null,
            { "bSortable": false }
        ]
    });
return this;  
}

After adding an app dependency to our object, we add an admin value to the context object we pass our template for rendering. Refresh the page, and the button is gone. Log in now as a user with admin permissions and verify that the button is still visible and in fact deletes the user.

Next Steps

In our final installment, we will make a few tweaks to the code and talk about what could be some next steps.

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

(Re)Learning Backbone Part 11

Brian Majewski — Fri, 06 Mar 2015 01:32:22 GMT

A Little Clean Up

At this point, we have a fairly functional app, with full CRUD operations and an authentication strategy. Before we dive into doing authorization, or permission based access, we are going to clean up our app logic a little bit, proactively protect our routes from unauthorized access, get a reference to the currently logged in user, and display relevant information in the header.

For the most part, we access data when we need it. Some data, however, is global and used by the app as a whole. This could be information such as an application version or build information. It could be reference data used in most pages, or, in our case, it's the user that is currently logged in. We're going to create an app object that will hold on to these types of values. It will also handle orchestrating information and workflow between views when appropriate.

We'll start by moving our local storage access routines into it.

/app/app.js

define(function (require) {

    'use strict';

    var globals = require('globals');
    var mediator = require('mediator');

    function _authenticated(response) {
        window.localStorage.setItem(globals.auth.TOKEN_KEY, response.token);
        window.localStorage.setItem(globals.auth.USER_KEY, response._id);
        mediator.trigger('router:navigate', {route: 'home', options: {trigger: true}});
    }

    function _logout(){
        window.localStorage.removeItem(globals.auth.TOKEN_KEY);
        window.localStorage.removeItem(globals.auth.USER_KEY);
        mediator.trigger('router:navigate', {route: 'home', options: {trigger: true}});
    }

    mediator.on('app:authenticated', _authenticated, this);
    mediator.on('app:logout', _logout);

    return {

    }

});

We pull in our globals and mediator objects, and set up two functions that are called when the appropriate messages are triggered. Now, we can clean up /app/router.js and /app/login/view.js, removing their local storage calls and redirects with a simple message. To ensure that this global object is always loaded and listening for messages, we can load it along with the main file in require-main.js

require(['main', 'app']);

Protecting Our Routes

We'll be adding to app.js shortly. Let's look at how we can enhance our router to protect our routes from unauthorized access. It's important to remember - ALL THIS CODE IS CLIENT SIDE - when we say we are protecting it, all we are doing is providing a better experience for our users and, in this case, minimizing the number of unauthenticated service calls. Any data, images, etc. that is in your JS/Handlebars/whatever files will still be sent to the user's browser - especially after you concatenate them.

If you recall the flowchart from the last installment, we asked potentially three questions before sending a user to their requested route: Does the route need authentication, do we have a stored token, and do we have a stored User? The first question we will answer implicitly by guarding only the routes that need it. For our app, that would be the Users page. The second question we will ask explicitly in our router, directing the user to a login page if not already authenticated. The third question we will defer to the view that we will use the information in.

Here is our new users route in our router:

users: function() {  
    console.log('routing - users');
    if (app.isAuthenticated()) {
        require(['users/collection', 'users/listView'], function (Collection, View) {
            var collection = new Collection();
            collection.fetch().done(function () {
                mediator.trigger('page:displayView', new View({collection: collection}));
            });
        });
    } else {
        console.log('unauthenticated - redirecting to login');
        this.login();
    }
},

We've wrapped our regular routing code in a check to our app object to see if we are authenticated, and if not we go to the login page. So, let's add that code now. On the empty object we are currently exporting from app we'll add an isAuthenticated property which will hold a reference to a "private" function.

function _isAuthenticated(){  
    return window.localStorage.getItem(globals.auth.TOKEN_KEY);
}

return {  
    isAuthenticated: _isAuthenticated
}

Here we are simply returning the value of the token we have stored. We make the assumption if there is one, it is valid, and use the truthiness of the value as our answer. If we want to get fancy, we could decouple this even more, using a Request pattern. Check out Backbone.Radio for more info.

Will the stored token always be valid? No. We currently have ours set to expire after 24 hours but nothing is going to remove it from the browser's storage unless the user logs out. In this case, we fall back on our 401 error handling. Same goes for a token that is forged or otherwise malformed. We could get fancy and use a client side JSON Web Token library to verify the encryption signature but there's really no need.

Application Wide Data

In addition to our current user, let's set up an unauthenticated API call that returns the current version of our application. Typically, we would set up another set of routes for our server, but let's cheat and put this call in our user routes. Use the following code and place it before we apply our authentication middleware.

userRouter.get('/applicationInfo', function(req,res){  
    res.json({version: '1.0-apple', build: 'local'});
});

While we are at it, let's add that URL to our globals object

urls: {  
    AUTHENTICATE: '/api/authenticate',
    APP_INFO: '/applicationInfo'
}

Together with the current user, we are going to spruce up our header/footer areas. So, we will be answering that third question (Do we have a user/app wide data?) in our page view. We will ask for it when we first render our page. In addition, we will add some messaging so that we can update our page should the information change (such as when the user logouts).

Since this is the third question, we can assume the user is authenticated - we verified this with the second question. What we can't assume is that we've loaded this information already. Perhaps the user is returning after being gone awhile. They still have a valid token, so they are 'authenticated' but haven't retrieved the requested data. What we want to do is "always" get the data, and then when done, return to our view. I say "always" because we will do a quick check and only call the server if we don't have it. To accomplish this, we will use jQuery's Deferred object and promises. In the case that the user has not authenticated, we will return an empty user object and render our page accordingly.

Aside: One might wonder why we don't store this information like we do the token or user id. For one, this type of information, especially reference data, can get quite large. We want to limit the amount of data we store locally. Additionally, this data can change. Maybe not over the course of a user's session but we do want to ensure we are working with current data when possible. Finally, some of the information may be sensitive. Leaving it in the browser storage makes it accessible with little safeguards.

Updating Our Header

Let's update the header to show different information on whether or not we have a valid user object. Let's assume if we have an empty user object (no _id property) that there is no logged in user.

/app/page/headerTemplate.hbs

  
    
        
            
                relearning backbone
            
            
                {{#if _id}}
                     Users
                {{/if}}
            
            
                {{#if _id}}
                    Hello {{name}}
                    Logout 
                {{else}}
                    Login 
                {{/if}}

To see this in action, we can update the render methods in our header view and page view

/app/page/headerView.js (render)

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

/app/page/pageView.js (render)

render: function () {  
    this.$el.html(template());
    //this.headerView = new HeaderView({ model: new User() });
    this.headerView = new HeaderView({ model: new User({ _id: '1', email: 'a@example.com', name: 'Example User' })});
    this.headerView.render();
    return this;
}

Here we alternately bind an empty User to the header view's model or one we mocked up. Comment one or the other out to see the two states of the header.

With that working, let's update our page view render once again to work with real live data.
/app/page/pageView.js (render)

render: function () {  
    var self = this;
    // Gets nonauthenticated application info
    app.initialize().done(function () { 
        // Ensure user is loaded if authenticated or blank user if not
        app.initializeUser().done(function(){ 
            self.$el.html(template());
            self.headerView = new HeaderView({ model: app.getUser()});
            self.headerView.render();
            return self;
        });
    });
}

Here we've wrapped our rendering with two asynchronous calls to load app data and the current user, and we get the current user (or a blank one) to bind to the header view's model. Let's add these three methods to our app object (and a fourth for getApplicationInfo which we will use later).

/app/app.js

// other methods above

var User = require('users/model');  
var _user;  
var _applicationInfo;

function _initialize() {  
    var d = $.Deferred();
    if (_applicationInfo !== null) {
        d.resolve();
    } else {
        $.ajax({
            url: globals.urls.APP_INFO,
            success: function (data) {
                _applicationInfo = data;
                d.resolve();
            }
        });
    }
    return d.promise();
}

function _initializeUser() {  
    var d = $.Deferred();
    if (_isAuthenticated() && !_user) {
        _user = new User({_id: window.localStorage.getItem(globals.auth.USER_KEY)});
        _user.fetch().success(function () {
            d.resolve();
        });
    } else {
        d.resolve();
    }
    return d.promise();
}

function _getApplicationInfo() {  
    return _applicationInfo;
}

function _getUser() {  
    return _user || new User();
}

return {  
    isAuthenticated: _isAuthenticated,
    initialize: _initialize,
    initializeUser: _initializeUser,
    getApplicationInfo: _getApplicationInfo,
    getUser: _getUser
}

This works. Kind of. If you already have a token from logging on previously, when you refresh the page, you should see the correct information in the header. However, if you need to login first, or when your log out, you'll see that the header information never changes. We set it once when we rendered it and then leave it alone. We need for our page view to respond when ever our current user changes.

Let's look at logout first. Let's update our logout method in app to clear out our user and fire off a message

function _logout() {  
    window.localStorage.removeItem(globals.AUTH_TOKEN_KEY);
    window.localStorage.removeItem(globals.AUTH_USER_KEY);
    _user = null;
    mediator.trigger('page:updateUserInfo');
    mediator.trigger('router:navigate', {route:'home', options: {trigger: true}});
};

Now, let's have the header view respond to that message. Here is the new view

/app/page/headerView.js

define(function (require) {

    'use strict';

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

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

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

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

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

        updateUserInfo: function(){
            this.model = app.getUser();
            this.render();
        }
    });
});

Now, when we logout, the header refreshes itself and clears the user's info. Now for logging in. Previously on login, we stored the token and user id and then navigated to the home page. Let's also load up the user with our _initializeUser call and send a message to update the page when it's done.

function _authenticated(response) {  
    window.localStorage.setItem(globals.auth.TOKEN_KEY, response.token);
    window.localStorage.setItem(globals.auth.USER_KEY, response._id);
    _initializeUser();
    mediator.trigger('router:navigate', {route: 'home', options: {trigger: true}});
}

function _initializeUser() {  
    var d = $.Deferred();
    if (_isAuthenticated() && !_user) {
        _user = new User({_id: window.localStorage.getItem(globals.auth.USER_KEY)});
        _user.fetch().success(function () {
            mediator.trigger('page:updateUserInfo');
            d.resolve();
        });
    } else {
        d.resolve();
    }
    return d.promise();
}

Once again, when the message is fired, the header view will be updated. We can follow the same pattern for any data that is stored and updated away from the view that is displaying it.

Next Steps

The last piece of functionality we want to take a look at is authorization. Just because a user is logged in doesn't mean they have access to all the app's features. We'll look at allowing only certain users to use the Delete feature and handling 403 Unauthorized errors.

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

(Re)Learning Backbone Part 10

Brian Majewski — Wed, 04 Mar 2015 01:47:29 GMT

Logging In

When we last left off, we had enforced authentication on our users endpoints and provided an endpoint to authenticate against. Today, we are going to add a Login screen and route to present our credentials to the backend. Upon success, we'll store the returned token and present it on all subsequent requests.

Let's start by introducing a globals object. I like to create an object to hang constant values off of that are needed throughout the app.

/app/globals.js

define(function (require) {

    'use strict';

    return {
        auth: {
            TOKEN_KEY: 'authToken',
            USER_KEY: 'userId'
        },
        urls: {
            AUTHENTICATE: '/api/authenticate'
        }
    }
});

Here we've defined two keys we are going to use to store and retrieve authentication data and the URL we need to hit to authenticate. For entities, like User, we store the URL with the model, but for URLs that don't neatly map to a model, I like to keep them here in globals.

So, with our authentication in place, if we try to hit /#users, we'll get a 401 error when we call the /api/users endpoint, and our screen will only show our header and our footer. Let's have our app respond to 401 errors by redirecting the user to a login screen.

In /app/main.js, before we create our Router, add the following code:

$.ajaxSetup({
    statusCode: {
        401: function () {
            console.log('AJAX Handler - 401 Error Received');
            mediator.trigger('router:navigate', {route: 'login', options: {trigger: true}});
        }
    }
});

We are using jQuery to make a global change to our AJAX handling. Now, any AJAX call that gets a 401 error will get trapped and we'll trigger the router to take us to our login page. Let's update our router to handle this.

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

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

We've updated our route table to include a login path, and created a handler for it. This should seem familiar by now. We'll need a template and a view.

/app/login/template.hbs

This is a simple form that will allow us to collect an email address and a password. It also has an alert div we will use to display error messages and a submit button with the class js-login which will trigger the submission action.

/app/login/view.js

define(function (require) {

    'use strict';

    var Backbone = require('backbone');
    var globals = require('globals');
    var mediator = require('mediator');
    var template = require('hbs!login/template');

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

        events: {
            'click .js-login': 'login'
        },

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

        login: function (e) {
            e.preventDefault();
            var formValues = {
                email: this.$('#email').val(),
                password: this.$('#password').val()
            };
            this.$('.alert').hide();
            console.log('login with ', formValues);
            $.ajax({
                url: globals.urls.AUTHENTICATE,
                type: 'POST',
                dataType: 'json',
                data: formValues,
                success: function(response){
                    if (response.success){
                        window.localStorage.setItem(globals.auth.TOKEN_KEY, response.token);
                        window.localStorage.setItem(globals.auth.USER_KEY, response._id);
                        mediator.trigger('router:navigate', {route:'home', options: {trigger: true}});
                    } else {
                        self.$('.alert-warning').text(response.message).show();
                    }
                }
            });
        }
    });
});

This is a standard view that listens for a click event on our submit button. When it receives one, we go to the login method.

Here, we get the values from the form fields. If the alert box is visible, we hide it. Finally, we make an AJAX call to our authentication endpoint, using the URL we defined in our globals.

If you remember, our authentication routine does not send back an HTTP error code. This allows us to handle any errors here. In our case, the else block, when the response message success property is false, takes the message returned from the server, adds it to the alert box and makes it visible.

When we successfully enter our credentials, we use local storage to store the auth token and the user id that was returned to us. Finally, we navigate to the home screen. Later, we can add code to redirect the user to their original destination but for now, we'll go home.

So what happens if we try to go to /#users again. Another 401 error! Just because we logged in once, the server has no idea that it is still us unless we tell it. To do this, we will include that token we just received in the header of all our AJAX calls. Go back to where we trapped for the 401 error and update the handler

$.ajaxSetup({
    statusCode: {
        401: function (context) {
            mediator.trigger('router:navigate', {route: 'login', options: {trigger: true}});
        }
    },
       beforeSend: function (xhr) {
        var token = window.localStorage.getItem(globals.auth.TOKEN_KEY);
        xhr.setRequestHeader('x-access-token', token);
    }
});

We've added the beforeSend method. This will retrieve the token from local storage, and set the x-access-token header to that value. If you recall, that is where our authenticated routes look for the token when determining if the caller is authenticated. Now if we hit our users page, the token we previously stored will be sent with our call, we'll be authenticated, and the page will display properly.

If you need to try again, you can use your browser's dev tools to remove the token from local storage, effectively logging you out. Let's make this a little easier on ourselves. Later, we'll be customizing our header view with information specific to the current user. For now, let's add a logout link.

In /page/headerTemplate.hbs replace the [Navigation Elements] place holder with

 Logout

and update your router

/app/router.js

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

logout: function() {  
    window.localStorage.removeItem(globals.auth.TOKEN_KEY);
    window.localStorage.removeItem(globals.auth.USER_KEY);    
    this.home();
 }

This simply deletes our authentication info and sends the user to the home page. If it seems a little messy that we are messing with local storage in different parts of our app, you're right. Later when we coordinate loading the currently authenticated user, we'll create some convenience methods that we can trigger with messages through the mediator.

Next Steps

When we load our app, we will want to make sure we have the user object associated with the currently logged in user. We've already stored the id, so it is just a matter of loading the user. With that User, we'll customize the header. Additionally, we relied on the 401 error to redirect us to the login page. We'll be adding an isAuthenticated check to the router itself so that we can redirect to the login screen without needing to make a server call round trip.

(You can check out the project at it's current state at commit: 8a0a2b3c06575454a7ffae2b03b579d3bc47acba)

(Re)Learning Backbone Part 9

Brian Majewski — Thu, 26 Feb 2015 04:53:11 GMT

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

Authentication and Authorization

In this installment we'll tackle some functionality that I feel many tutorials leave out - authentication. We are going to implement a simple model that will both authenticate users and determine whether they are authorized to perform a function. This implementation is not meant to be bulletproof but to get a basic workflow in place. We'll be identifying a user as an admin with permissions to delete users. In practice, I usually keep all admin type functions out of my main application. Keeping them to themselves in a purpose built app allows you to restrict the audience and enforce other security measures, such as IP whitelisting.

HTTP is a stateless transaction by default. Whether we create a server side session to track user details or not, we need some way to identify an incoming request as being made by a particular user. We will be using JSON Web Tokens to provide this identification. They will be generated by our server when a user authenticates themselves and stored in the browser's local storage. To demonstrate authorization and personalizing the interface we will also be asking the server for the user information for the currently logged in user and a set of permissions for actions they are allowed to take. We will use these permissions on the client to present a better experience for the user; we won't easily allow them to perform an action they are not authorized to perform. Ultimately, all actions will be verified on the server to prevent users from bypassing our UI restrictions.

Before we get into the code, let's take a look at the workflow of authenticating a user. Let's assume we have a home page accessible to anyone, our users page, accessible to logged in users, and the delete button accessible to anyone with Admin permissions.

We can describe our workflow in two places: the router and application wide AJAX error handling.

Here is the logic workflow we will be implementing in the router and supporting classes:

Along with these decisions, we will intercept and handle the following HTTP error codes returned by our backend:

401: The User is not Authenticated - Redirect to Login
403: The User is not Authorized - Redirect to Home
500: Generic Error Handling

So, in the case that a user has a token, but it has expired, when they go to retrieve their User object, we will return a 401 error, forcing them to login.

Creating An Admin User (The Wrong Way)

We don't want to create a full featured permissions model or management console at this point. We haven't coded any features so trying to write permissions would be premature. It would be helpful for testing and prototyping, however, to indicate that one or more of our users had a specific property. To add these permissions to a user, we are going to cheat. For our POST /api/users and PUT /api/users/:user_id routes, we are going to check the request query parameters. Any parameters that match permission=foo will get added to a permissions block on the user. If there are none, the permissions block will be set to empty. We will also want to update our User schema to return these permissions as part of our normal retrieval functionality.

/app/models/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},
    permissions: [String]
});

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

Here we simply added an Array of Strings named permissions to the Schema.

And update the POST and PUT blocks in /app/routes/user.js to include

user.permissions = req.query.permissions || [];

where we set the other user properties. Now, using our Postman utility, create or update an existing user and some permissions to the url. For example:

localhost:1337/api/users/54ea3206488bfd24c5ac7ee8?permissions=admin&permissions=superhero

This would then add admin and superhero to our permissions array. If we leave them off, an empty array is used. Again, this is The Wrong Way to do this, but it will serve our purposes.

Changes

So, let's run down the code changes we are going to make

We are going to modify our backend server code and
- create an /api/authenticate endpoint that will accept credentials. If successful, it will return a token.
- modify the /api/user(s) endpoints to check for the presence of a valid token before performing any actions. If one is not found, a 401 Unauthenticated error code will be returned.
- modify the DELETE /api/users/:user_id endpoint to verify the authenticated user also has admin permissions. If not, a 403 Unauthorized error code will be returned.
- update our server to accept requests from other domains. (More on this later).
We will create a login screen and
- extend the existing single user form view
- add some simple client side validation to enforce name and email requirements
- call the authentication endpoint
- upon successful login we'll store the token received
We will create a logout action in our navigation bar that
- will be visible only when logged in
- will remove the stored token when activated
We will display information about the logged in user in the navigation bar
We will modify our router to
- ensure that we are authenticated before showing the Users view
We will create an application wide object to
- perform authentication and logout actions
- provide access to our currently logged in user
We will add application wide AJAX error handling

Server Updates

Authentication Endpoint - Until now, we've been storing our passwords in the database in cleartext. We should really be encrypting them. Let's grab a crypto library to handle that, along with the JSON Web Tokens library.

npm install bcrypt-nodejs jsonwebtoken --save

In /app/models/user.js let's go ahead and require the crypto library and add some functionality to use it.

var bcrypt = require('bcrypt-nodejs');

UserSchema.pre('save', function(next){  
    var user = this;
    if (!user.isModified()){
        return next();
    }

    bcrypt.hash(user.password, null, null, function(err,hash){
        if (err) {
            return next(err);
        }
        user.password = hash;
        next();
    })
});

UserSchema.methods.comparePassword = function(password){  
    var user = this;
    return bcrypt.compareSync(password, user.password);
};

We have two things going on here. First, we've added a hook to the User schema that will get called before any Save operation. If the document has been modified, or is new, we assume the password has been modified and is in cleartext. We convert it to an encrypted form, and then let the normal save function occur.

Secondly, we've added a comparePassword method to the User object. When we authenticate a user, we will use this compare the submitted password to the stored one.

Now let's update our user routes in /app/routes/user.js. First add our dependency:

var jwt = require('jsonwebtoken');

var superSecret = 'TheAmazingKreskin`;

We've also created a "secret word" that we will use when encrypting and decrypting our token. This should probably be stored in a config file or passed in on the command line for better security.

After our default /api/ route, let's create our /api/authenticate route

var userRouter = express.Router();

userRouter.post('/authenticate', function (req, res) {  
    User.findOne({
        email: req.body.email
    }).select('name email password').exec(function (err, user) {
        if (err) throw err;

        if (!user) {
            res.json({success: false, message: 'User not found'});
        } else {
            var validPassword = user.comparePassword(req.body.password);
            if (!validPassword) {
                res.json({success: false, message: 'Wrong password'});
            } else {
                var token = jwt.sign({
                    name: user.name,
                    email: user.email,
                    _id: user._id
                }, superSecret, {
                    expiresInMinutes: 1440
                });

                res.json({
                    success: true,
                    message: 'login ok',
                    token: token,
                    _id: user._id
                });
            }
        }
    });
});

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

When receive the POST request, we lookup the user by the provided email, and select their name and password as well. Remember, by default, our Schema does not return a password. In the event of an error or the user is not found, an error is returned to the user. In this instance, we don't send an error response. We expect that an unsuccessful attempt is a common occurrence, so we will explicitly handle the response. In this way, we could count the number of attempts or provide extra help, rather than just redirecting back to the login page.

If the user is found, we compare the submitted password to the one on record. If successful, we create a token with some user info in it and a timeout of 1440 minutes, or 24 hours. This will force the user to reauthenticate after one day, even if they have a proper token. Encrypting it will prevent the token from being modified by the client.

Using our Postman extension, we can test this endpoint right away. Using our prvious user editing capabilities, change the password on one of the users. This will ensure that the password associated with the user is encrypted in the database. (In fact, you may want to clean out any other users you created since they will need to have their passwords reset. For a production app, we could trap for this condition and handle it gracefully. Let's just delete them and make new ones.)

Make a POST request to /api/authenticate with a body of

{"email" : "email_value", "password": "password_value"}

using the values for that user you updated. Remember to set the Content-Type header to application/json. If the passwords match, you should see a response similar to

{
    "success": true,
    "message": "login ok",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiQnJpYW4gTSIsIl9pZCI6IjU0ZTZiMTYyZWIyYWM2MWM1NGU5YjgwZiIsImlhdCI6MTQyNDkyNTA4MCwiZXhwIjoxNDI1MDExNDgwfQ.90utguKl1XrpQZHU6tYPzOhskOeSl4k5RTTk6JcbuDo",
    "_id": "54e6b162eb2ac61c54e9b80f"
}

Even with our authentication endpoint in place, we have no problem accessing our app, even if we provided the wrong password. We'll need to tell the other routes to check for a valid token to be sent with every request.

After our default route, add the following code. Since this is declared after the default route, we will still be able to access it without authentication.

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

userRouter.use(function (req, res, next) {  
    var token = req.body.token || req.params.token || req.headers['x-access-token'];
    if (token) {
        jwt.verify(token, superSecret, function (err, decoded) {
            if (err) {
                return res.status(401).send({success: false, message: 'Failed to authenticate token'});
            } else {
                req.decoded = decoded;
                next();
            }
        })
    } else {
        return res.status(401).send({success: false, message: 'No token provided'});
    }
});

With the use directive, we are adding some middleware to our route. For every request on routes declared after this we will attempt to find a token value in the body, in the parameters, or even in the headers. If a token is found, we verify it with our secret word. If it is valid, we continue to the next request handler, which will be our standard GET, PUT, POST, etc. calls. If there is no token, or it is invalid, we send a 401 HTTP error with an appropriate message. Our client will know that it needs to reauthenticate when it receives such a message.

Now, if we try to access our users page, we will get an error and nothing will display.

Next Steps

In our next installment, we'll wire up the client to call the authenticate endpoint when needed and send our token on future calls.

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

(Re)Learning Backbone Part 8

Brian Majewski — Tue, 24 Feb 2015 05:02:02 GMT

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

A Little Cleanup

Back when we created the REST endpoints, we returned some "friendly" success messages. Without a UI, these made it easy to see when the requests went through. Now that we are going to be using them, let's have them return something more useful.

For GET /api/users and GET /api/users/:user_id, we already return an array or a single user, as appropriate. Let's do the same for POST /api/users and PUT /api/users/:user_id. For these, we will return the User that was either just created or was updated. There is no user we can return after a DELETE, so we can return an empty object. Our updated /app/routes/user.js code now looks like this:

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.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(user);
                }

            });
        })
        .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(user);
                });
            });
        })
        .delete(function (req, res) {
            User.remove({_id: req.params.user_id}, function (err, user) {
                if (err) res.send(err);
                res.json({});
            })
        });

    return userRouter;
};

Adding Actions To Our User List

We're going to want to be able to Add a User, and Delete or Edit a specific user. Let's start with Delete.

Let's add a column to our table on the right side to hold user specific actions. Add a blank to our and a in our #each loop. In the add the following:

This will display a Delete button. We've added a data=id attribute to hold the User id. This will allow us to specify which User to delete. We've also added a js-deleteUser class to the button. We are using the js-* pattern for class names that indicate functionality as opposed to design.

Now, let's add the functionality to perform the delete in /app/users/listView.js. Under the el declaration, add an events block

events: {  
    'click .js-deleteUser': 'deleteUser'
},

On the left, we define an event and a CSS selector for the event, and on the right, a method to handle the event. In this case, we are trapping for a click event on any item with a class of js-deleteUser, and delegating to the deleteUser method to handle it. Let's create that method now.

deleteUser: function(e){  
    var self = this;
    var id = $(e.currentTarget).attr('data-id');
    var user = this.collection.get(id)
    user.destroy().done(function(){
        self.collection.remove(user);
        self.render();
    });
}

Here we ask the object that triggered the event for the value of its data-id attribute, and retrieve that user from our collection. We trigger the destroy method provided by Backbone, we will call our REST backend. When it is complete, we remove the user from the collection, and redraw the table.

Reload the app, and delete a user. If you don't have any to delete, you can either use the Postman extension to add some more, or, we can forge ahead and wire in an Add button.

We want to have a modal dialog popup with a form that will allow us to enter in a name, an email, and a password, along with a button to save it. With a little bit of configuration, we can use this same dialog to edit an existing user. To do the heavy lifting, we're going to add in a few libraries. Since we are using Bootstrap for our CSS, let's just dive in and grab the whole framework. We'll still only pull in what we need as we need it. We're also going to use a Backbone plugin to wrap the Bootstrap modal functionality so that we can easily interact with it from our views. Adding backbone.bootstrap-modal with bower will pull both libraries in.

We also want to incorporate data-binding. Data-binding is one of the big features that frameworks like Angular and Ember pitch as a benefit. We're going to get all the functionality they provide with much greater and explicit control of when we use binding and how for a lighter footprint on our page. For this, we will use stickit from the NYTimes. Install both these libraries with

bower install backbone.bootstrap-modal backbone.stickit --save

and update the require-main.js file

"bootstrap-modal": "../components/bootstrap/js/modal",
"backbone.bootstrap-modal": "../components/backbone.bootstrap-modal/src/backbone.bootstrap-modal",
"stickit" : "../components/backbone.stickit/backbone.stickit"

Let's once again update our list view, with an Add button at the top of the page and an Edit button next to the Delete.

/app/users/list.hbs

  
    Users
  

    {{#each users}}
        
    {{/each}}
      
    
    ID
    Email
    Name
    
    
    
            {{_id}}
            {{email}}
            {{name}}

ID	Email	Name
{{_id}}	{{email}}	{{name}}

Since we are using the same code for both editing and adding, we've added the same class, js-editUser to both. To the Edit button, we add a data-id attribute. If we were going to add any more actions, we might consider putting the ID on the row once for all the fields. For now, we'll stick with this.

Let's update our List view to trap for the new event.

events: {  
    'click .js-deleteUser': 'deleteUser',
    'click .js-editUser': 'editUser'
},

and

editUser: function(e) {  
    var id = $(e.currentTarget).attr('data-id');
    var options = id ? {title: 'Edit User', model: this.collection.get(id)} : {title: 'Add User'};
    console.log('options', options);
}

We don't have anywhere to send the user just yet, so we'll construct our options and log them to verify our event is wired in. Here we check for a data-id value on the element. If we have one, we are going to edit the user, so we set an appropriate title for our soon to be created dialog, and retrieve the user from the collection. If there is no data-id, like on the Add button, we set the title to 'Add User', and leave the model undefined. Reload your app and verify that we have all this working.

Creating our Dialog

Whether we are adding or editing a User, we will need a form with fields to enter data. Let's create a template for one, wrapped in the markup to create a Bootstrap modal dialog.

/app/users/single.hbs

This is mostly boilerplate Bootstrap code. Notice that we have assigned IDs to the form fields. We will use these to bind our data. Because we are binding our data, we don't need to use any template substitution for these values. We have also added a variable to hold our title at the top, and we added a js-saveUser class to our Save button. We'll use Bootstrap's built in functionality to cancel/close the modal when the user hits the Cancel or Close buttons.

To pair with our template, we will create a simple Backbone view. This view will handle binding our model data to the form fields and vice versa. It will also persist the data when the Save button is pressed.

/app/users/singleView.js

define(function (require) {

    'use strict';
    var Backbone = require('backbone');
    var mediator = require('mediator');
    var template = require('hbs!users/single');

    require('stickit');

    var User = require('users/model');

    return Backbone.View.extend({
        initialize: function (options) {
            this.title = options ? options.title : 'Please Set A Title';
            this.model = this.model || new User();
        },

        bindings: {
            '#name': 'name',
            '#email': 'email',
            '#password': 'password'
        },

        events: {
            'click .js-saveUser': 'saveUser'
        },

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

        saveUser: function () {
            var self = this;
            this.model.save().done(function (response) {
                if (self.model.isNew()) {
                    self.model.set('_id', response._id);
                }
                mediator.trigger('users:userSaved', self.model);
            });
        }
    });

});

At the top, we require our dependencies. We also include stickit here. Since it is a plugin, we don't need to assign it to anything. In our initialize method, we set some default values if the options passed to us don't have them. We also create a new User if we need one, as is the case for when we are adding one.

The bindings block is new. This is how we configure stickit. In this simple example, we map our CSS selectors on the right to User model attributes on the left. Stickit can do a lot more than this so read the docs.

We set up a standard events entry to trap for the Save button.

In our render method, we render our template as normal, then call stickit to activate the bindings.

Finally, we create a saveUser method. We use Backbone's built in save functionality. This will determine if the User is new or being edited, and call the appropriate backend method. When we get a successful response, we update our object with an _id value if necessary, then fire off a message to let our list view know we are done. We do this so that the list view can manage the lifecycle of the dialog window, including the opening and closing of it.

Let's now go back to our list view and update it to manage the dialog window.

Add our new dependencies

var mediator = require('mediator');  
var SingleView = require('users/singleView');  
require('bootstrap-modal');  
require('backbone.bootstrap-modal');

Since we are going to be responding to message, let's wire that up:

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

bindPageEvents: function(){  
    mediator.on('users:userSaved', this.userSaved, this);
},

userSaved: function(user){  
    this.modal.close();
    this.collection.add(user);
    this.render();
}

When we receive a message that the user has been saved, we close the modal that we will soon create, add the passed user to our collection, and rerender the table. If the user has an id that is already part of our collection, it will update itself, otherwise it will add itself.

Finally, lets create the modal. Let's go back to our editUser method

editUser: function(e) {  
    var id = $(e.currentTarget).attr('data-id');
    var options = id ? {title: 'Edit User', model: this.collection.get(id)} : {title: 'Add User'};
    var modalView = new SingleView(options);
    this.modal = new Backbone.BootstrapModal({content: modalView}).open();
},

We've removed the logging. We instantiate the view that holds our form fields with the options we've created. We then wrap that view with a Backbone.BootstrapModal view and open it. Simple as that. Reload your app and try adding and editing some Users.

Let's make one final cosmetic tweak. Since the last column in the table is always the same visually, let's turn sorting off for it. Pass in the following options when we construct the DataTable

this.$('table').DataTable({  
    "aoColumns": [
        null,
        null,
        null,
        { "bSortable": false }
    ]
});

Next Steps

We now have a relatively full featured CRUD management tool. We could easily add new entities by following the patterns we have set up here. Could we have generated these much quicker with an all encompassing framework? Sure. The use of small focused plugins, however, has kept our boilerplate code to a minimum and we have had full control over every line of code.

The last big piece that we are going to add that I consider mandatory for a starter app is authentication. We will put all the User editing functionality behind a login screen and see how to hold and use application wide data, such as the currently logged in user.

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

(Re)Learning Backbone Part 7

Brian Majewski — Sun, 22 Feb 2015 23:13:29 GMT

(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

  
     Users

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

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

Now let's create our template and view

/app/users/list.hbs

  
    Users
  

    {{#each users}}
        
    {{/each}}
      
    
    ID
    Email
    Name
    
    
            {{_id}}
            {{email}}
            {{name}}

ID	Email	Name
{{_id}}	{{email}}	{{name}}

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.

(Re)Learning Backbone Part 6

Brian Majewski — Sun, 22 Feb 2015 00:14:37 GMT

(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

  
  
{{> ./footerTemplate}}

/app/page/headerTemplate.hbs

  
    
        
            
                relearning backbone
            
            
                [Navigation Elements]

/app/page/footerTemplate.hbs

Relearning Backbone - http://brianmajewski.com

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

  
    WELCOME TO OUR APPLICATION

/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)

(Re)Learning Backbone Part 5

Brian Majewski — Sat, 21 Feb 2015 04:34:43 GMT

(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 "
  ],
  "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 of our document, beneath our styles.

  
    
    
    Relearning Backbone

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)

(Re)Learning Backbone Part 4

Brian Majewski — Fri, 20 Feb 2015 04:17:04 GMT

(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)

Some people prefer to include the function in the name, such as userModel.js and userRoute.js. I go back and forth on this. They are namespaced by their directory structure, so if there is no chance I am going to get them confused, I'll shorten them like I did here. You can name them mickey, pluto, and goofy if that floats your boat. I prefer frameworks without magic naming conventions. ↩

(Re)Learning Backbone Part 3

Brian Majewski — Sun, 15 Feb 2015 20:30:19 GMT

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

  
  
  
    
    
    Relearning Backbone
    
  
  
Relearning Backbone

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.

(Re)Learning Backbone Part 2

Brian Majewski — Fri, 13 Feb 2015 16:36:57 GMT

Opinions are like birthdays: everyone has one and I heard about yours on Facebook.

Tool Sets and Libraries

This is easily the most opinionated part of this process. I am always open to code changes; hearing the viewpoints of other developers who may have more experience or a different perspective often lead me to change my code. We call it software for a reason. It should be malleable. It should adapt. When it comes to my tools, however, that's a different story.

OS - Mac OS X

Let's get the holy war out of the way. If you use Windows, more power to you. You must like the extra challenges of playing on Expert mode. For me, there are three key reasons I develop on the Mac.

Environment: Most every environment I am going to deploy to is a *nix variant. Having a BASH (or similar) shell integrated into the OS allows me to create workflows that work everywhere I do.
The Cool Kids Use It: Most of the developers and designers that I read and learn from are using it. This isn't simply a case of "me too!" This is a case where I want zero impediments in my way of completing my task. If they recommend a tool or a library or even some non-web-dev related utility, I'd rather be able to copy them than go searching for an equivalent.
Comfort: I've worked on Apple hardware since the Apple][ days. It just makes more sense to me.

So, yeah, use Windows if you want. Good luck with that.

IDE - Jetbrains IntelliJ IDEA (or Webstorm)

I'm maybe a little bit more flexible on this issue, but not by much. As a professional developer who works with a number of different languages and technologies, having a tool that works across all of them is something I find is worth my investment in time and money. I've been using it since Version 1 when I met the original developers at a conference in Prague. It has been my IDE of choice ever since. Any good text editor like Sublime or Atom can be a useful tool with the right setup and plugins. IDEA mostly works out of the box with deep support for things like Node, Angular, Grunt, and the like.

Brew

Brew is "The missing package manager for OS X" and allows you to install and maintain the tools used to develop and build. Get it. Install it. If you like GUIs, get Cakebrew.

Node

We're going to use Node to stand up a web server to serve our REST endpoints and access the database. DO NOT simply go to the website, download the package and install it. You'll end up in a world of hurt, having to run everything as sudo. Use Brew (see above). $ brew install node Should we switch over to io.js? Maybe? This is one of those rat holes I wanted to avoid with this project. Investigating io.js is an endeavor for another day.

MongoDB

Is MongoDB the right database for your application? Who knows? For this project, we want a simple document datastore that has some easy integration with javascript. We could serve up JSON files instead of hitting a datastore, but that doesn't meet the requirements of having a fully functional application from soup to nuts to build off. We can always swap it out for another technology. Again, use Brew to install it.

Next Steps

At this point, we have the makings for a web server that can serve up data. Well, we have the tools anyways. In the next installment, we'll create a project structure and web server we'll use throughout the project.

(Re)Learning Backbone Part 1

Brian Majewski — Mon, 09 Feb 2015 16:40:53 GMT

A Little Bit of History

Two years ago, I was dropped head first into a large corporate Javascript project. Our flagship application's front end at the time was being developed in GWT. It had become too large for its own good: long compile times, a complicated Gradle build process orphaned by a developer who had moved on to a new job, and, most importantly, the difficulty of incorporating new open source Javascript frameworks for things like graphing or animations.

My boss, the VP of Engineering, felt our pain and championed the decision to "forklift" our app over to a pure Javascript implementation. In hindsight, this was probably a too ambitious task given a team of Java developers with minimal and/or rusty Javascript skills. The project was a go, however, and we moved forward.

We spent a good amount of time up front reviewing our options. At the time, Ember and Angular held a lot of promise, but ultimately were too green for our project. We wanted to engage with an outside firm to help kickstart the project and develop some patterns for our team to learn from. We needed to pick something that would assist us in making the language switch without being overly prescriptive.

Enter Backbone

For the first 6 weeks or so, our team of two external consultants took our existing application and created a new framework, based on Backbone. The goal was for a minimally functional application, working end to end - authentication, consuming (existing) REST services, displaying data and persisting changes. A basic CRUD application that our internal team could iterate on.

Of course, our "partners" in Marketing insisted that there be no UX changes, no functional changes, and that it be updated with a new CSS makeover. Additionally, any internal application SMEs had long ago left the company, so any information regarding how a feature worked, why something might be validated in a certain way, etc. was to be gleaned from the existing codebase, written primarily by developers long since gone. Oh, it had to be done in 6 months, and this would be blocking any new feature development and potentially impacting our deliverables.

My team rose to the occasion. Given all of these constraints, they developed a good-looking, performant application that was identically functional in an amazing timeframe. The pace of this development did come at a cost: There was no time for reflection, refinement, or absorption. Development challenges would arise, square pegs were jammed in round holes, and we moved on to the next feature. Aha moments were never shared. But we delivered.

And Now?

In the time since then, I have taken on professional engagements with both Angular and Ember projects. There have been so many times when I have been able to quickly do something that frustrated me for days previously. This, however, is due to simply being more proficient and comfortable in the development space. Both of these frameworks introduce their own flavors of complexity and challenges.

Currently my team maintains and enhances a large, but relatively straightforward, Ember application. Even so, I hear complaints about not 'getting the framework' and developers feel they are 'poking around and making tweaks', having not really had the immersive indoctrination to Ember.

Personally, I have a number of side projects that I would like to work on. My biggest stumbling block is picking a technology stack to start with and actually working on the project part. I find I'll read about a new framework, spend some time dinking through the tutorials, have some minimal Todo MVC clone, and then be left where I started. So I set myself out a challenge.

The Challenge

Instead of working on a project for the feature set, I would work on building out a scaffold that I could then use as a starting point for a project. The scaffold had to be more than some directory structures. It had to be what I asked that consulting firm for a few years ago: A working end to end application with authentication, REST interaction, etc. Something I could start adding features to from the jump.

Recently, Derick Bailey wrote about "opinionated frameworks". This made me think that, even more so than the frameworks, my code is opinionated. I want it to work in a way that makes sense to me. Libraries and frameworks are great at speeding up development, but in many cases they abstract away the details too much, and obscure a fundamental understanding of what they are doing, and more importantly, why. I picked Backbone as my base and dug in.

This past weekend, from scratch, I built up the first iteration of the project. I did in about 20 hours what I formerly paid a couple guys to do in 6 weeks. More importantly, I understand every single line of code and why I put it there. Is it perfect? Hell no. Could it be improved? Of course, and it will be. What it is is tangible. I can fork the repo today and start building out a new app. Which, hopefully, now I will do.

Next Steps

Over the next few weeks, I will break down the app into chunks and talk about how it works and why it works. If you follow along, hopefully, you too will understand a little bit more about how a single page application works end to end. Whether you stay with Backbone or choose a more inclusive framework, I hope that you'll learn a bit more than following along with code samples from a contrived example.

Next Time: Tool Sets and Libraries

Thieves Like Us

(Re)Learning Backbone Part 12

(Re)Learning Backbone Part 11

(Re)Learning Backbone Part 10

Login

(Re)Learning Backbone Part 9

(Re)Learning Backbone Part 8

UsersAdd User

{{title}}

(Re)Learning Backbone Part 7

Users

(Re)Learning Backbone Part 6

WELCOME TO OUR APPLICATION

(Re)Learning Backbone Part 5

(Re)Learning Backbone Part 4

(Re)Learning Backbone Part 3

Relearning Backbone

(Re)Learning Backbone Part 2

(Re)Learning Backbone Part 1

Users