angularjs transclusion - When to use transclude 'true' and transclude 'element' in Angular?




component meaning (4)

From AngularJS Documentation on Directives:

transclude - compile the content of the element and make it available to the directive. Typically used with ngTransclude. The advantage of transclusion is that the linking function receives a transclusion function which is pre-bound to the correct scope. In a typical setup the widget creates an isolate scope, but the transclusion is not a child, but a sibling of the isolate scope. This makes it possible for the widget to have private state, and the transclusion to be bound to the parent (pre-isolate) scope.

true - transclude the content of the directive.

'element' - transclude the whole element including any directives defined at lower priority.

transclude: true

So let's say you have a directive called my-transclude-true declared with transclude: true that looks like this:

<div>
  <my-transclude-true>
    <span>{{ something }}</span>
    {{ otherThing }}
  </my-transclude-true>
</div>

After compiling and before linking this becomes:

<div>
  <my-transclude-true>
    <!-- transcluded -->
  </my-transclude-true>
</div>

The content (children) of my-transclude-true which is <span>{{ something }}</span> {{..., is transcluded and available to the directive.

transclude: 'element'

If you have a directive called my-transclude-element declared with transclude: 'element' that looks like this:

<div>
  <my-transclude-element>
    <span>{{ something }}</span>
    {{ otherThing }}
  </my-transclude-element>
</div>

After compiling and before linking this becomes:

<div>
   <!-- transcluded -->
</div>

Here, the whole element including its children are transcluded and made available to the directive.

What happens after linking?

That's up to your directive to do what it needs to do with the transclude function. ngRepeat uses transclude: 'element' so that it can repeat the whole element and its children when the scope changes. However, if you only need to replace the tag and want to retain it's contents, you can use transclude: true with the ngTransclude directive which does this for you.

When should I use transclude: 'true' and when transclude: 'element' ? I cant find anything about transclude: 'element' in the angular docs, they are pretty confusing.

I would be happy if someone could explain this in simple language. What is the benefit of each option? What is the real difference between them?

This is what I have found :

transclude: true

Inside a compile function, you can manipulate the DOM with the help of transclude linking function or you can insert the transcluded DOM into the template using ngTransclude directive on any HTML tag.

and

transclude: ‘element’

This transcludes the entire element and a transclude linking function is introduced in the compile function. You can not have access to scope here because the scope is not yet created. Compile function creates a link function for the directive which has access to scope and transcludeFn lets you touch the cloned element (which was transcluded) for DOM manipulation or make use of data bound to scope in it. For your information, this is used in ng-repeat and ng-switch.


The best way of think about transclusion is a Picture Frame.A picture frame has its own design and a space for adding the picture.We can decide what picture will go inside of it.

When it comes to angular we have some kind of controller with its scope and inside of that we will place a directive that supports transclusion. This directive will have it’s own display and functionality . In non-transluded directive, content inside the directive is decided by the directive itself but with transclusion,just like a picture frame,we can decide what will be inside the directive.

angular.module("app").directive('myFrame', function () {
    return {
        restrict: 'E',
        templateUrl:"frame.html",
        controller:function($scope){
          $scope.hidden=false;
          $scope.close=function(){
            $scope.hidden=true;

          }
        },
        transclude:true


    }

});

Content inside the directive

<div class="well" style="width:350px;" ng-hide="hidden">

  <div style="float:right;margin-top:-15px">
    <i class="glyphicon glyphicon-remove" ng-click="close()" style="cursor:pointer"></i> 
  </div>
  <div ng-transclude>
    /*frame content goes here*/
  </div>
</div>

Call Directive

<body ng-controller="appController">
    <my-frame>
      <span>My Frame content</span>
    </my-frame>
  </body>

Example


When set to true, the directive will delete the original content, but make it available for reinsertion within your template through a directive called ng-transclude.

appModule.directive('directiveName', function() {
    return {
      template: '<div>Hello there <span ng-transclude></span></div>',
      transclude: true
    };
});


<div directive-name>world</div>

browser render: “Hello there world.”


How to declare the various functions?

Compile, Controller, Pre-link & Post-link

If one is to use all four function, the directive will follow this form:

myApp.directive( 'myDirective', function () {
    return {
        restrict: 'EA',
        controller: function( $scope, $element, $attrs, $transclude ) {
            // Controller code goes here.
        },
        compile: function compile( tElement, tAttributes, transcludeFn ) {
            // Compile code goes here.
            return {
                pre: function preLink( scope, element, attributes, controller, transcludeFn ) {
                    // Pre-link code goes here
                },
                post: function postLink( scope, element, attributes, controller, transcludeFn ) {
                    // Post-link code goes here
                }
            };
        }
    };  
});

Notice that compile returns an object containing both the pre-link and post-link functions; in Angular lingo we say the compile function returns a template function.

Compile, Controller & Post-link

If pre-link isn't necessary, the compile function can simply return the post-link function instead of a definition object, like so:

myApp.directive( 'myDirective', function () {
    return {
        restrict: 'EA',
        controller: function( $scope, $element, $attrs, $transclude ) {
            // Controller code goes here.
        },
        compile: function compile( tElement, tAttributes, transcludeFn ) {
            // Compile code goes here.
            return function postLink( scope, element, attributes, controller, transcludeFn ) {
                    // Post-link code goes here                 
            };
        }
    };  
});

Sometimes, one wishes to add a compile method, after the (post) link method was defined. For this, one can use:

myApp.directive( 'myDirective', function () {
    return {
        restrict: 'EA',
        controller: function( $scope, $element, $attrs, $transclude ) {
            // Controller code goes here.
        },
        compile: function compile( tElement, tAttributes, transcludeFn ) {
            // Compile code goes here.

            return this.link;
        },
        link: function( scope, element, attributes, controller, transcludeFn ) {
            // Post-link code goes here
        }

    };  
});

Controller & Post-link

If no compile function is needed, one can skip its declaration altogether and provide the post-link function under the link property of the directive's configuration object:

myApp.directive( 'myDirective', function () {
    return {
        restrict: 'EA',
        controller: function( $scope, $element, $attrs, $transclude ) {
            // Controller code goes here.
        },
        link: function postLink( scope, element, attributes, controller, transcludeFn ) {
                // Post-link code goes here                 
        },          
    };  
});

No controller

In any of the examples above, one can simply remove the controller function if not needed. So for instance, if only post-link function is needed, one can use:

myApp.directive( 'myDirective', function () {
    return {
        restrict: 'EA',
        link: function postLink( scope, element, attributes, controller, transcludeFn ) {
                // Post-link code goes here                 
        },          
    };  
});




angularjs angularjs-directive angularjs-ng-transclude