angular.directive

A directive is an HTML attribute that you can use in an existing HTML element type or in a DOM element type that you create as angular.widget, to modify that element's properties. You can use any number of directives per element.

For example, you can add the ng:bind directive as an attribute of an HTML span element, as in <span ng:bind="1+2"></span>. How does this work? The compiler passes the attribute value 1+2 to the ng:bind extension, which in turn tells the angular.scope to watch that expression and report changes. On any change it sets the span text to the expression value.

Here's how to define ng:bind:

  angular.directive('ng:bind', function(expression, compiledElement) {
    var compiler = this;
    return function(linkElement) {
      var currentScope = this;
      currentScope.$watch(expression, function(value) {
        linkElement.text(value);
      });
    };
  });

Directive vs. Attribute Widget

Both attribute widgets and directives can compile a DOM element attribute. So why have two different ways to do the same thing? The answer is that order matters, but we have no control over the order in which attributes are read. To solve this we apply attribute widget before the directive.

For example, consider this piece of HTML, which uses the directives ng:repeat, ng:init, and ng:bind:

Notice that the order of execution matters here. We need to execute ng:repeat before we run the ng:init and ng:bind on the <li/>;. This is because we want to run the ng:init="a=a+1 and ng:bind="person" once for each person in people. We could not have used directive to create this template because attributes are read in an unspecified order and there is no way of guaranteeing that the repeater attribute would execute first. Using the ng:repeat attribute directive ensures that we can transform the DOM element into a template.

Widgets run before directives. Widgets may manipulate the DOM whereas directives are not expected to do so, and so they run last.