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:

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.

It says transclude typically used with ngTransclude. But the sample from the doc of ngTransclude doesn't use ngTransclude directive at all.

I'd like some good examples to help me understand this. Why do we need it? What does it solve? How to use it?

Answer 1

Consider a directive called myDirective in an element, and that element is enclosing some other content, let's say:

<div my-directive>
    <button>some button</button>
    <a href="#">and a link</a>
</div>

If myDirective is using a template, you'll see that the content of <div my-directive> will be replaced by your directive template. So having:

app.directive('myDirective', function(){
    return{
        template: '<div class="something"> This is my directive content</div>'
    }
});

will result in this render:

<div class="something"> This is my directive content</div> 

Notice that the content of your original element <div my-directive> will be lost (or better said, replaced). So, say good-bye to these buddies:

<button>some button</button>
<a href="#">and a link</a>

So, what if you want to keep your <button>... and <a href>... in the DOM? You'll need something called transclusion. The concept is pretty simple: Include the content from one place into another. So now your directive will look something like this:

app.directive('myDirective', function(){
    return{
        transclude: true,
        template: '<div class="something"> This is my directive content</div> <ng-transclude></ng-transclude>'
    }
});

This would render:

<div class="something"> This is my directive content
    <button>some button</button>
    <a href="#">and a link</a>
</div>. 

In conclusion, you basically use transclude when you want to preserve the contents of an element when you're using a directive.

My code example is here. You could also benefit from watching this.