Introduction to

A Superheroic MVW Framework

A Conversation

First version

I'll admit, it was a bit of a mess to begin with. I tend to design things from the graphics down, and so I was busy thinking about whether we could use this or that HTML5 feature, and not as much time thinking about how I was to structure the data that was driving the app. Since a big part of the app was letting people interact and change the onscreen data, what I ended up doing was storing a lot of data in the DOM, and then grabbing all that data back out when it was time to save it back to the server. This brought several issues. The app was pretty fragile. Making changes to the way the interaction worked, if I wanted to say, let people add extra pages or remove pages from a conversation, needed a lot of very careful manipulation of the order of divs in the DOM. Another big pain in the arse was when I had massaged the data from the server in order for it to be presented in an intuitive way onscreen. When saving, I had to reconstruct the data to send it back to the server. Again, fragile. So naturally enough, the things we wanted the app to do increased, and it was clear that it would only end up becoming unmanageable unless I did something to separate all this data from the DOM and keep it in one place, ideally in a form that mirrored the way the server stored it.

Frameworks

Backbone
Knockout
Ember
... MVWTF

So I started looking at javascript frameworks. The first I looked into was Backbone.js. I'd heard a lot about backbone and it has some really interesting guides online. I was pretty excited about it, it offers a light way to separate out the models and views, and even set up binding between the two so that data changing in the model could be passed on to the views. I tried a few tutorials, tried even setting up a little heroku project using backbone as the approach to handling some onscreen data, and, well, it was OK I guess, but I struggled to really understand the workflow. The code seemed to make sense, but it just didn't quite gel in my mind enough to start using it. I think it was its agnostic, "do what you like" approach that made it more difficult to get into using it. I was too busy second guessing myself, not quite confident enough to make good use of it. Still, the problem remained, we had a lovely looking app that did it's job pretty well, but was rapidly becoming a maintenance nightmare. One evening while flicking through pages for Knockout.JS, Ember,js and the likes, I came across a Google project called AngularJS.

A grand aim

HTML is static

Opinionated

Two-way binding

Hello world

Hello {{world}}!

Code:

<ul>
  <li><input placeholder="Give me a name!" ng-model="world" /></li>
</ul>
<h3>Hello {{world}}!</h3>

Here's a little example of what I mean. Angular allows you to declare a model, in this case, this input text box is a model, and then using curly braces you can fire out the data into the view. When I type in this input box, the "Hello..." message is updated immediately. I haven't had to write a single line of javascript to get this to work, it's just done by telling Angular: here's the model, and here's where it goes. Anytime the model changes, you see it right there in the view. It's as simple as telling AngularJS that the page is an Angular app. I just added the attribute "ng-app" to the body tag of the page, and from then on, any curly braces in the html, or any of the Angular-specific attributes, are picked up by Angular and it does it's thing. So we have a hello world example, where we specify an input and specify where it is output, but what if you want to manage more data than that? When approaching the Converser app, I had these conversations with multiple pages, each of which had their own sets of data in the form of text, images, etc. All this data had to be bound to the views properly, and as people are going to want to edit the content and save it back to the system, a way to store all this data in the front end was needed. I needed to look into how Angular handles the model.

Moar data

{{item}}

HTML:

<ul>
  <li ng-repeat="item in model.listItems">{{item}}</li>
</ul>

JS:

$scope.model = {
  listItems: ['Item one',
              'Item two',
              'Banana']
}

While getting started with AngularJS, the first thing I did was set up a model for the data I was to manage. This was pretty straightforward. The data for the model is stored in a controller function, and the controller is mapped to an area of the view so that it knows where the data will be used and where to look for changes. Here's a way to show how the model is connected to the view. I've got a list here. The content of the list is populated by a little bit of Angular inline logic called "ng-repeat". Here we have the function in the javascript, the controller, which contains the data items. On the right we have the HTML that displays them. The HTML has in it's containing div this "ng-controller" attribute. This is how it knows what data to act on. If this model data on the left changes, the change is reflected immediately in the data of the displayed list. This was immediately very useful for what displaying multiple pages in my editor app. The pages were stored in a model hash, and rather than adding divs to the DOM, removing them and all that messy stuff, all I had to do was add an entry to the model and the "ng-repeat" was given the extra item to display. All very elegant and fast. So this is all very well when the data in your model is straightforward. But if you want to do more than just pass data back and forth? What if you wanted to manipulate the data in some way so that it looked different that how it is eventually stored by the server, but at the same time maintain this binding? This is where directives come in.

Directives

If binding is the main thing AngularJS is built around, directives are how it wraps the data in whatever way you want while still maintaining this binding. Directives are discreet modules that describe specific actions you want the browser to do. You can use directives to create your own HTML tags, specify how they handle the data inside the tag, both on the way from the model to the view and back again. I'm a bit of a slow learner. When I started using AngularJS, I had skimmed across the notion of directives and frankly, I was keen to do what I could to avoid them as they looked a bit scary. And they kind of are. But they're extremely handy, and what's great is that they can be built once, and then once you have the directive working, then they become tools that your web app can use again and again.

