Building a simple element directive

One of the most common use cases of directives is to create custom HTML elements that are able to encapsulate their own template and behavior. Directive complexity increases very quickly, so ensuring your understanding of its foundation is essential. This recipe will demonstrate some of the most basic features of directives.

How to do it…

Creating directives in AngularJS is accomplished with a directive definition object. This object, which is returned from the definition function, contains various properties that serve to shape how a directive will act in your application.

You can build a simple custom element directive easily with the following code:

(app.js)

// application module definition
angular.module('myApp', [])
.directive('myDirective', function() {
  // return the directive definition object
  return {
    // only match this directive to element tags
    restrict: 'E',
    // insert the template matching 'my-template.html'
    templateUrl: 'my-template.html'
  };
});

As you might have guessed, it's bad practice to define your directive template with the template property unless it is very small, so this example will skip right to what you will be using in production: templateUrl and $templateCache. For this recipe, you'll use a relatively simple template, which can be added to $templateCache using ng-template. An example application will appear as follows:

(index.html)

<!-- specify root element of application -->
<div ng-app="myApp">
  <!-- register 'my-template.html' with $templateCache -->
  <script type="text/ng-template" id="my-template.html">
    <div ng-repeat="num in [1,2,3,4,5]">{{ num }}</div>
  </script>  
  
  <!-- your custom element -->
  <my-directive></my-directive>
</div>

When AngularJS encounters an instance of a custom directive in the index.html template, it will compile the directive into HTML that makes sense to the browser, which will look as follows:

<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>

Tip

JSFiddle: http://jsfiddle.net/msfrisbie/uwpdptLn/

How it works…

The restrict: 'E' statement indicates that your directive will appear as an element. It simply instructs AngularJS to search for an element in the DOM that has the my-directive tag.

Especially in the context of directives, you should always think of AngularJS as an HTML compiler. AngularJS traverses the DOM tree of the page to look for directives (among many other things) that it needs to perform an action for. Here, AngularJS looks at the <my-directive> element, locates the relevant template in $templateCache, and inserts it into the page for the browser to handle. The provided template will be compiled in the same way, so the use of ng-repeat and other AngularJS directives is fair game, as demonstrated here.

There's more…

A directive in this fashion, though useful, isn't really what directives are for. It provides a nice jumping-off point and gives you a feel of how it can be used. However, the purpose that your custom directive is serving can be better implemented with the built-in ng-include directive, which inserts a template into the designated part of HTML. This is not to say that directives shouldn't ever be used this way, but it's always good practice to not reinvent the wheel. Directives can do much more than template insertion (which you will soon see), and it's best to leave the simple tasks to the tools that AngularJS already provides to you.