jQuery

The most basic option in serializing a form’s elements in to use jQuery’s serialize or serializeArray methods. These methods work well and make it easy to get data out of your form. But they have limitations that I don’t like:

The serialize method encodes the values in to a URL encoding. This works well if you plan on using the data as URL parameters in an HTTP GET or other similar manner. But if you want to use the data in your JavaScript code, it’s a bit of a pain to work with.

The serializeArray method return a JavaScript array that contains objects each with a name and value key. So, a text input with a “name” of “foo” would return [{name: "foo", value: "bar"}]. This works much better for dealing with the data in your JavaScript code, but is still severely constrained. You don’t have direct access to the key/value pairs based on the name of the input element. Instead, you have to search through the array of objects and find the one you want. 

What I want, instead, is a way to serialize a form into a plain JavaScript object where the object’s attributes (or keys) are the input element ids, with the key’s value set to the value of the input element.

Backbone.Syphon

Backbone.Syphon aims to make it easy to serialize the form inputs of a Backbone.View in to a simple JSON object that contains all of the values from the form. All you need to do is call `Backbone.Syphon.serialize(view)` and it will return a JavaScript object to you with key / value pairs that match the input element ids and values.

For example, with this underscore template:

<script id="my-form-template" type="text/html">
  <form>
    <input type="text" id="foo" value="bar">
    <input type="checkbox" id="chk" checked>
  </form>
</script>

And this Backbone.View setup:

Backbone.View.extend({
  events: {
    "submit form": "formSubmitted"
  },

  formSubmitted: function(e){
    e.preventDefault();

    var data = Backbone.Syphon.serialize(this);
    this.model.set(data);

    this.model.save();
  },

  render: function(){
    // build the view's form, here
  }
});

When you click the “save” button, the handler for the click calls `Backbone.Syphon.serialize(this)`. This returns an object that looks like this:

{
  foo: "bar",
  chk: true
}

The large benefit of this output is that you can immediately pass it to a Backbone.Model instance via the `set` method. There’s no need to sift through it and pull out the bits you need, like the jQuery serialize methods. Of course you can use it for more than just Backbone models, too. Anywhere that you need the data from your form, you can get it with Syphon and use it right away.

I use this plugin in several of my projects already – well, precursors that were poorly written and not tested thoroughly, at least. But I plan on continuing to use this plugin in scenarios where I need to get data out of my forms. Data-binding plugins just don’t interest me anymore, as I’ve gone down that path and abandoned it. 

Serializes By Element Id

There are a handful of limitations in this first release. One of the largest is that all of the input elements will be serialized by the `id` attribute of the element. Look at the example above again, and you’ll notice that the text input with an id of “foo” was serialized in to a `{foo: “bar”}` attribute on the resulting object. I’m sure this will change over time, and become something more configurable. But for now, this was all I needed as I tend to use the id of a field as the key for my object’s data.

For more information on the current limitations, see the documentation.

Some-what Pluggable Serialization

I’ve built this plugin more than a few times at this point, starting with direct client needs and eventually turning in to the plugin that it is now. One of the lessons that I learned in rebuilding it a few times is that the process of serializing the input elements needs to be pluggable. I can’t limit how it reads the data from the input elements, because there are different needs for different situations. 

With that in mind, I built in the idea of “Input Readers“. An Input Reader is a callback function that is registered against a particular input type, and is used to read the data from that type of input. 

At the moment, there are only two built in input readers: the default, which handles nearly everything, and the checkbox reader. The default reader uses jQuery’s `val()` function to get the value out of the input. This works for nearly every type of input. But there are some cases where this isn’t what you want to do. For example, I generally use checkboxes as boolean values instead of an actual text value. To handle this, then, I created the built in checkbox input reader. It uses jQuery’s `prop()` function to read the state of the checkbox and tell me whether or not the checkbox is checked. If you look at the previous example again, you’ll see that the “chk” checkbox is returning a boolean value.

Initial Build And Release As A Screencast

There are several reasons that this initial release is so small and limited in scope and functionality. The largest of which is that it covers the majority of my needs, and like all of my plugins and add-ons, I figure out what I need and the common things that I do across projects first. Then when I have the majority of my cases covered, I start looking at what others need in order to get their projects up and running.

Another reason that this release is limited, is because I decided to record the creation of the plugin as a live screencast – a “prequel” of sorts, to the first “Refactoring JavaScript” screencast that I released last year. In this case, the end product of the Backbone.Syphon plugin is more of a side effect than the purpose of the screencast. The real focus of the screencast is the tools and processes that I use to get a plugin like this off the ground, built and delivered. 

If you’re an audio/video learner and you want to see my process for creating something from nothing more than the ideas in my head, then you should check out Episode 7 of WatchMeCode: Building A Backbone Plugin (Live). And if you’re looking for a way to get up to speed with test-driven JavaScript, including a basic introduction to Jasmine and refactoring an existing application that is covered by Jasmine tests, then you might be interested in the Jasmine Live! multi-pack of screencasts.

Documentation, Downloads, And Moving Forward

If you’d like to get your hands on Syphon, head over to the Github repository. There are links to the the downloads and a little bit of documentation to show how to use it (the same as what I showed here), as well as some discussion on the current limitations of the plugin.

I’m hoping to get some input and assistance from others that could use a plugin like this, moving forward. I’d like to see this project fleshed out so that it can be used in a broader set of scenarios, with more options for how the data is serialized from the input elements. At the same time, though, I’m going to be rather picky about how the implementation moves forward. I don’t want to end up with another 1,000 line blob of unmaintainable garbage, like my ModelBinding plugin. As it stands now, though, Syphon’s code is starting out on the right foot. I just need to keep it heading down a clean path as it moves forward.

