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 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 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 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.

Thieves Like Us

(Re)Learning Backbone Part 12

(Re)Learning Backbone Part 10

Login

(Re)Learning Backbone Part 8

UsersAdd User

{{title}}

(Re)Learning Backbone Part 4

(Re)Learning Backbone Part 3

Relearning Backbone

(Re)Learning Backbone Part 2

Users