Directive templating

Directives will frequently load HTML templates from outside their definition. When using them in an application, you will need to understand how to properly manage them, how they interact (if at all) with the directive's parent scope, and how they interact with the content nested inside them.

Getting ready

Suppose that you begin with the following skeleton application:

(index.html - uncompiled)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <my-directive>
      Stuff inside
    </my-directive>
  </div>
</div>

(app.js)

angular.module('myApp', [])
.controller('MainCtrl', function ($scope) {
  $scope.overwrite = false;
  $scope.origin = 'parent controller';
});

How to do it…

Introduce a template to the directive as follows:

(index.html – uncompiled)

<div ng-app="myApp">
  <div ng-controller="MainCtrl">
    <my-directive>
      Stuff inside
    </my-directive>
  </div>
  
  <script type="text/ng-template" id="my-directive.html">
    <div>
      <p>Directive template</p>
      <p>Scope from {{origin}}</p>
      <p>Overwritten? {{overwrite}}</p>
    </div>
  </script>
</div>

(app.js)

angular.module('myApp', [])
.controller('MainCtrl', function ($scope) {
  $scope.overwrite = false;
  $scope.origin = 'parent controller';
})
.directive('myDirective', function() {
  return {
    restrict: 'E',
    replace: true,
    templateUrl: 'my-directive.html',
    link: function (scope) {
      scope.overwrite = !!scope.origin;
      scope.origin = 'link function';
    }
  };
});

This snippet will compile the directive element into the following:

(index.html – compiled)

<div>
  <p>Directive template</p>
  <p>Scope from link function</p>
  <p>Overwritten? true</p>
</div>

Tip

JSFiddle: http://jsfiddle.net/msfrisbie/cojb59b1/

How it works…

The parent scope from MainCtrl is inherited by the directive and is provided as the scope parameter inside the directive's link function. The directive template is inserted to replace the <my-directive> tag and its contents, but the supplanting template HTML is still subject to the inherited scope. The link function is able to modify the parent scope as though it were the directive's own. In other words, the link scope and the controller scope are the same object in this example.

See also

• The Directive scope inheritance recipe goes over the basics that involve carrying the parent scope through a directive
• The Isolate scope recipe gives details on how a directive can be decoupled from its parent scope
• The Directive transclusion recipe demonstrates how a directive handles the application of a scope to the interpolated existing nested content