Mastering AngularJS Directives

Directives are one of the most powerful components of AngularJS, helping you extend basic HTML elements/attributes and create reusable and testablecode. In this tutorial, I will show you how to use AngularJS directives with real-life best practices. 

What I mean here by directives is mostly custom directives during the tutorial. I will not try to teach you how to use built-in directives like ng-repeat, ng-show, etc. I will show you how to use custom directives to create your own components. 

Outline

1. Simple Directives
2. Directive Restrictions
3. Isolated Scope
4. Directive Scopes
5. Directive Inheritance
6. Directive Debugging
7. Directive Unit Testing
8. Directive Scope Testing
9. Conclusion

1. Simple Directives

Let say that you have an eCommerce application about books and you are displaying specific book detail in several areas, such as the comments, user profile pages, articles, etc. Your book detail widget may be like below:

In this widget there is a book image, title, description, comments, and rating. Collecting that information and putting in a specific dom element may be hard to do in every place you want to use it. Let's widgetize this view by using an AngularJS directive. 

01 02 03 04 05 06 07 08 09 10

angular.module('masteringAngularJsDirectives', []) .directive('book', function() {     return {         restrict: 'E',         scope: {             data: '='         },         templateUrl: 'templates/book-widget.html'     } })

A directive function has been used in the above example to create a directive first. The name of the directive is book. This directive returns an object, and let's talk a bit about this object. restrict is for defining the directive type, and it can be A (Attribute), C (Class), E (Element), and M (coMment). You can see the usage of each respectively below.

Type	Usage
A	<div book></div>
C	<div class="book"></div>
E	<book data="book_data"></book>
M	<!--directive:book -->

scope is for managing the directive scope. In the above case, book data is transferred to the directive template by using the "=" scope type. I will talk about in detail about scope in the following sections. templateUrl is used for calling a view in order to render specific content by using data transferred to the directive scope. You can also use template and provide HTML code directly, like this:

1 2 3

..... template: '<div>Book Info</div>' .....

In our case, we have a complicated HTML structure, and that is why I chose the templateUrl option.

2. Directive Restrictions

Directives are defined in the JavaScript file of your AngularJS project and used in the HTML page. It is possible to use AngularJS directives in HTML pages as follows:

A (Attribute)

In this usage, the directive name is used inside standard HTML elements. Let say that you have a role-based menu in your eCommerce application. This menu is formed according to your current role. You can define a directive to decide whether the current menu should be displayed or not. Your HTML menu may be like below:

1 2 3 4 5 6

<ul>     <li>Home</li>     <li>Latest News</li>     <li restricted>User Administration</li>     <li restricted>Campaign Management</li> </ul>

and the directive as follows:

01 02 03 04 05 06 07 08 09 10 11 12

