A previous post talked about a general idea behind data annotation and the ability to mark up classes. But the example was far from being real world or useful. Today we are going to explore the way that data annotation can be used to decouple business logic with angular bindings. We are in search of a simpler solution to ES6 modules or RequireJS and Angular modules.

Module Pattern and Angular

ES6 brings us modules and the "import" keyword for better composition management, which basically means that this code:

import {ngBase} from './ngBase';  

transforms into RequireJS code that creates a dependency and on './ngBase

define(['./ngBase'], function($__0) {  
  "use strict";
  if (!$__0 || !$__0.__esModule)
  $__0 = {default: $__0};
  var ngBase = $__0.ngBase;
});

Nicely enough, ngBase becomes the variable into which the import is piped, scoped to the wrapper function. So how does this play with something like Angular which has its module system. A quick look online brings about a general consensus that the module pattern is good for business logic, but the angular bootstrapping should take place once the require js modules are loaded.

• http://www.sitepoint.com/using-requirejs-angularjs-applications/
• http://solutionoptimist.com/2013/09/30/requirejs-angularjs-dependency-injection/
• http://marcoslin.github.io/angularAMD/#/home
• http://stackoverflow.com/questions/12529083/does-it-make-sense-to-use-require-js-with-angular-js

Each of these post talks about creating non-angular aware modules that are later bootstrapped in another bootstrapping file. In my mind, this is a bit messy. When anything changes, you must change the bootstrapping file and the implementation file logic. But data annotation solves this problem. We can defer bootstrapping by marking our classes with all required data annotations to complete the late bootstrapping.

Annotate it All

So data annotation lets us create classes that understand their own purpose. Ideally, anything in Angular can be broken down into a class constructor function with annotation that defines the class function.

We annotate the controller/factory/directive name and dependency list into the ngController/ngFactory/ngDirective and ngInject annotation.

Annotation Classes

The magic behind this type of annotation is a collection of annotation classes that can register the class it annotates against an angular module.

ngBase class is an abstract that all Angular-based annotations derive from. We do have a useful wrap function, which allows us to wrap the Angular array notation for dependency injection. The ngBase class is common ground for all Angular annotations from Angular registering functions (ngController/ngFactory/ngDirective).

ngController class is an actual annotation class. It describes controllers to angular modules. The register function, which is aware of annotation on the class, can work in combination with other annotations like route and inject. The controller annotation simply takes the name.

@ngController('main')
@ngInject(['$scope', 'data'])
@ngRoute('/Home', { templateUrl : 'home.html' });

export class main {  
  constructor($scope, data) {
    $scope.data = data();
  }
}

ngFactory annotation class for creating factories, the Angular version of a singleton. Like ngController, it also works in combination with

@ngFactory('data')

export class data {  
  constructor() {
    return () => "test";
  }
}

ngDirective annotation class for creating directives has some additional logic. Like the other ngBase classes the name of the directive is the first argument of the annotation constructor and the directive property object as the second argument. The constructor of the annotated class automatically becomes the link function on the directive object.

@ngDirective('hello', {
  scope : true,
  template : '<div> hello {{data}}</div>',
  restrict : 'AE'
})
@ngInject(['data'])
export class hello {  
  constructor(data) {
    return (scope, element, attr) => {
      scope.data = data();
    }
  }
}

The Bootstrapper

Annotations can bind behavior to a class, and we can process the behavior by looking at injectable dependencies. The ngBootstrap class processes a list of imports. In our bootstrapping process, this is denoted by arguments based on how Tracuer transpiles this code.

import {ngBootstrap} from './lib/ngBootstrap';  
import {data} from './data';  
import {main} from './main';  
import {hello} from './hello';

var app = ngBootstrap(document, angular.module('test', []), arguments);  

Transpiled, we get this code, which explains the argument's object.

define(['./lib/ngBootstrap', './data', './main', './main2', './hello'], function($__0,$__2,$__4,$__6,$__8) {  
  "use strict";
  if (!$__0 || !$__0.__esModule)
  $__0 = {default: $__0};
  if (!$__2 || !$__2.__esModule)
  $__2 = {default: $__2};
  if (!$__4 || !$__4.__esModule)
  $__4 = {default: $__4};
  if (!$__6 || !$__6.__esModule)
  $__6 = {default: $__6};
  if (!$__8 || !$__8.__esModule)
  $__8 = {default: $__8};
  var ngBootstrap = $__0.ngBootstrap;
  var data = $__2.data;
  var main = $__4.main;
  var main2 = $__6.main2;
  var hello = $__8.hello;
  var app = angular.module('test', ['ngRoute']);
  ngBootstrap(document, app, arguments);
  return {};
});

Conclusion

You can find running code examples here

This post gave a real world example of the usefulness of data annotation. But there is a lot more. There are benefits to decoupling the application from Angular. The annotation can be quickly re-writen to bind a different framework to your current classes. There are benefits to unit testing a directive without needing to bind to angular.

Overall, data annotation is a tool for the tool box, and more posts will come on how this tool is useful.

The Angular team published a playground for @script: https://github.com/angular/atscript-playground

So why is annotation-oriented programing so much win?

The quick answer is meta programing. Buzz word alert: The basic idea is that you can mark up some object in your code with additional meta-information. And the cool part: parse that mark up at runtime to give your application additional intelligence.

But lets take a quick look:

// An annotation class that defines an animal
class animal {  
  constructor(sound) {
    this.sound = sound;
  }
  speak() {
    console.log(this.sound);
  }
}

An annotation is really just the instantiation of some class that can be bound to an 'annotations' property on the target class. The above code created an annotation class called "animal." When instantiating a class, we can create animal with a custom sound. As the example bellow shows, the @script annotation syntax allows us to attach the annotation class of "animal" to any classes we create like "cow" or "dog" targets.

// Create a cow class an annotate it with a cow sound.
@animal('Mooo')
class cow {  
}

// Create a dog class and annotate it with a dog sound.
@animal('Woof')
class dog {  
}

This is @script transpilation; the @animal('Woof') actually translates to the following JavaScript.

var dog = function dog() {};  
($traceurRuntime.createClass)(dog, {}, {});
Object.defineProperty(dog, "annotations", {get: function() {  
  return [new animal('Woof')];
}});

After the classes are marked up with annotation, a new property, 'annotations,' becomes available on the class object. It is an array, allowing for multiple annotations to be applied to a class.

cow.annotations[0].speak() //=> Mooo  
dog.annotations[0].speak() //=> Woof  

This is nothing revolutionary, but it does create a great convention, allowing us to write code that describes itself to itself. Lets take a look at a way that this can be consumed. In the code example, lo-dash, it is used for writing functional code, I am a lambda whore.

_.each([cat, dog, table], c => {  
  var noop =  { speak : () => {}};
  (c.annotations || [ noop ])[0].speak();
  });

Each loop can process the individual classes for the annotation property. In more complicated workflows, this can take into account the different annotation classes.

Conclusion

You can find running code examples here.

The code example above is not very useful, since any number of polymorphic practices can resolve this problem in much cleaner ways. But it does show how annotations can create behaviors on classes that you may not have the rights to change. Annotation also get out of the way of the implementation, allowing you to attack cross cutting concerns without affecting the annotated class.