Here’s the gist of that again:

orgChart = {

  addNewEmployee: function(){
    var that = this;

    var employeeDetail = this.getEmployeeDetail();
    employeeDetail.on("complete", function(employee){

      var managerSelector = that.selectManager(employee);
      managerSelector.on("save", function(employee){
        employee.save();
      });

    });
  },

  getEmployeeDetail: function(){
    var form = new EmployeeDetailForm();
    form.render();
    $("#wizard").html(form.el);
    return form;
  },

  selectManager: function(employee){
    var form = new SelectManagerForm({
      model: employee
    });
    form.render();
    $("#wizard").html(form.el);
    return form;
  }
}

// implementation details for EmployeeDetailForm go here

// implementation details for SelectManagerForm go here

// implementation details for Employee model go here

I’ve implemented various views and objects in various manners, in order to facilitate that workflow, but what it always comes down to is that the objects facilitating the workflow need to trigger events. 

A Basic Implementation

The most common way of triggering an event from a Backbone.View is to have some DOM events handled, and from the event handler/callback method for that, trigger the event you want:

SomeView = Backbone.View.extend({

  events: {
    "click .next": "nextClicked",
    "click .previous": "previousClicked"
  },

  nextClicked: function(e){
    e.preventDefault();
    this.trigger("next")
  },

  previousClicked: function(e){
    e.preventDefault();
    this.trigger("previous");
  }

});

This works well. I’ve done this more times than I can count. But there’s a lot of redundancy here. You can see that both of the DOM events that I’m handling have a callback method, and both of the callback methods do nothing more than trigger an event from the view itself so that the workflow can move forward.

We can do better than that… enter Marionette’s new “triggers”.

Reducing Event Triggering To Configuration

With the v0.8.2 release of Marionette, I’ve introduced the idea of view triggers – a way to configure a DOM event to trigger a view event. So instead of having to write all of that redundant code, where the only real difference is the name of the callback method and the name of the event that’s triggered, we can write this:

SomeView = Backbone.Marionette.ItemView.extend({

  // ...

  triggers: {
    "click .next": "next",
    "click .previous": "previous"
  }

});

Must shorter. Much cleaner.

You can see that the left side of the hash is a standard Backbone.View events setup where you specify the DOM event and element selector. Then on the right hand side, specify the name of the event that you want the view to trigger when that DOM event fires. Then, when I click on the “.next” element, the view will trigger a “next” event for me. Similarly, clicking the “.previous” element will trigger a “previous” event.

Trigger From Any Marionette View

Triggers can be used from any Marionette view. You’re not limited to the ItemView type that I showed. In fact, the trigger functionality is built in to the base Backbone.Marionette.View, so even if you are creating your own specialized view type, you only need to extend from that in order to get this functionality.

Limitations

Of course this isn’t a “complete” solution for handling events in your views, by any means. If you need to do anything more than trigger the event by itself, you should still use a standard event handler and callback method. At this point, there’s no way for you to configure any kind of data or objects to be passed through the event itself. But this may be added at some point in the future. I wrote this fairy quickly last night, and it suits my needs right now. 

For simple scenarios where you just need to trigger an event from the view, though, this works well. I’m using it in several places where my workflow is just to display a button or a link, and have that clickable item move on to another part of the application.

A Poorly Constructed Workflow

It seems to be common in the JavaScript applications world, to have very poorly defined and constructed workflow in applications. We take one object and build some functionality. Then when the next part of the app needs to fire up, we call the object that runs it directly from the first object. Then when the next part of the app is requested, we call that object from the second one. And we continue on down this path ad-infinitum, creating a mess of tightly coupled concerns, tightly coupled concepts, tightly coupled objects, and a brittle and fragile system that is dependent entirely on the implementation details to understand the higher level concept.

For example, might have a human resources application that allows you to add a new employee and select a manager for the employee. After entering a name and email address, we would show the form to select the manager. When the user clicks save, we create the employee. A crude, but all too common implementation of this workflow might look something like this:

EmployeeInfoForm = Backbone.View.extend({
  events: {
    "click .next": "nextClicked"
  },

  nextClicked: function(e){
    e.preventDefault();

    var data = {
      name: this.$(".name").val(),
      email: this.$(".email").val()
    };

    var employee = new Employee(data);

    this.selectManager(employee);
  },

  selectManager: function(employee){
    var view = new SelectManagerForm({
      model: employee
    });
    view.render();
    $(".wizard").show(view.el);
  },

  // ...
  render: function(){ ... }
  // ... etc
});

SelectManagerForm = Backbone.View.extend({
  events: {
    "click .save": "saveClicked"
  },

  saveClicked: function(e){
    e.preventDefault();

    var managerId = this.$(".manager").val();
    this.model.set({managerId: managerId});

    this.model.save();
    // do something to close the wizard and move on  
  },

  // ...
  render: function() { ... }
  // ... etc
});

Can you quickly and easily describe the workflow in this example? If you can, then you’re a better person than I am. I have to spend time looking at the implementation details of both views in order to see what’s going on and why. I have to piece together the bits from multiple places and form a more coherent high level overview in my head. It’s not easy for me to see what’s going on because every time I look at another part of the code, I have to put together the pieces again to make sure I am not breaking someone from the other parts.

Too Many Concerns

We’ve mixed two different concerns in to very few objects, and we’ve taken those concerns and split them apart in some rather un-natural ways at that.

