Custom Directives in AngularJS

This article explains custom directives.

Directives are the most important components of any AngularJS application. Directives are markers on a DOM element that tell angular js HTML compiler to attach specific behaviour to that element. We know the use of some commonly used built-in directives like ng-app, ng-controller, ng-repeat, ng-show, ng-hide and so on. All these directives attach special behaviour to DOM elements.

Although AngularJS ships with a wide range of directives, you will often need to create application-specific directives since some of the requirements in the application requirements vary. The custom directive helps the developer in creating a reusable component that can be maintained easily. Consider the example of a custom control or web user control in ASP.Net web applications or HTML helpers in ASP.Net MVC applications. Very similar to that, custom directives are UI components built in angular js.

Angular js has its own way of manipulating the DOM element, it is not the same way as in jQuery. It is the directive where we need to do the DOM Manipulation. Don't mix up jQuery with angular js it will create a mess up code which is not a good practice.

Custom directives are used in AngularJS to extend the functionality of HTML. Custom directives are defined using the "directive" function. A custom directive simply replaces the element for which it is activated. An AngularJS application during bootstrap finds the matching elements defined in the custom directive and does a one-time activity using its compile() method of the custom directive then processes the element using the link() method of the custom directive based on the scope of the directive. AngularJS provides support to create custom directives for the following types of elements.

AngularJS Directives are markers on a DOM element (such as an attribute, element name, comment or CSS class) that tells the AngularJS HTML compiler ($compile) to attach a specified behaviour to that DOM element or even transform the DOM element and its children.

Custom directives in AngularJS is your own directive with their own core functions that run when the DOM is compiled by the compiler. Suppose we want to reuse a specific lines of code in multiple pages of our application without code duplication, then we simply put that specific piece of code in a separate file and call that code using a custom directive instead of writing it over and over again. This way code is better to understand.

Let us look at the syntax of creating a custom directive as in the following:

 

myModule.directive("directiveName", function(injectables component)
{
    return
    {
        restrict: "A/E/C/M", //Attribute Element Class Comment
        template: "<div></div>", // Html to be added
        templateUrl: "directive.html", // template to be added
        replace: false, // replace yes/No
        transclude: false, // Transclude yes/No
        scope: false, // Current scope or isolated scope
        require: ["someOtherDirective"], // if any other directive is needed
        controller: function($scope, $element, $attrs, $transclude, otherInjectables) {...
        }, // controller
        link: function postLink(scope, iElement, iAttrs) {...
        },
        priority: 0, //Priority of directive
        terminal: false,
        compile: function compile(tElement, tAttrs, transclude)
        {
            return
            {
                pre: function preLink(scope, iElement, iAttrs, controller) {...
                },
                post: function postLink(scope, iElement, iAttrs, controller) {...
                } // compile functions
            }
        }
    };
});

When writing a custom directive we don't need all the parameters, we need some of them depending on our needs. Let us understand what these parameters are and what role they play in custom directives.

 

restrict: Specifies how a directive can be used. Possible values are: E (element), A (Attribute), C (Class) and M (Comment). The default value is A. This provides a way to specify how a directive should be used in HTML (remember a directive can appear in four ways). In this case we have set it to "AE". So, the directive can be used as a new HTML element or an attribute. To allow this directive to be used as a class we can set restrict to "AEC".

template: HTML template to be rendered in the custom directive. This specifies the HTML markup that will be produced when the directive is compiled and linked by Angular codes. This does not need to be a simple string. The template can be complex, often involving other directives, expressions ({{ }}) and so on. In most cases you want to use templateUrl instead of template. So, ideally you should place the template in a separate HTML file and make templateUrl point to it.

templateUrl: URL of the file containing HTML template of the element.

replace: Boolean value denoting if the directive element is to be replaced by the template. The default value is false.

transclude: Boolean value that says if the directive should preserve the HTML specified inside the directive element after rendering. The default is false. Let's understand a bit more on transclude.

Example of transclude

Consider a directive called myDirective in an element and that element is enclosing some other content, let's say:

 

<div my-directive>
   <button>some button</button>
   <a href="#">and a link</a>
</div>

If myDirective is using a template, you'll see that the content of <div my-directive> will be replaced by your directive template. So having:

 

