There are two separate features provided by the same API: Regular transclusion and Element transclusion.
For regular transclusion, the basic use case is: You want to include or replace some content from one template to another. There are two ways to do this using regular transclusion: the ngTransclude directive and the Transclusion Function.
The following is from Eric Greene that I thought was a good explanation for Regular transclusion with code, Understanding Transclusion.
ngTransclude
HTML Code
<div foo>
Some Content Here
</div>
JavaScript Code
.directive("foo", function() {
// returns the Directive Definition Object
return {
transclude: true,
template: "<div>the template</div><div ng-transclude></div>"
};
})
The result of the using the ngTransclude directive is the following HTML output.
HTML Code
<div foo>
<div>the template</div>
<div ng-transclude>Some Content Here</div>
</div>
Transclude Function
The second method to do transclusion is to use the transclude function
provided in the post-link function of a directive. In the code below,
the link property points to the post-link function. Unless a pre-link
function is specifically provided, all references to a link function
refer to the post-link function. Review the code below to see how the
same goal is achieved with a transclude function:
HTML Code
<div foo>
Some Content Here
</div>
JavaScript Code
.directive("foo", function() {
return {
template: "<div>the template</div>",
transclude: true,
link: function(scope, element, attrs, ctrl, transclude) {
transclude(function(clone) {
element.append(clone);
});
}
};
})
The transclude function is passed an argument that is a callback
function used to manipulate the cloned element. In the code above, the
callback function will receive the cloned content as a parameter, then
the function adds the cloned content to the DOM. The execution of the
of link function results in the following HTML output:
HTML Code
<div foo>
<div>
the template
<div>Some Content Here</div>
</div>
</div>
However, for Element transclusion, I would like to expand upon his answer because his explanation seemed confusing and incomplete for use cases. On Tero Parviainen’s blog “ A Guide to Transclusion in Angularjs” he gets to the root of the element transclusion, mainly to defer linking and attachment for some part of the UI.
To quote him:
Understanding Element Transclusion
Let's now turn our attention to an alternative way you can use
transclusion: Doing element transclusion with transclude: 'element'.
One use case for element transclusion is when you want to defer the
linking and attachment for some part of your UI until something
happens. Since element transclusion essentially removes part of the
DOM and makes it available for you to put back using the transclusion
function, you have control into when that happens.
For example, you
might want to only link and attach part of the DOM after some
condition on the parent scope becomes true: What we have here is
essentially a simplified version of ngIf. If you look at the source
code of ngIf, you should now be able to understand what it's doing:
It's using element transclusion to conditionally link this part of the
DOM only when the condition expression is true. This also explains why
you see HTML comments in your DOM tree whenever ngIf is used. They're
inserted by element transclusion.
This was something I would see in the Element tab in Chromes Dev Tools when viewing the source on a page, but didn’t understand where it was coming from. I’ve also see it with ng-repeat.
Repeated Rendering with Element Transclusion. Another use case for
element transclusion is if you want to link and attach part of the DOM
several times.
For example, you could have a directive that iterates
over an array and renders the DOM subtree again for each item in the
array, also making each item available on the scope. This can all be
done when we combine the element transclusion mechanism with the clone
attach function, because then we can link a new clone for the DOM for
each item: This is essentially a (hugely) simplified version of
ngRepeat. The built-in ngRepeatdirective also uses element
transclusion, though studying its source code is not quite as easy as
with ngIf because of the various ways you can use ngRepeatand all the
optimizations it contains. At the heart of it though, it's just an
application of element transclusion and the clone attach function.
I felt like Tero's coverage on the use of Transclusion by element was better than I could have said it.