The first concern is the high level workflow:

1. enter employee info
2. select manager
3. create employee

The second concern is the implementation detail:

1. Show the EmployeeInfoForm 
2. Allow the user to enter a name and email address
3. When “next” is clicked, gather the name and email address of the employee. 
4. Then show the SelectManagerForm with a list of possible managers to select from. 
5. When “save” is clicked, grab the selected manager
6. Then take all of the employee information and create a new employee record on the server

And I haven’t even gone through any of the secondary and third level workflow in this. What happens when the user hits cancel on the first screen? Or on the second? What about invalid email address validation? If we start adding in all of those steps to the list of implementation details, this list of steps to follow is going to get out of hand very quickly.

By implementing both the high level workflow and the implementation detail in the views – the details and implementation – we’ve destroyed our ability to see the high level workflow at a glance. That will cause problems for us as developers, because we will forget some of those details when changing the system, and we will break things.

Modeling An Explicit Workflow In Code

What we want to do, instead, is get back to that high level workflow with fewer bullet points and very little text in each point. But we don’t want to have to dig through all of the implementation details in order to get to it. We want to see the high level workflow in our code, separated from the implementation details. This makes it easier to change the workflow and to change any specific implementation detail without having to rework the entire workflow.

Wouldn’t it be nice if we could write this code, for example:

orgChart = {

  addNewEmployee: function(){
    var employeeDetail = this.getEmployeeDetail();
    employeeDetail.on("complete", function(employee){

      var managerSelector = this.selectManager(employee);
      managerSelector.on("save", function(employee){
        employee.save();
      });

    });
  },

  // ...
}

In this pseudo-code example, we can more clearly see the high level workflow. When we complete the employee info, we move on to the selecting a manager. When that completes, we save the employee with the data that we had entered. It all looks very clean and simple. We could even add in some of the secondary and third level workflow without creating too much mess. And more importantly, we could get rid of some of the nested callbacks with better patterns and function separation.

But let’s see what this would really look like in code that we could execute:

orgChart = {

  addNewEmployee: function(){
    var employeeDetail = this.getEmployeeDetail();
    employeeDetail.on("complete", function(employee){

      var managerSelector = this.selectManager(employee);
      managerSelector.on("save", function(employee){
        employee.save();
      });

    });
  },

  // ...
}

Yeah – turns out this is code that we can actually run, and it can be implemented fairly easily with a couple of Backbone views and a model for the details:

orgChart = {

  addNewEmployee: function(){
    var that = this;

    var employeeDetail = this.getEmployeeDetail();
    employeeDetail.on("complete", function(employee){

      var managerSelector = that.selectManager(employee);
      managerSelector.on("save", function(employee){
        employee.save();
      });

    });
  },

  getEmployeeDetail: function(){
    var form = new EmployeeDetailForm();
    form.render();
    $("#wizard").html(form.el);
    return form;
  },

  selectManager: function(employee){
    var form = new SelectManagerForm({
      model: employee
    });
    form.render();
    $("#wizard").html(form.el);
    return form;
  }
}

// implementation details for EmployeeDetailForm go here

// implementation details for SelectManagerForm go here

// implementation details for Employee model go here

I’ve obviously omitted some of the details of the views and model, but you get the idea.

The Benefits

There are a number of benefits to writing code like this. It’s easy to see the high level workflow. We don’t have to worry about all of the implementation details for each of the views or the model when dealing with the workflow. We can change any of the individual view implementations when we need to, without affecting the rest of the workflow (as long as the view conforms to the protocol that the workflow defines). And there’s probably a handful of other benefits, as well. 

But the largest single benefit of all these, in my experience, is being able to see the workflow at a glance. 6 months from now – or if you’re like me, 6 hours from now – you won’t remember that you have to trace through 5 different Views and three different custom objects and models, in order to piece together the workflow that you spun together in the sample at the very top of this post. But if you have a workflow as simple as the one that we just saw, where the workflow is more explicit within a higher level method, separated from the implementation details… well, then you’re more likely to pick up the code and understand the workflow quickly. 

The Drawbacks

Everything has a price, right? But the price for this is fairly small. You will end up with a few more objects and a few more methods to keep track of. There’s a mild overhead associated with this in the world of browser based JavaScript, but that’s likely to be so small that you won’t notice.

The real cost, though, is that you’re going to have to learn new implementation patterns and styles of development in order to get this working, and that takes time. Sure, looking at an example like this is easy. But it’s a simple example and a simple implementation. When you get down to actually trying to write this style of code for yourself, in your project, with your 20 variations on the flow through the application, it will get more complicated, quickly. And there’s no simple answer for this complication in design, other than to say that you need to learn to break down the larger workflow in to smaller pieces that can look as simple as this one.

But It’s Worth It

In the end, in spite of potential drawbacks and learning curves, making an effort to explicitly model your workflow in your application is important. And it really doesn’t matter what language your writing your code in. I’ve shown these examples in JavaScript and Backbone because that’s what I’m using on a daily basis at this point. But I’ve been applying these same rules to C#/.NET, Ruby and other languages for years. The principles are the same, it’s just the implementation specifics that change.

And I need your help to answer these questions and improve the documentation and wiki.

The Marionette Wiki

In addition to the technical documentation in the project’s readme, I’ve started up the wiki on the github project page. I’ve begun with two simple pages: an overview on the different view types, and page to let Marionette users show of their projects and websites that are using it.

Help me and the rest of the community of Marionette users improve the documentation for this project by providing examples, best practices, answers to frequently asked questions, and more. 

