Custom Directive Introduction

AngularJS directives are what controls the rendering of the HTML inside an AngularJS application. Examples of directives are the interpolation directive ( {{ }} ), the ng-repeat directive and ng-if directive.

It is possible to implement your own directives too. This is what AngularJS refers to as "teaching HTML new tricks". This text will show you how to do that.

Directive Types

You can implement the following types of directives:

• Element directives
• Attribute directives
• CSS class directives
• Comment directives

Of these, AngularJS recommends that you try to use element and attribute directives, and leave the CSS class and comment directives (unless absolutely necessary).

The type of a directive determines how the directive is activated. An element directive is activated when AngularJS finds a matching HTML element in the HTML template. An attribute directive is activated when AngularJS finds a matching HTML element attribute. A CSS class directive is activated when AngularJS finds a matching CSS Class. And, a comment directive is activated when AngularJS finds a matching HTML comment.

A Basic Directive

You register a directive with a module. Here is an example of how that looks:

myapp = angular.module("myapp", []);

myapp.directive('div', function() {
    var directive = {};

    directive.restrict = 'E'; /* restrict this directive to elements */

    directive.template = "My first directive: {{textToInsert}}";

    return directive;
});

Notice the call to the directive() function on the module. When you call this function you can register a new directive. The first parameter to the directive() function call is the name of the directive to register. This name is what you use in your HTML templates when you want to activate the directive. In this example I have used the name 'div' which means that the directive is activated every time an HTML element named div is found in the HTML template.

The second parameter passed to the directive function is a factory function. This function should return a directive definition when invoked. AngularJS will invoke this function to obtain a JavaScript object which contains the definition of the directive. If you look inside the function in the above example you will see that it does indeed return a JavaScript object.

The JavaScript object returned from the factory function has two properties: A restrict field and a template field.

The restrict field is used to set if the directive should be activated by a matching HTML element, or an element attribute. By setting restrict to E you specify that only HTML elements named div should activate the directive. By setting restrict to A you specify that only HTML attributes named div should activate the directive. You can also use a value of AE which will match both HTML element names and attribute names.

The template field is an HTML template that will replace the content of the matched div element. It will work as if the content of the matched div element had not been there, and instead this HTML template had been located in the same place.

Imagine that your HTML page has this HTML:

<div ng-controller="MyController" >
    <div>This div will be replaced</div>
</div>

Then the added directive would be activated when AngularJS finds the inner div element. Instead of this div element, this HTML will be inserted:

My first directive: {{textToInsert}}

As you can see, this HTML contains an interpolation directive ({{textToInsert}}). AngularJS will interpret this HTML again, so that the interpolation directive actually works. The value of the $scope.textToInsert property will be inserted at this point in the HTML.