An Introduction to Angular Directives

Warning: Illegal string offset 'filter' in /var/sites/t/ on line 1409

This is the first part of a series looking into some important concepts in Angular.

Directives are the essence of Angular – if you can understand how directives work, and how to use them, you are a fair way towards understanding Angular.

What is a directive?

The definition of the word directive according to is:

An order or instruction, especially one issued by an authority.

…and that is what a directive is in Angular – an instruction. To be more specific, it is an instruction to the Angular compiler, issued by an authority – you, to render a particular DOM element in a predefined way, such as adding some behaviour.

What is the Angular compiler?

The compiler is a service which walks through your HTML, looking for directives, and rendering them as specified by your directive definitions.

Adding behaviour to a DOM element, that sounds like what you can do with jQuery?

It is true that you can add behaviour to an element using jQuery, however the difference with Angular directives is that they are separated from the HTML which uses them.

When you write some jQuery to add behaviour, say a click event to a button, your jQuery code depends upon your HTML. This dependency makes testing difficult, and your HTML page tends to give little information with regards to its behaviour. For these reasons and others, using Angular directives is almost always a better approach than adding behaviour to the DOM using jQuery.

What does an Angular directive look like?

There are two main ways in which directives can be used in Angular1 : by attribute name, and by tag name.

Using an Angular directive via a tag name:

Using an Angular directive via an attribute name:

If you have any experience with Angular you will be familiar with attributes such as ng-app and ng-controller, which you need to use for Angular to work. These are also directives, which are built-in to Angular. The basket-contents directive in the examples above is a custom directive, created by the developer.

In this way, Angular directives essentially allow you to use new syntax when composing your HTML pages.

How are custom directives defined?

Angular applications are built via modules, and for each custom directive in your application, you need to decide which module to add it to. A directive needs a module to exist in. The process of adding a custom directive to a module is referred to as registering that directive.

To register a directive, you need to provide at least two things: a name for it, and a factory function.

The factory function you define should return an object2, whose properties tell the Angular compiler what to render (including behaviour) wherever your directive appears.

The simplest form of custom directive replaces an element with some static HTML. This might be useful when you have some HTML which you want to reuse across your application.

Here is a really simple example, where our template (our reusable markup) consists of some static HTML.



In the markup the directive is called ‘basket-contents’, but in the JavaScript it is ‘basketContents’?

Yes – there is a reason for this. Because HTML is case-insensitive, and we want to use camel case in our JavaScript (as this is standard practice), Angular normalizes dash-delimited attributes, and so matches our basket-contents tag name to our basketContents directive.

Presumably if you have a more complex template, you can specify a separate HTML file, rather than defining it inline?

Correct. You do this by using the templateUrl property, instead of the template property:


What about if we want to render some dynamic HTML in our template?

This can be done in a number of ways.

An extremely common requirement is to shape what is rendered according to the state of our model. This is achieved in Angular through data binding, whether we are using custom directives or not. Using Angular’s double curly brace notation for binding expressions, we can modify our code to display some value from our model. To do this, we will add a controller.



Why do we now need to add a controller?

Controllers in Angular are used to expose variables and functionality to directives. The fact that we now have a model to think about, means that it is time to introduce a controller. Our BasketController would expose data and functionality to our basket-related views, via directives and expressions.

Now that we have scratched the surface of Angular directives, the next part in this series will look in more detail at Angular controllers.

1 It is also possible to use a directive via a class name, or via comments, however it is best practice to use tag names or attribute names where possible.
2 The factory function can also return a function, but it is standard practice to return an object.

Share Button