Understanding the transclude option of directive definition?

angularjs, angularjs-directive

Solution

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.

Problem

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?

Original source