Introduction to Transclusion of directives in AngularJS

This is an introduction to the transclusion part of directives in AngularJS. In order to make it more simpler, I have created one directive:

http://plnkr.co/edit/T2hh9d?p=preview

which uses couple of key use cases(mentioned below) of transclusion.

ng-transclude:  Rendering transcluded content. 
transcludeFn:   Constructor Function to modify the transcluded content with or without new scope.

By definition transclusion is the inclusion of document or part of the document into another document by reference.(From Wikipedia)

In case of AngularJS transclusion is used in similar fashion but we have more control on the transcluded content. If you are creating a directive which basically acts as an wrapper for it's child contents, and the content can be anything.Then transclusion should be your approach.

 Consider the below directive:

    

<org-v-card>

    <h4>{{firstName}} {{lastName}}</h4>

    <h5>Designation: {{jobtitle}}</h5>

    <h5>Company: {{company}}</h5>

    <h5>Phn no: {{phn}}</h5>

    <h5>Email: {{email}}</h5>

</org-v-card>

In the above example org-v-card is an user defined directive which acts as wrapper for it's child contents(one h4 and four h5 elements ).

Lets look into the template part  of the org-v-card directive.

<div class="vcard">
    Quick Info:<span ng-transclude></span>
</div>

In the above example to access all the child content(In this example one h4 and four h5 elements) and to render  it we are using <span ng-transclude></span>. The directive ng-transclude provided by AngularJS renders the child contents of the parent directive(In this example org-v-card).

Lets look into the controller:

var theApp = angular.module('myApp', []);

theApp.controller('myCtrl', function ($scope) {

  $scope.firstName = "Mike";
  $scope.lastName = "Logan";
  $scope.jobtitle = 'Consultant';
  $scope.company = 'BCA Corp.';
  $scope.phn = '080-22116677';
  $scope.email = 'mlogan@bca.com';
});


theApp.directive('orgVCard', ['$compile',
  function ($compile) {
    return {
      restrict: 'E',
      transclude: true,
      templateUrl: 'vcardtemplate.html',
      replace: true,
      link: function (scope, iele, attr, controller, transcludeFn) {
        /**        

         * Modify the  transcluded content with a new scope and return the cloned content        

       */     

   var modifyTranscludeContent = function (clonedelem, newscope) {

          newscope.firstName = "Jane";
          newscope.lastName = "King";
          newscope.jobtitle = 'Manager';
          newscope.company = 'BCA Corp.';
          newscope.phn = '080-22116678';
          newscope.email = 'jking@bca.com';
          clonedelem.scope = newscope;
          angular.element(clonedelem[0]).css('font-weight', 'bold')
            .css('color', 'red');
        };

        /**         

        * It shows the top most div        

        */        

        console.log(iele);
        /**         

         * Get the modified transcluded content      

         */        

        var transInstance = new transcludeFn(scope.$new(), modifyTranscludeContent;

        iele.append('Reports to:')
        /**         

         *Render the cloned content compiled with new scope values         

        */       

        iele.append(transInstance);


      }

    };

  }
]);

In the above script we are creating following scope variables:
 firstName, lastName, jobtitle, company, phn and email.

In the directive we are giving transclude:true, which means this directive can act as wrapper for it's child elements.

In the link function we are passing transcludeFn as an parameter, this function takes two parameters:

scope.$new: [Optional]A newly generated scope which is applicable only to the transcluded   content not to the directive.
modifyTranscludeContent:  This function(defined in the link function ) as defined above it accepts two parameters , clonedelement and the scope.

clonedelement :   The cloned element of the transcluded  content. Which  also get returned by the transcludeFn.
scope: The scope for the cloned elements.If no values  passed for this then the scope assigned to the directive will be considered as the value.

Inside  modifyTranscludeContent we are assigning different values to properties  of the scope passed to the  function  and assigning that scope to the clonedelement.

Consider the below line:

var transInstance = new transcludeFn(scope.$new(), modifyTranscludeContent);

transInstance is basically the cloned content after assigning the new scope to it. So now all the child content will render values which are assigned inside the transcludeFn.

In  the last line we are appending the cloned contents  to the parent directive.