Head over to the wiki and start helping! 

https://github.com/derickbailey/backbone.marionette/wiki

Topics To Cover

Example topics that should be covered in the wiki:

• Using Marionette with RequireJS
• Using JST templates with Marionette views
• Using Handlebars templates with Marionette views
• Using jQuery plugins and visual controls with Marionette
• and much, much more

I realize that some of these are items that I’ve blogged about here. One of my hopes and goals is to have many of the Marionette blog posts from this blog, copied in to the Wiki in a manner that makes sense for the wiki. I will try to do some of this myself, but it would also be wonderfully helpful if other members of the Marionette community could assist in doing this.

I Need Your Help. Yes. YOU.

I know I’m asking a lot – but I believe the community of Marionette users is up to it. It only takes a few minutes of time to improve one page or create a new one with some very basic information. Then another person can come along and make another improvement. Then another, and another. 

Lastly: don’t think “oh, someone else will do it”. They won’t. Believe me. The distribution of responsibility is the single largest reason that people won’t take responsibility or put effort in to something. Everyone assumes that someone else will do it, and no one actually does it.

Non-CRUD-y Apps

Now I don’t think that there’s anything wrong with Backbone’s “save”, “fetch” and “destroy” methods. They’re quite handy, and very well done. The deciding factor in using them is whether or not my application is CRUD-y or not. That is to say, many of my recent apps are taking more of a command approach to user interaction and data updates. Instead of just having simple Create, Read, Update and Delete forms on my apps, I tend to have smaller and more focused commands that are called.

For example, signing a terms of service agreement is a command to sign the agreement, not just a “create” on a resource. Sure, the implementation of that may be a “POST” on a resource location. But that doesn’t mean I need a full Backbone model, or need to think about the signature as a RESTful resource from my JavaScript code.

Executing Commands vs Making AJAX Calls

As a result of all this, I end up using $.ajax a lot… and it’s getting really ugly and obnoxious seeing this all over my code:

var signForm = $.ajax({
  type: "POST",
  url: "/some/form",
  dataType: "JSON",
  data: myData
});

signForm.done(function(response){
  // handle success here
});

signForm.fail(function(response){
  // handle failure here
});

Not only is this ugly when you repeat the $.ajax calls all over the code, but it doesn’t really give the semantic benefit of knowing what the code is really doing. I’m not just making a call across an AJAX connection. I’m trying to execute a command – I’m trying to do something important, and I want my code to reflect that.

So I wrapped up my $.ajax calls in a thin “command” wrapper for my current client app (built with Backbone of course), and ended up with this instead:

// Register a command to use
// -------------------------

Backbone.AjaxCommands.register("signForm", {
  url: "/some/form",
  type: "POST"
});


// somewhere else in the application, use the command
// --------------------------------------------------

var signForm = Backbone.AjaxCommands.get("signForm");

signForm.on("success", function(response){
  // handle success here
});

signForm.on("error", function(response){
  // handle failure here
});

// execute the command and send this data with it
signForm.execute(myData);

Looking at this in comparison to the original $.ajax calls, there are a few less lines of code. Since I have a thin wrapper around the ajax calls and setup, I can make a few assumptions about the calls and provide a little bit of default configuration. 

I can also move the registration of commands somewhere other than the execution of the commands, which is a huge win for readability and organization of the code when it comes time to execute a command.

Of course the handling of events for success, error and completed doesn’t give me any advantage over $.ajax and deferred objects. But the big benefit here and why I don’t mind the thin wraper around the done/fail/always deferred methods, is the semantic value of executing a named command vs configuring an ajax call.

And before you go in to a “semantics are not important” lapse of sanity, just think a little about this line that I once heard from Sharon Cichelli:

“Semantics will continue to be important until we learn to communicate in something other than language.“

Implementing The Command Structure

This implementation relies on Backbone, Underscore and jQuery, so it’s really only useful in Backbone applications at this point. It’s also important to note that this code is not unit tested at all. I’m using it in my current client application and it is functional for me, but I don’t recommend taking this code as a great implementation, yet. I have plans on turning this into a real plugin, with full testing around it. But like most of my plugins and libraries, it started out as a quick hack in order to get something cleaned up in one of my applications.

// Backbone.AjaxCommands
// ---------------------

Backbone.AjaxCommands = (function (Backbone, $, _) {
    var Commands = {};

    // Private data
    // ------------

    var commandList = {};

    // Public API
    // ----------

    Commands.register = function (commandName, options) {
        commandList[commandName] = options;
    }

    Commands.get = function (commandName) {
        var options = commandList[commandName];
        options = options || {};
        options = _.clone(options);
        var command = new Commands.Command(commandName, options);
        return command;
    };

    // Command Type
    // -------------------

    Commands.Command = function (name, options) {
        this.name = name;
        this.options = options
    };

    _.extend(Commands.Command.prototype, Backbone.Events, {
        execute: function (data) {
            var that = this;

            var config = this.getAjaxConfig(this.options, data);

            this.trigger("before:execute");

            var request = $.ajax(config);
            request.done(function (response) {
                that.trigger("success", response);
            });

            request.fail(function (response) {
                that.trigger("error", response);
            });

            request.always(function (response) {
                that.trigger("complete", response);
            });
        },

        getAjaxConfig: function (options, data) {
            var url = this.getUrl(options, data);

            var ajaxConfig = {
                type: "GET",
                dataType: "JSON",
                url: url
            };

            _.extend(ajaxConfig, options);
            ajaxConfig.data = data;

            return ajaxConfig;
        },

        getUrl: function (options, data) {
            return options.url;
        }
    });

    return Commands;
})(Backbone, $, _);

