Understanding the transclude option of directive definition?

Question

I think this is one of the hardest concept for me to understand with angularjs\'s directive.

The document from http://docs.angularjs.org/guide/directive says:

<

Answer 1

The Updated AngularJS 1.6.6 documentation now has a better explanation.

Transclude is Used to Create a Directive that Wraps Other Elements

Sometimes it's desirable to be able to pass in an entire template rather than a string or an object. Let's say that we want to create a "dialog box" component. The dialog box should be able to wrap any arbitrary content.

To do this, we need to use the transclude option. Refer to the example below.

---

script.js

angular.module('docsTransclusionExample', [])
.controller('Controller', ['$scope', function($scope) {
  $scope.name = 'Tobias';
}])
.directive('myDialog', function() {
  return {
    restrict: 'E',
    transclude: true,
    scope: {},
    templateUrl: 'my-dialog.html',
    link: function(scope) {
      scope.name = 'Jeff';
    }
  };
});

index.html

  Check out the contents, {{name}}!

my-dialog.html

Compiled Output

  
Check out the contents, Tobias!

---

Transclude makes the contents of a directive with this option have access to the scope outside of the directive rather than inside.

This is illustrated in the previous example. Notice that we've added a link function in script.js that redefines name as Jeff. Ordinarily, we would expect that {{name}} would be Jeff. However, we see in this example that the {{name}} binding is still Tobias.

Best Practice: only use transclude: true when you want to create a directive that wraps arbitrary content.