chan-d / angular_custom_directives_lab

Custom & External Angular Directives

Directives are snippets of HTML with their own custom JavaScript logic. Angular's concept of directives helps separate concerns and duties of code while making your views DRY and logic-less. Angular directives are very modular and can be added, shared, and swapped between projects. Check out ng-modules to find popular Angular Directives to add to your projects.

Adding an External Directive

Sometimes when you're looking to solve a problem, you find that another developer has already made a solution in the form of a directive. Now the challenge is how to include that directive in your project.

1. Add the directive's file(s) to your project.
2. Include the file(s) in index.html.
3. Inject the directive into your app:

// app.js

angular.module('yourApp', ['ngResource', 'ngMap', 'pickadate', 'ui.bootstrap']);

Making Your Own Directive

A Current Weather Example

Follow Along by putting these code samples into an Angular project.

Reference: ng-newsletter blog post on directives

Imagine you wanted to make a box that displayed a city's current weather that was re-useable across pages for various cities. A directive would be a great solution! Let's look at how you'd build this directive that fetches a city's weather data and displays it on the page.

Place this HTML anywhere inside your Angular controller:

<!-- index.html -->

<current-weather city="San Francisco"></current-weather>

Add this directive to your app:

// app.js
angular.module('weatherApp', [])
  .directive('currentWeather', currentWeather);

function currentWeather() {
  vm = this;
  return {
    restrict: 'E',
    scope: {
      city: '@'
    },
    template: '<div class="current-weather"><h4>Weather for {{city}}</h4>{{weather.main.temp}}</div>',
    // templateUrl: 'templates/currentWeatherTemplate.html',
    // transclude: true,
    controller: ['$scope', '$http',
      function (vm, $http) {
        var url = "http://api.openweathermap.org/data/2.5/weather?mode=json&cnt=7&units=imperial&callback=JSON_CALLBACK&q=";
        // ask Justin for an API key or go to openweathermap.org to acquire your own!
        var apiKey = "&APPID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

        vm.getWeather = function(city) {
          $http({ method: 'JSONP', url: url + city + apiKey })
            .success(function(data) {
              vm.weather = data;
            });
        }
    }],
    link: function (vm, element, attrs) {
      vm.weather = vm.getWeather(attrs.city);
    }
  }
};

Angular Directive Options

Restrict

The first option in an Angular directive is the restrict option. This option lets you specify how exactly you'd like to call the directive in HTML. See the options below; A and E are the most popular.

'A' - <span data-ngsparkline></span>
'E' - <data-ng-sparkline></data-ng-sparkline>
'C' - <span class="ng-sparkline"></span>
'M' - <!-- directive: data-ngsparkline -->

template and templateUrl

Using the template and templateUrl options you can define an HTML template inside the directive's JS or in a separate HTML file in the templates folder.

Scope inside a Directive

But wait a sec, how do directives interact with the vm set by the local controller? Can I get data from the local controller into my directive?

By default, scopes do inherit the scope of their local controller just like they were HTML in the template. However, you can use the scope option to change this default behavior to isolate your directive's scope.

1. scope: true - If scope is set to true, then the directive will have its own child scope that inherits from the parent scope of the local controller, meaning it can still access and change the parent scope.

2. scope: {} - By passing an object to the scope option, you can define an isolated scope. Inside this object you can pass in three aliases indicating the expected datatype:

scope: {
  ngModel: '=',     // provides two-way binding
  onSend: '&',      // works with function calls
  fromName: '@'     // reads attribute value
}

<input type="text" data-ngmodel="recipient.email">
<!-- invoke the directive -->
<div scope-example data-ngmodel="recipient.email" on-send="sendMail()" from-name="[email protected]">

controller

The controller option allows you to define a controller specific and isolated to the directive.

link()

The link() option is the meat and potatoes of the directive. Inside this function, you specify what you'd like the directive to do, and you can update scope.