There ar ea couple of things you’ll want to note in this code:

The call to “register” a command stores the configuration that you provide. The call to “get” a command creates a new command instance and hands it back to you. This is done so that you can have single-use command objects and not have to worry about unbinding events from the command after it has completed. If I held on to a single command instance and just handed that back to you, you would be responsible for unbinding the event handlers after executing the command. 

The wrapper events for “success”, “error”, and “complete” also don’t guarantee to fire if you subscribe to them after the command has been executed. So, it’s important to set up your event handlers before calling .execute on the command object.

I’ve also extracted the “getUrl” method specifically because I need to provide a very custom implementation of this method in my client’s application. I have another plugin that I’m looking at writing, which handles storage and retrieval of URLs in my Backbone apps, including :token replacement in the urls … but that’s another blog post and another plugin to write.

A Timed Polling Mechanism

One of the more interesting things I’m doing with this is using it as a timed polling mechanism. I set up a command and then I wrap the commands “execute” function in another method that I can call from a setTimeout. When the command executes, I check the response. If I find the data I need, I move on. If I don’t find the data I need, I call the wrapper function again, inside of a setTimeout.

var myCommand = Backbone.AjaxCommands.get("myCommand");

var executeCommand = function(){
  myCommand.execute(someData);
};

myCommand.on("success", function(response){
  if (response.someValueImChecking){
    // move on to the next thing, here
  } else {
    // poll again, 1 second from now
    setTimeout(executeCommand, 1000);
  }
});

There’s lot of fun little tricks you can do with a simple object wrapper like this, that would be a little more cumbersome and awkward when directly using $.ajax. 

Fortunately, it’s easy to build helper methods for Underscore templates (and they end up looking a lot like Rails view helpers).

Logic In Templates: A Bad Idea

On a client project recently, I had a JavaScript object that needed to be bound to my template. The object looked somewhat like this:

var data = {
  type: "something",
  name: "whatever",
  addresses: [
    {
      type: "read_address",
      address: "1/2/3",
      value: "10"
    },
    {
      type: "write_address",
      address: "1/2/4"
    }
  ]
}

I needed to take all of the “addresses” and find each specific address within the array, by name, so that I could get the right information in place at the right time in my template.

The first pass of code that I wrote to do this, looked like this:

<script id="my-template" type="text/template">
  <p>type: <%= type %></p>
  <p>name: <%= name %></p>
  <p>read address: <%= _.find(this.addresses, function(addr){ return addr.type == "read_address" }).address %> </p>
  <p>read address value: <%= _.find(this.addresses, function(addr){ return addr.type == "read_address" }).value %> </p>
  <p>write address: <%= _.find(this.addresses, function(addr){ return addr.type == "write_address" }).address %> </p>
</script>

And this worked, but it’s a bad idea. I have a lot of duplication in this template and I have a lot of logic and processing of data in the template, too. This is going to make for a very painful setup when it comes to maintenance – especially if / when I have to change how the address is looked up.

View Helper Methods: A Better Idea

In asking around on twitter for some suggestions on how to clean this up, I received several responses. Out of everything that everyone said, though, I liked the response I got from DaveTheNinja because of it’s simplicity.

The basic idea is to recognize that the data I send to my template is a JavaScript object. Since this is an object, it can have methods. If I can have methods on my object, why not put methods on it as view helper methods?

var viewHelpers = {
  getAddress: function(type){
    var address = _.find(this.addresses, function(addr) { 
      return addr.type == type 
    });
    return address;
  }
}


_.extend(data, viewHelpers);

_.template(myTemplate, data);

The helper method – “getAddress” – is pretty much the same code. But now it’s consolidated in to a single location and I’m able to give better formatting for it which makes it easier to read and understand.

You can also see that I’ve kept the data separate from the objects until just before rendering the template. I’m using Underscore’s “extend” method to copy all of the methods from my “viewHelpers” object on to my data object.

Then when I pass the data object to my template, I can call my “getAddress” method like this:

<script id="my-template" type="text/template">
  <p>type: <%= type %></p>
  <p>name: <%= name %></p>
  <p>read address: <%= getAddress("read_address").address %> </p>
  <p>read address value: <%= getAddress("read_address").value %> </p>
  <p>write address: <%= getAddress("write_address").address %> </p>
</script>

And we’re done! I now have view helper methods that I can call from within my templates.

Using This With Backbone

I use this technique with Backbone a lot. The code that I showed above is really no different than what I do with my Backbone views, either. When you get to the point where you need to render your template, just extend the view helper methods on to your data before doing the actual rendering:

Backbone.View.extend({
  template: "#my-template",

  render: function(){

    var data = this.model.toJSON();
    _.extend(data, viewHelpers);

    var html = _.template($(this.template), data);
    this.$el.html(html);

  }
});

Using This With Backbone.Marionette

I’ve added this functionality in to Backbone.Marionette as well. ItemView, CompositeView and Layout will all look for a `templateHelpers` attribute on a view definition. If it finds it, it will mix that object in to the data that is used to render the template: 

Backbone.Marionette.ItemView.extend({

  template: "#my-template",
  templateHelpers: viewHelpers

});

You can specify a reference to the viewHelpers object as shown in this example, provide an object literal as the templateHelpers directly, or specify a function that returns an object with the helper methods that you want. For more information see the documentation for Marionette.

Other Template Engines

This basic technique will probably work with other template engines, too. Some engines like Handlebars, though, have this idea baked in to them directly. But if you’re using Underscore’s templates, then this is a good way to keep your templates clean while still providing the logic you need.