app.directive('myDirective', function()
{
    return
    {
        template: '<div class="something"> This is my directive content</div>'
    }
});

This will result in this render:

 

<div class="something"> This is my directive content</div>

Observe here, the content of your original element <div my-directive> will be lost.

 

<button>some button</button>
<a href="#">and a link</a>

So, what if you want to keep your page as in the following:

<button>some button</button>
<a href="#">and a link</a>

You'll need something called transclusion.

Include the content from one place into another. So now your directive will look something like this:

app.directive('myDirective', function()
{
    return
    {
        transclude: true,
        template: '<div class="something" ng-transclude> This is my directive content</div>'
    }
});

This would render:

 

<div class="something"> This is my directive content
   <button>some button</button>
   <a href="#">and a link</a>
</div>

Scope: Scope of the directive. It may be the same as the scope of the surrounding element (default or when set to false), inherited from the scope of the surrounding element (set to true) or an isolated scope (set to {}).

By default, a directive gets the parent's scope. But we don't want that in all cases. If we are exposing the parent controller's scope to the directives, they are free to modify the scope properties. In some cases your directive may want to add several properties and functions to the scope that are for internal use only. If we are doing these things to the parent's scope, we are polluting it. So, we have the following two other options:

• A child scope: This scope prototypically inherits the parent's scope.
• An isolated scope: A new scope that does not inherit from the parent and exists on its own.

In Angular, this binding can be done by setting attributes on the directive element in HTML and configuring the scope property in the directive definition object.

Let's explore a few ways of setting up the binding.

Option 1: Use @ for One Way Text Binding

Binds the value of parent scope property (that is always a string) to the local scope. So the value you want to pass in should be wrapped in {{}}.

Option 2: Use = for two-way binding and binds the Parent scope property directly that will be evaluated before being passed in.

Option 3: Use and to Execute functions in the parent scope and binds an expression or method that will be executed in the context of the scope it belongs in.

app.directive('helloWorld', function()
{
    return
    {
        scope: {
            Name: '='
            Name: '@'
            Name: '='
        },
        // other codes go here
    };
});

By default a directive does not create a new scope and uses the parent's scope. But in many cases this is not what we want. If your directive manipulates the parent scope properties heavily and creates new ones, it might pollute the scope. Letting all the directives use the same parent scope is not a good idea because anybody can modify our scope properties. So, the following guidelines may help you choose the right scope for your directive.

Parent Scope (scope: false): This is the default case. If your directive does not manipulate the parent scope properties you might not need a new scope. In this case, using the parent scope is okay.

Child Scope (scope:true): This creates a new child scope for a directive that prototypically inherits from the parent scope. If the properties and functions you set on the scope are not relevant to other directives and the parent, you should probably create a new child scope. With this you also have all the scope properties and functions defined by the parent.

Isolated Scope (scope:{}): This is like a sandbox! You need this if the directive you will build is self-contained and reusable. Your directive might be creating many scope properties and functions that are meant for internal use and should never be seen by the outside world. If this is the case, it's better to have an isolated scope. The isolated scope, as expected, does not inherit the parent scope.

require: A list of directives that the current directive needs. The current directive gets access to controller of the required directive. An object of the controller is passed into the link function of the current directive

controller: Controller for the directive. Can be used to manipulate values on scope or as an API for the current directive or a directive requiring the current directive.

priority: Sets the priority of a directive. The default value is 0. A directive with a higher priority value is executed before a directive with a lower priority.

terminal: Used with priority. If set to true, it stops execution of directives with lower priority. Default is false.

link: A function that contains the core logic of the directive. It is executed after the directive is compiled. Gets access to the scope and element on which the directive is applied (jqLite object attributes) of the element containing the directive and controller object. Generally used to perform DOM manipulation and handling events.

compile: A function that runs before the directive is compiled. Doesn't have access to the scope since the scope is not created yet. Gets an object of the element and attributes. Used to perform the DOM of the directive before the templates are compiled and before the directive is transcluded. It returns an object with the following two link functions:

pre link: Similar to the link function, but it is executed before the directive is compiled. By this time, transclusion is applied. Used rarely. One of the use cases is when a child directive requires data from its parent, the parent directive should set it through its pre-link function. Set data required for its child directives. Safe to attach event handlers to the DOM element. Not safe to access DOM elements belonging to child directives. They're not linked yet.

post link: This is the most commonly used for data binding. Safe to attach event handlers to the DOM element. All children directives are linked, so it's safe to access them. Never set any data required by the child directive here, because the child directive's will be linked already.

Compilation in directives

When the application bootstraps, Angular starts parsing the DOM using the $compile service. This service searches for directives in the mark-up and matches them against registered directives. Once all the directives have been identified, Angular executes their compile functions. As previously said, the compile function returns a link function that is added to the list of link functions to be executed later. This is called the compile phase. If a directive needs to be cloned multiple times (for example ng-repeat), we get a performance benefit since the compile function runs once for the cloned template, but the link function runs for each cloned instance. That's why the compile function does not receive a scope.

After the compile phase is over, next is the linking phase, where the collected link functions are executed one by one. This is where the templates produced by the directives are evaluated against correct scope and are turned into a live DOM that reacts to events.

Let's do some simple samples on custom directives now.

Example-1

We will create a directive called "firstDirective" that will return us a sample text.

 

<!DOCTYPE html>
<html ng-app="myApp">
    <head>
        <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.9/angular.min.js"></script>
        <script>

var myapp = angular.module('myApp', [])

myapp.directive('firstDirective', function () {

return {

template: '
            <h3> I am From custom directive !!! </h3>'

};

});
        </script>
    </head>
    <body>
        <div ng-app="myApp">
            <div>
                <div>
                    <first-directive>
                </div>
            </div>
        </div>
    </body>
</html>

Note: "firstDirective" name must be a camel case while declaring a directive and while calling it should be written as <first-directive> . There are some other way of calling it as in the following:

<first_directive> or <first:directive>

Output below

 

Example-2

We will create a directive that will convert the first letter of words to uppercase.

 

<!DOCTYPE html>
<html ng-app="myApp">
<head>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.9/angular.min.js"></script>
<script>
var myApp = angular.module('myApp', []);
myApp.directive('capitalizeFirst', function (uppercaseFilter, $parse) {
return {
require: 'ngModel',
link: function (scope, element, attrs, modelCtrl) {
var capitalize = function (inputValue) {
var capitalized = inputValue.charAt(0).toUpperCase() +
inputValue.substring(1);
if (capitalized !== inputValue) {
modelCtrl.$setViewValue(capitalized);
modelCtrl.$render();
}
return capitalized;
}
var model = $parse(attrs.ngModel);
modelCtrl.$parsers.push(capitalize);
capitalize(model(scope));
}
};
});
</script>
    </head>
    <body>
        <div>
            <input type="text" ng-model="name" capitalize-first>
        </div>
    </body>
</html>

Output

 

 

Example 3

In the third example we will create a directive that will define some extra “USD” to text on the blur event.

 

<!DOCTYPE html>
<html ng-app="app">
    <head>
        <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.9/angular.min.js"></script>
        <script>
var app = angular.module('app', []);
app.controller('currencyController', ['$scope', function (scope) {
scope.amount = 5;
}]).directive('srCurrency', ['$filter', function ($filter) {
return {
restrict: 'A',
require: 'ngModel',
link: function (scope, el, attrs, ngModel) {
function onChangeCurrency() {
ngModel.$setViewValue($filter('currency')(ngModel.$viewValue, 'USD$'));
ngModel.$render();
el.css('color', 'blue');
}
el.on('blur', function (e) {
scope.$apply(onChangeCurrency);
});
}
}
}]);
</script>
    </head>
    <body>
        <div ng-app='app' ng-controller="currencyController">
        Enter The Expense Amount :
            <input type="text" sr-currency ng-model='amount' />
        </div>
    </body>
</html>

Output

 

 

Example 4

Let us do a directive that will read the value from the scope object and show it in a tabular format.

 

<!DOCTYPE html>
<html ng-app="myApp">
    <head>
        <style type="text/css">
