Introduction to AngularJS Directives

What are directives, and why should you care about them?

Directives are regularly described as the ability to teach HTML new tricks, but what the heck does that mean?

Let’s imagine a scenario where a directive can be helpful.

You have a contact form on your site where your users can submit their email and hit send. The problem is, your backend is really slow to respond, so users become impatient and press “submit” multiple times, causing multiple requests to be made [and spamming your email!].

Wouldn’t it be nice if the submit button became disabled after the form was submitted, and then re-enabled after the request was finished?

In this tutorial we’ll be building a basic directive to handle this scenario.

Not only do we prevent double form submission, but we also provide some visual feedback to the user (changing “Save” to “Saving…”).

Now that we know what we’re building, let’s hop into it.

The HTML

<!-- Our Form Stuff -->
<form name="myForm">
  <input type="text" ng-model="newThing.content" placeholder="Type something...">
  <button ng-click="submitForm(newThing)" loading-text="Saving..." enable-button="myForm.$pristine" submit-button>
    Save
  </button>
<form>

I’ve removed all unneccessary css styles and markup so that we’re just looking at the code necessary for the directive. Full source is available here

<form name="myForm">: Form is not only a default HTML tag, but also a directive in AngularJS. By assigning a name to our form, we have access to myForm from within our controller’s $scope. This gives us access to certain methods and properties, such as $valid to check for validity.

<input>: let’s take a look at the input tag. Here we are binding the text field to newThing.content, which will assign it to $scope.newThing.content in our controller. This is the object that we will be submitting with our form.

<button>: now for the fun stuff, the button. There are a few things to explain here before diving into the JavaScript.

<button ng-click="submitForm(newThing)" loading-text="Saving..." enable-button="myForm.$pristine" submit-button>
  Save
</button>

Now that we have taken a look at the HTML markup needed for our form, let’s move on to the JavaScript…

The JavaScript

// Our ng-app and controller
app = angular.module('MyApp', []);

app.controller('MyCtrl', function($scope, $timeout) {
  $scope.listOfThings = [];
  $scope.newThing = {};

  $scope.submitForm = function(thing) {
    // Adding a timeout here to simulate
    // a very long request to backend.
    $timeout(function() {
       $scope.listOfThings.push(thing); // Add to listOfThings
       $scope.newThing = {}; // Reset newThing to empty object
       $scope.myForm.$setPristine(); // Reset the form so myForm.$pristine is true
    }, 1500);
  };
});

Here we are just creating the application called MyApp, and a basic controller. MyCtrl contains an array, listOfThings, and the submitForm() function that is called when pressing Save. I have added a 1.5 second timeout to simulate a slow response from a web server.

Our Directive: submitButton

app.directive('submitButton', function() {
  return {
    restrict: 'A',
    scope: {
      loadingText: "@",
      enableButton: "="
    },
    link: function ($scope, ele) {
      var defaultSaveText = ele.html();

      ele.bind('click', function(){
        ele.attr('disabled','disabled');
        ele.html($scope.loadingText);
      });

      $scope.$watch('enableButton', function() {
        ele.removeAttr('disabled');
        ele.html(defaultSaveText);
      });
    }
  };
});

app.directive('submitButton', function() {
  // ...
});

restrict: 'A',

scope: {
  loadingText: "@",
  enableButton: "="
},

link: function ($scope, ele){
  // ...
}

ele.bind('click', function(){
  ele.attr('disabled','disabled');
  ele.html($scope.loadingText);
});

var defaultSaveText = ele.html();
// ...
$scope.$watch('enableButton', function() {
  ele.removeAttr('disabled');
  ele.html(defaultSaveText);
});

That’s it! Hopefully this has given you an idea of how to contruct a basic directive. Directives can be used in many situations, and can really help to keep your code DRY.

If you’re looking for more in-depth information , please consult the official angular documentation. They have examples on the different capabilities of directives, such as using templates, custom DOM elements, and shared scopes.