Demystifying Transclusion

Wait, Trans .. what? Yes, Transclusion is the mysterious, big and most intimidating of words when writing AngularJS Components. AngularJS, being so powerful and all provides a lot of ways to do many things.

Now writing directives is not a very complex exercise, infact it is quite simple now if you first have a look at the improving(sort of) documentation. But when writing directives in order to create Re-usable components, then we have to consider a lot of stuff for functionality and customization for our component to be successful. And nothing says customizable when the user can use his own markup inside our component.

So what is it exactly

In simple words transclusion is the ability to wrap user’s markup by our own template(markup). Lets say we are creating some component in which the user can hack in his own markup with his own scope variables and values. The markup they provide will co-exist in the component we wrote!

Confused, lets consider an example:

[js]
return {
restrict: "E",
templateUrl: "template.html",
transclude: true,
scope: {}, //lets have some isolation
link: function(scope, attrs) {
scope.favoriteCharacter = "Tyrion Lannister;
}
}
[/js]

and our template.html looks like this:

[js]
<div>
<div ng-transclude> This will be replaced by user markup </div>
<div class="my-own-component"> {{favoriteCharacter}} is awesome.</div>
</div>
[/js]

and we’ll be using it like this:

[js]
<game-of-thrones>
<!–
This following markup will replace the div with
ng-transclude directive
–>
<div>What’s you problem Oberion?, {{oberion}} </div>
</game-of-thrones>
[/js]

In the above snippets the two important things to notice are transclude: true in our directive and ng-transclude in our template markup.

The transclude option in our directive tells angular that this directive will be using transclusion (As per the docs you should really use this option when you require transclusion capabilities), the second part in the template markup tells the directive that this part is to be replaced.
Simple huh! 😉

But, what about scope?

Since its AngularJS it really isn’t complete without scope talks. Transclusion does some trickery with the scope.

You must have noticed that we really don’t have any oberion in our directive scope, so how will this work. Well scope with transclusion works a bit differently because since end user’s markup is embedded it would require the context of the user’s scope tree and not the isolated scope of our directive.

Thus the transcluded element does not refer to the scope of our directive, as if it didn’t exist. It would always refer to the scope in which the directive is used.

Thus even though oberion is not in our isolated scope, it wouldn’t matter because it will always be picked from outer context. Template markup other than the transcluded section will continue to use the isolated scope.

so if the user’s end looks like this:

[js]
// The Controller
// …
$scope.oberion = "The mountain makes my head explode";
$scope.favoriteCharacter = "Khaleesi";
// …

//The markup
<game-of-thrones>
<!–
This following markup will replace the div with
ng-transclude directive
–>
<div>What’s you problem Oberion?, {{oberion}} </div>
</game-of-thrones>
// …

// Final rendered markup
<game-of-thrones>
<div>What’s you problem Oberion?, The mountain makes my head explode.</div>
<div class="my-own-component"> Tyrion Lannister is awesome.</div>
</game-of-thrones>

[/js]

The above is a very simple way to understand transclusion, The basics are really easy to grasp and implement even though the term sounds very complicated and scientific.

Hope you enjoyed this little look at Transclusion in AngularJS.

Happy Transcluding 🙂