If I run “npm install express” from within a folder, the “express” package will be installed in to my ./node_modules folder.

But I can’t say “express foo” on the command line at this point, to run express. And I can’t say “npm express foo” or “npm exec express foo” or anything like that. This ability is sadly missing from NPM. There are a few ways to get around this, though.

Global Modules

When you install a Node module with the `-g` option, it installs in to the global module list. Global modules can have their bin files run from the command line just like any other command. So if you install the “express” module, for example, with the global flag then you’ll be able to say “express foo” from the command line and watch it build a fresh new project for you in the “foo” folder.

This is nice for packages that you want to have available for any application you’re building. I use global packages a lot because some of the tools that you can find in node packages are quite useful, even outside the context of a node project. But not every package should be installed in the global package repository for your computer.

Run Bin From Relative Path

You can also run bin files from node modules by using the relative path of ./node_modules/.bin/ to find the command.

This is a bit tedious, though it is functional. I’ve build a few simple command / shell scripts to execute some of my installed modules this way, for some of my projects. That makes it a bit easier overall, but you have to set up a shell script for each package you want.

Run Bin From Generic Shell Script

Since all of the bin files for all of the node packages are installed in to ./node_modules/.bin/ for a given project, why not build a generic “npm_exec” shell script and just forward all the parameters?

Easy enough:

./node_modules/.bin/$@

Just “chmod +x npm_exec” to make this file executable, and away we go.

Now I can run any arbitrary package binary I want. I could even put this little shell script in my /usr/local/bin folder and it would be available for all of my node projects, anywhere on my box.

This is a nice little solution, even if it’s a work around for something that should be built in to npm.

NPM Scripts In package.json

This last option is one that I’m using more and more often for project specific, recurring needs.

When you create an express app, it builds a package.json file for you. One of the pieces that it sticks in there is the “scripts” setting which contains a “start” setting, by default.

{
  "name": "application-name",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "start": "start app"
  },
  "dependencies": {
    "express": "3.0.0alpha1",
    "jade": "*"
  }
}

It turns out you can use these “scripts” from the npm command line. When you call “npm start”, npm will execute the “scripts”/”start” configuration for you. By default, this is just a call to “node app” which runs the app.js file in node and gets your express.js app up and running.

You can do more with “scripts”, too. You can add your own named script, in fact.

{
  ...

  "scripts": {
    "start": "node app",
    "foo": "node -e 'console.log(1+2)'"
  }

  ...
}

But you can’t just “npm foo”. The “start” script is recognized by npm explicitly. For other non-standard script names, you have to use the “run-script” command from node: npm run-script foo

The other thing that this does for us, is give us direct access to all of the bin files that our node packages have installed. So within a “script” configuration, we can call any arbitrary package’s bin file.

For example, if I want to use the node-supervisor package to restart my app whenever any files change, I can set up my package.json file to look like this:

{
  "name": "application-name",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "start": "supervisor app"
  },
  "dependencies": {
    "express": "3.0.0alpha1",
    "jade": "*"
  },
  "devDependencies": {
    "supervisor": "*"
  }
}

This will install the “supervisor” package for development only, and set up the “start” script to run “supervisor app”. Now from the command line, I can’t run “supervisor app” directly:

But I can run “node start” and node will pick up the ./node_modules/.bin/ folder for me, allowing supervisor to be executed:

This works well for recurring / repetitive tasks within a project. But if you want ad-hoc package commands, you’re going to be in for a little more work and will likely have to fall back to one of the other solutions I’ve mentioned.

Other Options?

I really do miss the “bundle exec” feature of bundler. I honestly don’t know why npm doesn’t have an equivalent built in to it. Maybe it just needs someone to come along and contribute this feature. Maybe this feature was rejected. I don’t know. I haven’t looked in to it. But I wanted to get something in place now, so that I don’t have to install all of my project specific packages in the global package list.

There might be better option than the ones I’ve listed, as well. So, what am I missing? Is there something built in to npm to make this easier? Are there other ways that you’ve worked around this? Or am I going to stick with my “npm_exec” script and using npm “scripts” in my package.json fil?

What tool do you use to refresh your browser when you change a file in your editor?

It’s LiveReload, and I’ve put together a 10 minute introduction that shows how to get up and running with the GUI application and the Guard plugin, how to use it to compile your assets such as SASS or CoffeeScript, and more.

Personally, I can’t live without this tool anymore. It takes the “refresh” button out of my development effort and greatly simplifies my workflow.

Be sure to checkout my other screencasts (paid and free) at WatchMeCode.net as well.

A Web Socket Library

Now you could write your own web sockets implementation. But I don’t recommend this. It’s notoriously difficult to get it to work across all of the browsers that you’ll have to support and frankly, not worth your time. Instead I’d recommend using an existing socket library. I’ve used these and can highly recommend all of them:

• Socket.IO: The defacto standard for web sockets libraries. It primarily runs on NodeJS, but there are back-end servers for several other languages available as well. It falls back to long-polling, AJAX, and several other implementations that work in nearly every browser.
• SignalR: A long-polling, web sockets, AJAX adaptive system for .NET. It’s Socket.IO for .NET.
• Pusher: A third-party web sockets server. This is great for hosted sites (like Heroku) and for high scalability, fast. I learned how to use web sockets and converted a very chatty app from AJAX calls to PusherApp in less than an hour, a few years ago. There are libraries for PusherApp in many different development languages, like Ruby, .NET, Python, etc. I’ve only used the Ruby library, but it was dirt simple. They also have an article on working with Backbone and Pusher.