Anatomy of a directive

myModule.directive('directiveName', function factory(injectables) {
  var directiveDefinitionObject = {
    priority: 0,
    template: '',
    templateUrl: 'directive.html',
    replace: false,
    transclude: false,
    restrict: 'A',
    scope: false,
    compile: function compile(tElement, tAttrs, transclude) {
      return {
        pre: function preLink(scope, iElement, iAttrs, controller) { ... },
        post: function postLink(scope, iElement, iAttrs, controller) { ... }
      }
    },
    link: function postLink(scope, iElement, iAttrs) { ... }
  };
  return directiveDefinitionObject;
});

Markdown example

Actually, as it turns out, directives can be quite simple. They have loads of options and I've not plumbed the depths of what they can do, but here's an illustrative example that shows how a directive canhelp manipulate some data. We've got two text boxes here. The left is a textarea, the right is a preview. I can type a load of markdown here on the left, and immediately on the right, we get HTML. I'm using the javascript tool Showdown.js to handle the actual translation of the markdown, but the process of passing this markdown through the processor function and then putting it across here, is handled by a directive. First through, here's the HTML I used in this example:

Markdown Example HTML

<textarea markdown></textarea>

<div class="preview"></div>

Markdown Example JS

angular.module('presentationApp.directives', []).
directive('markdown', function() {
  var converter = new Showdown.converter();
  return {
    restrict: 'A',
    link: function(scope, element, attrs) {
  	  element.bind('blur keyup change', function() {
  	    var htmlText = converter.makeHtml(element.val());
  	    $('.preview').html(htmlText);
  	  });
  	}
  }
});

When you're initialising an Angular project, you bolt on any directives at loading time. What Angular does is it runs through the HTML looking for ways to connect these directives, and then applies their logic. What we have here is essentially a function called directive that is given two values, "markdown" which is the name of the function, and a function that listens for changes in the textarea and shoves them through the Showdown processor, and finally pastes the output into the preview div. This means you can create your own tools for handling quite complex data manipulation, and compartmentalise it away from the view, keeping what's in the view quite streamlined. The documentation on the Angular site has lots of examples around directives. You can bring in custom templates, even inject unit tests using the example code the Angular guys have set up, so while they are pretty complex, they're powerful.

Directives

Custom HTML tags and attributes
Can apply templates
Abstract complex logic from views
Nestable

Techniques learned

Models for data
Binding to views
Manipulating with directives

Real world example

Did it help?

Data management
Code structure

In summary

Good stuff

Opinionated
Extendable
Magical binding
Growing community
It does a lot

Which brings me to some of the benefits of AngularJS. It's opinionated, do it this way or else approach, is for me a benefit as it has resulted in a project I'd be a little more confident passing over to someone else, and they'd be less likely to drop dead before they reach the end of the file. It's been a bit of a learning curve for me understanding scope, understanding where the data *is* at any point, but what's been great is that since using it, I've found adding on extra functionality a much less daunting task. The data is always in one place, so I know that if I change the view, add extra directives for handling different types of data, it doesn't change the underlying data structure. That makes me feel a lot more relaxed about the code and more productive in the long run. The way AngularJS does it's data binding is great. I don't need to specifically set up listening events for each piece of data in the app, I know that if I ensure that the views are using Angular's functions for displaying the data, it'll take care of maintaining that binding. I've only really dipped my toes into what the framework can do, and it's actively developed so I'm interested in seeing where it goes. Since it's actively developed, I'm interested in seeing where it goes.

Not so good

Opinionated
Breaking changes
Not for every app

There were moments when I was banging my head against the wall so to speak. Especially around the idea of directives. This could have been my own fault really as I'm not great at reading documentation, I tend to poke first, swear second then turn to the guides. However one thing to look out for, this had me confused for a while, was a few breaking changes between version 0.9 and 1.0.1. The main change was within directives, specifically around declaring the scope of the data being worked on. I'd recommend checking changelogs around the 1.0 mark as the videos tend to reference the older method, even though they're just a few months old. But yes, there is a little bit of learning around AngularJS. I do like it, but I'll admit I'm perhaps more open to giving Backbone another go as I've learned quite a bit in the past month about how MVWTF controllers work. The AngularJS website itself notes that it's not a solution for every problem. It's great for most CRUD style apps, but maybe not so great for the likes of say, an IDE, which would probably need finer grain control of the DOM. Having said that, I've only scratched the surface so I could well be wrong about that.

Resources

Thanks

Donovan Hutchinson
Converser.io
Blog: http://hop.ie