Understanding Directives

Generously reshared from AngularUI

This document is a (tangential) attempt to explain how AngularJS directives and the related compiling engine works so that you're not flailing around like a noodle the first time you try to tackle it yourself.

Injecting, Compiling, and Linking functions

When you create a directive, there are essentially up to 3 function layers for you to define1:

myApp.directive('uiJq', function InjectingFunction(){

  // === InjectingFunction === //
  // Logic is executed 0 or 1 times per app (depending on if directive is used).
  // Useful for bootstrap and global configuration

  return {
    compile: function CompilingFunction($templateElement, $templateAttributes) {

      // === CompilingFunction === //
      // Logic is executed once (1) for every instance of ui-jq in your original UNRENDERED template.
      // Scope is UNAVAILABLE as the templates are only being cached.
      // You CAN examine the DOM and cache information about what variables
      //   or expressions will be used, but you cannot yet figure out their values.
      // Angular is caching the templates, now is a good time to inject new angular templates 
      //   as children or future siblings to automatically run..

      return function LinkingFunction($scope, $linkElement, $linkAttributes) {

        // === LinkingFunction === //
        // Logic is executed once (1) for every RENDERED instance.
        // Once for each row in an ng-repeat when the row is created.
        // If ui-if or ng-switch may also affect if this is executed.
        // Scope IS available because controller logic has finished executing.
        // All variables and expression values can finally be determined.
        // Angular is rendering cached templates. It's too late to add templates for angular
        //  to automatically run. If you MUST inject new templates, you must $compile them manually.

      };
    }
  };
})

You can only access data in $scope inside the LinkingFunction. Since the template logic may remove or duplicate elements, you can only rely on the final DOM configuration in the LinkingFunction. You still cannot rely upon children or following-siblings since they have not been linked yet.

Deferred Execution

Even though you can evaluate variables and expressions by the time we hit our LinkingFunction, children DOM elements haven't been rendered yet. Sometimes jQuery plugins need to know the number and size of the DOM element's children (such as slideshows or layout managers like Isotope). To add support for these plugins, we may decide to delay the plugin's execution using $timeout or nested directives so that AngularJS can finish rendering the rest of the page.

This does NOT accomodate for async changes such as loading $scope data via AJAX

If you need to wait till your $scope data finishes loading try using ui-if.

$element === angular.element() === jQuery() === $()

To make working with the DOM easier, AngularJS contains a miniaturized version of jQuery called jqlite. This emulates some of the core features of jQuery using an almost identical API as jQuery. Any time you see an AngularJS DOM element, it will be the equivalent to a jQuery() wrapped DOM element.

You do NOT have to wrap AngularJS elements in jQuery()

If you are noticing that the full array of jQuery methods (or plugins) aren't available on an AngularJS element, it's because you either forgot to load the jQuery lib, or you forgot to load it BEFORE loading AngularJS. If AngularJS doesn't see jQuery already loaded by the time AngularJS loads, it will use it's own jqlite library instead.

$attributes.$observe()

If you have a sibling attribute that will contain {{}} then the attribute will need to be evaluated and could even change multiple times. Don't do this manually!

Instead use $attributes.$observe('myOtherAttribute', function(newValue)) exactly as you would have used $scope.$watch(). The only difference is the first argument is the attribute name (not an expression) and the callback function only has newValue (already evaluated for you). It will re-fire the callback every single time the evaluation changes too.

NOTE: This means that you can only access this attribute asynchronously

NOTE: If you want to reliably access the attribute pre-evaluation then you should do it in the CompileFunction

Footnotes

1. A transcluding function is actually a 4th layer, but this is not used by uiJq