And yes, I realize that there are more libraries than just these. I’ve only used these, so they are the ones I’m mentioning. And I love all three of these web socket libraries. If I was forced to pick a favorite, it would be Socket.IO but only because I love working with NodeJS. But I do have an affinity for Pusher, since it’s the place that got me started with Websockets.

All three of these libraries are easy to use, and can easily be adapted to this example, though. Don’t feel like you’re going to make a wrong choice either. After all, the purpose of this article is to show you how the choice you’ve made doesn’t matter that much.

Decoupling Web Sockets

When I build apps with web sockets for communication, I don’t want my application to actually know anything about the sockets. I don’t want to mix that responsibility all throughout the code, for a number of reasons. If my need for sockets changes, for example, having many places to update the use of them would become a pain. If I want to get rid of sockets entirely or use another form of communication in addition to web sockets, having to go and add a bunch of extra code in all of the places that need the new communication would be awful. There’s also a high likelihood of code duplication, hidden problems and workflow, and hard to test code when we couple our web sockets implementation to our application code.

The simple solution that I’ve found for this is to abstract the web sockets away from our application. There are several ways to do this, one of which is to replace the Backbone.sync method in a Backbone app with something like Backbone.IOBind. This plugin replaces the sync method with a version that communicates over web sockets. That means your fetch, save and destroy methods would all move over web sockets instead of AJAX calls. If you’re using Socket.IO and you want to have your data access methods working this way, I recommend checking out Backbone.IOBind.

Another way to do this, though, is to move the web sockets code away from the application entirely. We can easily set up an adapter objects that translates between our web sockets implementation and our actual application.

A SocketAdapter

There are two basic things that you’ll need to build a socket adapter in the manner that I like. a web sockets setup and an event aggregator. Pick a web sockets library – any of them will do. For this example, I’ll be using Socket.IO. As for an event aggregator, I’ve got my default setup with Backbone.Marionette which provides one for us. Or you can pick any of a number of other pub/sub libraries for JavaScript.

Here’s the trick to decoupling the application code from the web sockets library: all of the events that the web socket publishes will be forwarded to the event aggregator, and your application will only pay attention to the event aggregator. For example:

  HIT = new Backbone.Marionette.Application();
  // ... other settings here




  // Socket.io Adapter
  // -----------------
  
  // This adapter forwards all socket.io events
  // to the application's event aggregator. The
  // intention of this is to decouple the specific
  // websockets implementation from the application's
  // use of it.

  var socket;

  var initialize = function() {
    socket = io.connect(HIT.socketUrl);

    socket.on("connect", function() {
      SocketAdapter.connected = true;
      HIT.vent.trigger("socket:connected");
    });

    socket.on("someData", function(data){
      HIT.vent.trigger("someData", data);
    });

    socket.on("disconnect", function() {
      SocketAdapter.connected = false;
      HIT.vent.trigger("socket:disconnected");
    });

    socket.on("error", function(err){
      console.log("ERROR: ", err);
    });

  };

  HIT.addInitializer(initialize);


  // Handle the event, start the app and the socket adapter

  HIT.vent.on("someData", function(data){
    alert("some data came through!");
  });

  HIT.start();

In this case we’re listening for an event called “someData” on the socket library. When that event fires, we’re just forwarding the event in to our application’s event aggregator. Our application listens for the necessary events from it’s event aggregator, and does it’s thing.

From there, you just extend the adapter to listen to your specific events, and continue to forward them on. In some cases, you can even create very generic socket event handlers so that you don’t have to constantly add new ones. In other cases, you might need to add a very specific event handler and have it do some manipulation of the data that it receives before forwarding it on to the application. No matter the case, though, you now have a single place in your application where this needs to happen.

Yes, it’s really that simple.

But, Why?

Decoupling and all that, of course. But really, it just makes our lives as developers easier. Having the web sockets and application code decoupled like this does add a little bit of overhead in both the run time execution of the code, and in the mental effort to keep track of all the moving parts. But the slicing of the individual parts down in to single responsibilities makes it easier to understand each part, and in some cases can make it easier to see the machine as a whole.

We’ve also made the choice of a web sockets library somewhat irrelevant. Did you pick Socket.IO and realize that you now need something hosted so that you can scale faster? No problem – just replace the socket adapter with an implementation that uses Pusher. Did you choose Pusher and now realize that you don’t want to pay for a hosted solution in your .NET system? No problem, just replace the Pusher implementation with SignalR.

When we’re testing our applications, we don’t have to worry about mocking or stubbing the web sockets, either. Rather than going through the pain of dealing with the web sockets API that we’ve chosen, we can simply fire off events from our application’s event aggregator and verify the results of firing those events. Removing the web sockets library from our tests will make the tests easier to work with, cleaner to read and write, and probably run a little faster too.

On that note, we can also simulate web sockets events in to our application. In a recent client project, for example, I had to simulate a list of devices with addresses receiving events from Socket.IO in my development environment. This project involved some hardware integration, and the only place where the hardware was available was a server in Germany. I didn’t have access to it here in Texas, except by deploying the app and running it there. So in my development environment, I used a setInterval to publish an event through my event aggregator every 1 second. The events I published contained valid but slightly random data to simulate what I would be receiving from the actual web sockets server. With this in place, I was able to write my app and deploy it to the real server with a fair amount of confidence. It worked nearly every time (except that time where we changed how the web sockets data was being pre-processed by our adapter).

Only One Of Many Options

