AngularJs modules to the rescue

Building large scale JavaScript application is a tough problem. The language nature is malleable and it does not have proper modules mechanism built in. Some argue that you can’t really built and maintain big applications built with JavaScript.  Others say that the key in succeeding is to never built big applications but to approach things in a more clever way – by applying divide and conquer rule.

Dividing code base

Due to lack of modules mechanism in ECMAScript 5th edition, which is the version most commonly available in browsers, there were couple of implementations created. RequireJs and AMD are just 2 most popular ones. Angular team decided to provide it’s own implementation of modules and left the asynchronous loading of them to existing tools. I suspect that it was because they didn’t want to create a dependency on 3rd party library and because of their use of dependency injection. The framework relies on modules heavily making it possible to use just the parts that you actually need saving precious network and loading time. Here is how to define a module:

var myApp = angular.module('myApp', ['ngResource']);

myApp.factory('itemsStorage', function ($resource) { 
  var itemsStorage = ...;
  // items storage implementation
  return itemsStorage;
});

We’ve declared a new module called myApp and stated that it depends on another module called ngResource. In line 3 we are declaring a factory for itemsStorage that requires $resource service. Angular will automatically resolve $resource service and inject it as a value of parameter. As you may suspect under the hood the dependency injection mechanism inspects parameter names of our function and thus it is able to know how to satisfy them with proper values. Be careful when using JavaScript minimizing tools because most of them will by default shorten parameter names and that will break the DI. The only work around for it is to disable an option responsible for parameters in minimizer. Most of the times I find it useful to split one module definition across couple of files. It is a supported scenario but there are some quirks to it.

var myApp = angular.module('myApp');
 
myApp.directive('timeAgo', function(){
  return function($scope, $element, $attrs){
    // timeAgo directive link implmentation
  };
});

The first line says that we would like to retrieve myApp module so that we can extend or use it. This API may be confusing, it was for me, as it may look like we’re actually declaring a module that has no dependencies. The distinction between extending and declaring a module has an important ramification. You’re now responsible of loading file with module declaration before files that extend module functionality. In order to declare module with no dependencies you have to pass an empty array as a second argument:

var secondModule = angular.module('secondModule', []);

A praise of dependency injection

Dependency injection is a very useful concept especially in statically typed languages as C# or Java. It really helps you decouple your code as your classes no longer require to know about the implementation details of their dependencies. There are several ways to implement this pattern however must commonly used is a constructor injection. A lot of IoC containers exists both in .NET and Java world: Castle.Windsor, StructureMap, Guice or Ninject are just a few. However I have never seen a viable implementation of DI in JavaScript until AngularJs.

At first it seemed like a magic, so much that I actually had to dig into the framework code base to see how it’s done. As it turned out the idea behind the implementation is really simple. I did however encounter problems while trying to figure out why a particular service cannot be resolved or a directive isn’t working. Usually it was because of typos in parameter names or a missing dependency in module declaration. I know that the Angular team has put effort to make it easier to figure out those kind of problems in a recent release.

I’ve heard opinions that in a dynamic language as JavaScript the DI provides little to know gain instead adding an accidental complexity. I do agree that it is possible to live without however it requires much more discipline to keep a code clean. Whenever you create a service (a piece of code) that will be used in several places you have to make sure not to leak implementation details to clients (the ones that use the service). Without DI it means you have to make it easy to create a service by hand, typically by providing a factory method or a parameter less constructor. If you won’t take care of it upfront it will be harder to refactor the service implementation later on because of the number of clients that create it. When using DI at least this one task is forced upon you upfront.

Now what makes an actual implementation of DI practical is its ease of use. If you remember a time when most of C# and Java IoC containers required declaring actual object graph in an XML files you’ll understand what I mean. I think Angular team made using dependency injection feel easy and very natural and that’s what makes it so useful.

Dependency resolution and conflicts

There is an important limitation in Angular modules implementation around conflict resolution. Basically the framework uses last wins approach so you really have to be careful while naming things. It may seem not important at first but let’s consider following code sample.

var A = angular.module('A', []);

A.factory('serviceA', function(){
 return function(){
  console.log('using serviceA defined in module A');
 };
});

var B = angular.module('B', ['A']);

B.factory('serviceB', function(serviceA){
 return function(){
  console.group('using serviceB defined in module A');
  serviceA();
  console.groupEnd();
 };
});

var C = angular.module('C', ['A']);

C.factory('serviceA', function(){
 return function(){
  console.log('using serviceA defined in module C');
 };
});

C.factory('serviceC', function(serviceA){
 return function(){
  console.group('using serviceC defined in module C');
  serviceA();
  console.groupEnd();
 };
});

As you can see we have 3 modules here A, B and C. But in line 21 inside C module definition we’re declaring serviceA. Since module C depends on A that already defined serviceA we’re actually overriding the implementation. It’s quite useful to be able to override and stuff our custom implementation of particular service provided by other module. Except that we have no control over the scope of our modification. In the above example the serviceA defined in module C will be the one used everywhere at runtime. Even though module B knows nothing bout C. Calling declared services like this:

serviceA();
serviceB();
serviceC();

Will produce following output:

You can play around with this sample on jsfiddle.

What can we do about it? The only advice I’ve seen is to use prefix on service names. Now this is a working and simple approach however the code will not look great. I wonder how hard it would be to modify angular injector part to gain the ability to gain more control over overriding things…

AngularJs – my new superhero tool.

As I mentioned in my previous post I’ll describe my thoughts and findings about 3 popular JavaScript libraries that help building large web application. I’ll start with AngularJs which is the first one I’ve used in a real product.

Model View Whatever

Angular team didn’t try hard to map their concepts to classical MVC pattern. You can see it even in the title of its home page. Instead they focused on making a development path of a large web application as smooth and productive, in a long term, as possible. This means its really important to return to documentation and developer guide if you feel you’re getting lost along the way. Learning Angular is a really interesting journey especially that many concepts that I previously had categorized as not for the web turned out to be totally useful.

Model and view model

This term has really a short definition according to angular way:

a model is any data that is reachable as a property of an angular Scope object

The nice thing about it is that it really is up to you how you choose to encapsulate the most valuable and complex logic inside your model or view model classes. No base “class” , no artificial properties and helpers is required. In fact the framework won’t force you to build a proper view model for data-binding. While this freedom gives you more flexibility it also means that you are responsible for keeping your Controllers clean and thin. I prefer to put logic that encapsulates data and provides global, shared behaviour into separate classes totally unaware of the UI. Depending on the use case I’ll then put an instance of this model into scope or  if the presentation logic is more complex create a view model that wraps some model objects. To make the model objects easily accessible and sharable between views angular provides services. For a very simple logic that augments the way a single piece of data is presented there are filters.

One important thing to understand though is that data-binding is only happening between view (and directives) and a scope object. If a model object provides events fired when its state changes they have to implemented in a traditional way. When I say traditional I mean that you typically will need to apply Observer pattern – or rather use one of implementations available. This is somewhat different from the dirty checking mechanism that sits behind all the angular data-binding magic. Fortunately the framework provides a way to connect a non angular event to the scope with $apply method. However be warned that you have to be really careful here to call it only outside of angular digest cycle.

Controller – keep it thin

A controller is mainly responsible for setting up the scope object and as such is created on a per view basis. It is the most common entry point for an application behaviour triggered by DOM events. While its often easy to put more and more business logic inside them you should really try hard not to. As a reward I often found myself being able to reuse more logic than I anticipated. Another rule of thumb is to never access DOM elements from controller. Angular has a special place for all DOM related activities called directives.

Directive – a way to reusable ui

This is the part of angular that causes lot of confusion when it comes to building custom directives. Especially that whenever you need to manipulate DOM in any way you should use them. To make things easier there is a lot of not so obvious vocabulary used like compile, interpolate, link and my favourite transclude. In my opinion directives make working with data-binding in angular so productive. They are kind of hard to understand deeply at first, but reading the guide couple of times helps a lot. To demonstrate its power I’ll just say that entire jQuery ui is easily accessible with just one directive. I guess I have to little experience to provide some tips about building directives - the most complex one I’ve built was paginate. Here is a HTML snippet of how to use it:

<div paginate="items">
    <ul>
        <li ng-repeat="item in pager.paged">
            {{item.index}} {{item.text}}
        </li>
    </ul>
    <button ng-click="pager.previous()">Previous</button>  
    <span ng-repeat="page in pager.pages" 
             ng-class="pager.classForPage(page)">
      <a ng-click="pager.goTo(page)">{{page}}</a>
    </span>
    <button ng-click="pager.next()">Next</button>
</div>

Directive is the hardest part to fully understand but if you do learn them and built them in a generic way you can accelerate development a lot.

Views

I’ve only touched couple of aspects of Angular - there is a lot more to it. In particular I haven’t commented on View part in MVC trio. Angular tends to be criticised for the way it handles views. Mainly because you may get to a stage where it is hard to see actual html inside tons of directives attached to DOM elements. An alternative approach would be to use existing template engines like Handlebars – that’s the way it’s done in Ember.js – but it’s not really practical in Angular.

However I really like the idea that behaviour of html elements is immediately visible when you scan views mainly because declarative nature of directives. It makes it possible for an CSS or UI design expert, not familiar with Angular nor JavaScript, to make safe changes to views. In addition you no longer need to repeat selectors to access DOM and attach behaviour to it. This eliminates some of the maintenance burden. Like with any tool you have to be careful though not to overload html with directives and never put logic inside your views even if its only presentation related. If you find yourself repeating the same set of directives in many places of your codebase it may be good to step back a little and think of a way to encapsulate a common behaviour – probably with a more specific directives.

I’ll soon try to comment on features that Angular provides that make it suitable for large scale application development.