table {

color:#666;

text-shadow: 1px 1px 0px #fff;
background:#eaebec;
margin:20px;
border:#ccc 1px solid;
-moz-border-radius:3px;
-webkit-border-radius:3px;
border-radius:3px;
-moz-box-shadow: 0 1px 2px #d1d1d1;
-webkit-box-shadow: 0 1px 2px #d1d1d1;
box-shadow: 0 1px 2px #d1d1d1;
}
table th {
padding:21px 25px 22px 25px;
border-top:1px solid #fafafa;
border-bottom:1px solid #e0e0e0;
background: #ededed;
background: -webkit-gradient(linear, left top, left bottom, from(#ededed), to(#ebebeb));
background: -moz-linear-gradient(top, #ededed, #ebebeb);
}
table th:first-child {
text-align: left;
padding-left:20px;
}
table tr:first-child th:first-child {
-moz-border-radius-topleft:3px;
-webkit-border-top-left-radius:3px;
border-top-left-radius:3px;
}
table tr:first-child th:last-child {
-moz-border-radius-topright:3px;
-webkit-border-top-right-radius:3px;
border-top-right-radius:3px;
}
table tr {
text-align: center;
padding-left:20px;
}
table td:first-child {
text-align: left;
padding-left:20px;
border-left: 0;
}
table td {
padding:18px;
border-top: 1px solid #ffffff;
border-bottom:1px solid #e0e0e0;
border-left: 1px solid #e0e0e0;
background: #fafafa;
background: -webkit-gradient(linear, left top, left bottom, from(#fbfbfb), to(#fafafa));
background: -moz-linear-gradient(top, #fbfbfb, #fafafa);
}
table tr.even td {
background: #f6f6f6;
background: -webkit-gradient(linear, left top, left bottom, from(#f8f8f8), to(#f6f6f6));
background: -moz-linear-gradient(top, #f8f8f8, #f6f6f6);
}
table tr:last-child td {
border-bottom:0;
}
table tr:last-child td:first-child {
-moz-border-radius-bottomleft:3px;
-webkit-border-bottom-left-radius:3px;
border-bottom-left-radius:3px;
}
table tr:last-child td:last-child {
-moz-border-radius-bottomright:3px;
-webkit-border-bottom-right-radius:3px;
border-bottom-right-radius:3px;
}
table tr:hover td {
background: #f2f2f2;
background: -webkit-gradient(linear, left top, left bottom, from(#f2f2f2), to(#f0f0f0));
background: -moz-linear-gradient(top, #f2f2f2, #f0f0f0);
}
.odd {
color: red;
}
.even {
color: blue;
}
</style>
        <script src="scripts/angular.min.js"></script>
        <script>
var myapp = angular.module('myApp', [])
.controller('countryctrl', ['$scope', function ($scope) {
$scope.data = [{
id: 1,
name: 'India',
capital: 'New Delhi',
curreny:"INR"
}, {
id: 2,
name: 'USA',
capital: 'New York',
curreny: "USD"
}, {
id: 3,
name: 'China',
capital: ' Beijing ',
curreny: "Renminbi"
}, {
id: 4,
name: 'Japan',
capital: 'Tokyo',
curreny: "yen"
}, {
id: 5,
name: 'Korea',
capital: 'Seoul',
curreny: "Won "
}, {
id: 6,
name: 'Vietnam',
capital: 'Hanoi',
curreny: "dong"
}
];
}])
.directive('trRow', function () {
return {
template: '
            <tr>
                <td ng-bind="row.id"></td>
                <td>
                    <strong ng-bind="row.name"></strong>
                </td>
                <td ng-bind="row.capital"></td>
                <td ng-bind="row.curreny"></td>
            </tr>'
};
});
</script>
    </head>
    <body>
        <div ng-app="myApp">
            <table ng-controller="countryctrl">
                <thead style="color:red; ">
                    <th>Country Id</th>
                    <th>Country Name</th>
                    <th>Capital</th>
                    <th>Currency</th>
                </thead>
                <tbody>
                    <tr tr-row ng-repeat="row in data"></tr>
                </tbody>
            </table>
        </div>
    </body>
</html>

Output

 

 

These are some basic directive examples to start custom directives. In an application, if you observe, there can be many reusable UI components that we can make it a custom directive and make it usable across the team to use it.

In the next article I will return with more on custom directives. I hope you now have a understanding of custom directives. Thanks for reading!