There are likely a thousand or more ways that you can integrate a web sockets system in to your application. I’ve shown you how to do one of them and linked to another (Backbone.IOBind). But don’t think that you have to do it the way that I like to do it. This is my preference based on the style of event-driven architecture that I like to write. The main point that you should take away from this article is not that you can build an event aggregator adapter for web sockets, but that you should decouple your web sockets from your application in a manner that makes it easier to maintain and change both your application and the web sockets implementation, independently of each other.

The Problem: Moving DOM Elements

The core of the problem that people run in to when using a modal dialog is that the modal plugin removes the DOM element that wraps the modal, from the DOM. It usually gets added to some special holding location where the modal plugin can guarantee that the element won’t be visible until the modal dialog is opened. I’m over-generalizing this a bit, but many of the modal dialogs work this way or in a similar manner.

The problem that this usually causes is that a Backbone view will lose it’s event handling when the DOM element gets moved around by the modal dialog. When the modal dialog removes the view’s `el` from the DOM, the `events` configuration is lost because the DOM element has been moved or removed from the DOM and jQuery had to let go of the events. When the `el` is re-added to the DOM for displaying it as a modal, then, the `events` are not re-attached.

This is usually caused by a developer using the Backbone view itself as the modal dialog – which is not what you want to do.

The Solution: Don’t Modal A Backbone View

No, really. That’s the solution.

I’m not saying you can’t use a Backbone view in a modal. I’m saying you shouldn’t try to modal the view itself. Instead, you should create a simple wrapper div for the modal plugin to use and then populate the contents of that div with the view’s `el`.

Let’s see an example of a Twitter Bootstrap modal dialog, displaying a Backbone view. First, the HTML and Underscore template:

<script id="modal-view-template" type="text/html">
  <div class="modal-header">
    <h2>This is a modal!</h2>
  </div>
  <div class="modal-body">
    <p>With some content in it!</p>
  </div>
  <div class="modal-footer">
    <button class="btn">cancel</button>
    <button class="btn-default">Ok</button>
  </div>
</script>

<div id="modal"></div>

Note that I have a “<div id=’modal’></div>” in there. This is explicitly for the Twitter Bootstrap modal dialog to use. This div is the modal. There’s no content in it, though. I will supply the content for the modal through a Backbone view, which looks like this:

var view = new MyView();
view.render();

var $modalEl = $("#modal");

$modalEl.html(view.el);
$modalEl.modal();

How easy is that? I’m just rendering a view like I always do, stuffing the view’s `el` in to the “#modal” div, and then calling `.modal` on the jQuery selector object. And that’s it. My modal is done and my view’s `events` will still work.

Managing A Modal With Backbone.Marionette

Yes, it always comes back to my Marionette plugin, right? :)

In this case, I want to manage my modal dialogs as I do any other area of my screen. I want a single object that keeps track of what view is currently displayed within the modal, handles rendering it that view for me, calls the `.modal` dialog method for me, and correctly closes the modal when the “cancel” or “close” button on my view is clicked.

This largely sounds like a Region object in Backbone.Marionette: a way to manage the contents of a particular DOM element, by rendering and displaying a Backbone View in to that DOM element. Only in this case, it’s a very specialized Region that needs to manipulate the DOM element as a Twitter Bootstrap modal.

To do this, I’m going to take advantage of Marionette’s “Region” and extend it with the behavior that I need for managing the modal:

  var ModalRegion = Backbone.Marionette.Region.extend({
    el: "#modal",

    constructor: function(){
      _.bindAll(this);
      Backbone.Marionette.Region.prototype.constructor.apply(this, arguments);
      this.on("view:show", this.showModal, this);
    },

    getEl: function(selector){
      var $el = $(selector);
      $el.on("hidden", this.close);
      return $el;
    },

    showModal: function(view){
      view.on("close", this.hideModal, this);
      this.$el.modal('show');
    },

    hideModal: function(){
      this.$el.modal('hide');
    }
  });

This is honestly more code than I wanted to write. There’s a few things that I need to clean up and add in my Region object to make this a little more elegant. But, it works! And that’s the important part.

The `constructor` function listens to the region’s “view”show” event, which is fired when a view’s contents are populated in to the `el` of the Region. In the event handler for this, I’m calling the `modal` plugin method on the `el` of the region.

I’m also setting up a “close” event handler on the view itself at this point. That way when I close the view from within my view’s code (a cancel button, or otherwise), the modal will shutdown. The handler for this simply hides the modal using the modal’s ‘hide’ option.

As I said before, I want to reduce the amount of code that is required to make this happen. But for now, this is a functional modal dialog region. I’m using it in my application, like this:

var App = new Backbone.Marionette.Application();

App.addRegions({
  main: "#main-content",
  modal: ModalRegion
});

// somewhere else in the app
var view = new MyView();
App.modal.show(view);

Note that I’m registering my ModalRegion object in my Marionette.Application with my other regions. Instead of passing in a DOM selector, though, I passing in the ModalRegion type.

More Than Just Twitter Bootstrap

The examples I’ve shown here cover the use of Twitter Bootstrap, but are applicable to more than that. You should be able to easily modify the ModalRegion object to work with any JavaScript modal dialog. I’ve used the same basic solution for jQuery UI modals, and I expect that KendoUI and other modals would work in a similar manner as well (though I may be wrong about that).

The best part about this is that you’ll only need to modify the region object. You shouldn’t have to worry about changing your entire application to use a different modal system, because we’ve encapsulated the modal system in to our ModalRegion object, and our application makes use of that to display the modal dialog with any Backbone.View that we want.