app.directive("restricted", function() {     return {         restrict: 'A',         link: function(scope, element, attrs) {             // Some auth check function             var isAuthorized = checkAuthorization();             if (!isAuthorized) {                 element.css('display', 'none');             }         }     } })

If you use the restricted directive in the menu element as an attribute, you can do an access level check for each menu. If the current user is not authorized, that specific menu will not be shown. 

So, what is the link function there? Simply, the link function is the function that you can use to perform directive-specific operations. The directive is not only rendering some HTML code by providing some inputs. You can also bind functions to the directive element, call a service and update the directive value, get directive attributes if it is an E type directive, etc.

C (Class)

You can use the directive name inside HTML element classes. Assuming that you will use the above directive as C, you can update the directive restrict asC and use it as follows:

1 2 3 4 5 6

<ul>     <li>Home</li>     <li>Latest News</li>     <li class="nav restricted">User Administration</li>     <li class="nav active restricted">Campaign Management</li> </ul>

Each element already has a class for styling, and as the restricted class is added it is actually a directive.

E (Element)

You don't need to use a directive inside an HTML element. You can create your own element by using an AngularJS directive with an E restriction. Let's say that you have a user widget in your application to show username, avatar, andreputation in several places in your application. You may want to use a directive like this:

01 02 03 04 05 06 07 08 09 10 11

app.directive("user", function() {     return {         restrict: 'E',         link: function(scope, element, attrs) {             scope.username = attrs.username;             scope.avatar = attrs.avatar;             scope.reputation = attrs.reputation;         },         template: '<div>Username: {{username}}, Avatar: {{avatar}}, Reputation: {{reputation}}</div>'     } })

The HTML code will be:

1	<user username="huseyinbabal" avatar="https://www.gravatar.com/avatar/ef36a722788f5d852e2635113b2b6b84?s=128&d=identicon&r=PG" reputation="8012"></user>

In the above example, a custom element is created and some attributes are provided like username, avatar, and reputation. I want to draw attention to the link function body. Element attributes are assigned to directive scope. The first parameter of the link function is the scope of the current directive. The third parameter of the directive is the attribute object of the directive, which means that you can read any attribute from the custom directive by usingattrs.attr_name. Attribute values are assigned to the scope so that they are used inside the template. 

Actually, you can do this operation in a shorter way, and I will talk about that later. This example is for understanding the main idea behind usage.

M (coMment)

This usage is not very common, but I will show how to use it. Let's say that you need a comment form for your application to use in many places. You can do that by using the following directive:

1 2 3 4 5 6

app.directive("comment", function() {     return {         restrict: 'M',         template: '<textarea class="comment"></textarea>'     } })

And in the HTML element:

1	<!-- directive:comment -->

3. Isolated Scope

Every directive has its own scope, but you need to be careful about the data binding with the directive declaration. Let say that you are implementing thebasket part of your eCommerce application. On the basket page you have items already added here before. Each item has its amount field to select how many items you want to buy, like below:

Here's the directive declaration:

1 2 3 4 5 6 7 8 9

app.directive("item", function() {     return {         restrict: 'E',         link: function(scope, element, attrs) {             scope.name = attrs.name;         },         template: '<div><strong>Name:</strong> {{name}} <strong>Select Amount:</strong> <select name="count" ng-model="count"><option value="1">1</option><option value="2">2</option></select> <strong>Selected Amount:</strong> {{count}}</div>'     } })

And in order to display three items in HTML:

1 2 3

<item name="Item-1"></item> <item name="Item-2"></item> <item name="Item-3"></item>

The problem here is that whenever you choose the amount of the desired item, all the amount sections of the items will be updated. Why? Because there is two-way data binding with a name count, but scope is not isolated. In order to isolate scope, just add scope: {} to the directive attribute in the return section:

01 02 03 04 05 06 07 08 09 10

app.directive("item", function() {     return {         restrict: 'E',         scope: {},         link: function(scope, element, attrs) {             scope.name = attrs.name;         },         template: '<div><strong>Name:</strong> {{name}} <strong>Select Amount:</strong> <select name="count" ng-model="count"><option value="1">1</option><option value="2">2</option></select> <strong>Selected Amount:</strong> {{count}}</div>'     } })

This leads your directive to have its own isolated scope so two-way data binding will occur inside this directive separately. I will also mention about the scope attribute later.

4. Directive Scopes

The main advantage of the directive is that it's a reusable component that can be used easily—you can even provide some additional attributes to that directive. But, how is it possible to pass additional value, binding, or expression to a directive in order for data to be used inside the directive?

"@" Scope: This type of scope is used for passing value to the directive scope. Let's say that you want to create a widget for a notification message:

01 02 03 04 05 06 07 08 09 10 11 12

app.controller("MessageCtrl", function() {     $scope.message = "Product created!"; }) app.directive("notification", function() {     return {         restrict: 'E',         scope: {             message: '@'         },         template: '<div class="alert">{{message}}</div>'     } });

and you can use:

1	<notification message="{{message}}"></notification>

In this example, the message value is simply assigned to the directive scope. The rendered HTML content will be:

1	<div class="alert">Product created!</div>

"=" Scope: In this scope type, scope variables are passed instead of the values, which means that we will not pass {{message}}, we will pass message instead. The reason behind this feature is constructing two-way data binding between the directive and the page elements or controllers. Let's see it in action.

1 2 3 4 5 6 7 8 9

.directive("bookComment", function() {     return {         restrict: 'E',         scope: {             text: '='         },         template: '<input type="text" ng-model="text"/>'     } })

In this directive, we are trying to create a widget for displaying comment text input to make a comment for a specific book. As you can see, this directive requires one attribute text to construct two-way data binding between other elements on the pages. You can use this on the page:

1 2	<span>This is the textbox on the directive</span> <book-comment text="commentText"></book-comment>

This will simply show a textbox on the page, so let's add something more to interact with this directive:

1 2 3 4 5

<span>This is the textbox on the page</span> <input type="text" ng-model="commentText"/> <br/> <span>This is the textbox on the directive</span> <book-comment text="commentText"></book-comment>

Whenever you type something in the first text box, it will be typed also in the second text box. You can do that vice versa. In the directive, we passed the scope variable commentText instead of the value, and this variable is the data binding reference to the first text box. 

"&" Scope: We are able to pass the value, and reference to directives. In this scope type we will have a look at how to pass expressions to the directive. In real-life cases, you may need to pass a specific function (expression) to directives in order to prevent coupling. Sometimes, directives do not need to know much about the idea behind the expressions. For example, a directive will like the book for you, but it doesn't know how to do that. In order to do that, you can follow a structure like this:

1 2 3 4 5 6 7 8 9

.directive("likeBook", function() {     return {         restrict: 'E',         scope: {             like: '&'         },         template: '<input type="button" ng-click="like()" value="Like"/>'     } })

In this directive, an expression will be passed to the directive button via thelike attribute. Let's define a function in the controller and pass it to the directive inside the HTML.

1 2 3

$scope.likeFunction = function() {     alert("I like the book!") }

This will be inside the controller, and the template will be:

1	<like-book like="likeFunction()"></like-book>

likeFunction() comes from the controller and is passed to the directive. What if you want to pass a parameter to likeFunction()? For example, you may need to pass a rating value to the likeFunction(). It is very simple: just add an argument to the function inside the controller, and add an input element to the directive to require start count from the user. You can do that as shown below:

01 02 03 04 05 06 07 08 09 10

.directive("likeBook", function() {     return {         restrict: 'E',         scope: {             like: '&'         },         template: '<input type="text" ng-model="starCount" placeholder="Enter rate count here"/><br/>' +         '<input type="button" ng-click="like({star: starCount})" value="Like"/>'     } })

1 2 3

$scope.likeFunction = function(star) {     alert("I like the book!, and gave " + star + " star.") }

1	<like-book like="likeFunction(star)"></like-book>

As you can see, the text box comes from the directive. The text box value is bound to the function argument like like({star: starCount}). star is for the controller function, and starCount for the textbox value binding. 

5. Directive Inheritance

Sometimes, you may have a feature that exists in several directives. They can be put in a parent directive so that they are inherited by the child directives. 

Let me give you a real-life example. You want to send statistical data whenever customers move their mouse cursor to the top of a specific book. You can implement a mouse click event for the book directive, but what if it will be used by another directive? In this case, you can use inheritance of the directives like below:

1 2 3 4 5 6 7

app.directive('mouseClicked', function() {     return {         restrict: 'E',         scope: {},         controller: "MouseClickedCtrl as mouseClicked"     } })

This is a parent directive to be inherited by child directives. As you can see there is a controller attribute of the directive using the "as" directive. Let's define this controller also:

01 02 03 04 05 06 07 08 09 10 11 12 13

app.controller('MouseClickedCtrl', function($element) {     var mouseClicked = this;       mouseClicked.bookType = null;       mouseClicked.setBookType = function(type) {         mouseClicked.bookType = type     };       $element.bind("click", function() {         alert("Typeof book: " + mouseClicked.bookType + " sent for statistical analysis!");     }) })

In this controller, we are simply setting a controller instance of the variablebookType by using child directives. Whenever you click a book or magazine, the type of element will be sent to the back-end service (I used an alert function just to show the data). How will child directives be able to use this directive?

01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16

app.directive('ebook', function() {     return {         require: "mouseClicked",         link: function(scope, element, attrs, mouseClickedCtrl) {             mouseClickedCtrl.setBookType("EBOOK");         }     } }) .directive('magazine', function() {     return {         require: "mouseClicked",         link: function(scope, element, attrs, mouseClickedCtrl) {             mouseClickedCtrl.setBookType("MAGAZINE");         }     } })

As you can see, child directives use the require keyword to use the parent directive. And one more important point is the fourth argument of the link function in the child directives. This argument refers to the controller attribute of the parent directive that means the child directive can use the controller function setBookType inside the controller. If the current element is an eBook, you can use the first directive, and if it is a magazine, you can use the second one:

1 2	<a><mouse-clicked ebook>Game of thrones (click me)</mouse-clicked></a><br/> <a><mouse-clicked magazine>PC World (click me)</mouse-clicked></a>

Child directives are like a property of the parent directive. We have eliminated the usage of the mouse-click event for each child directive by putting that section inside the parent directive.

http://code.tutsplus.com/tutorials/mastering-angularjs-directives--cms-22511