4

In the John Lindquist tutorial, transclusion is used to grab some content from the directive and put it in a desired place.

But the docs talk about translude function and passing it to controller and compile function. So, what is transclusion and how do I use it?

user1624400
  • 395
  • 4
  • 13

3 Answers3

16

When creating a basic directive, transclusion is easy:

module.directive( 'myTransDir', function () {
  return {
    transclude: true,
    scope: true,
    replace: true,
    template: '<div><h1>Hello!</h1><div ng-transclude></div></div>',
  };
});

Because the template includes the ngTransclude directive, it will automatically transclude the contents for me. If I use it like this:

<div my-trans-dir>
  <p>Some Content</p>
</div>

The resultant HTML will be:

<div>
  <h1>Hello!</h1>
  <div>
    <p>Some Content</p>
  </div>
</div>
Josh David Miller
  • 120,525
  • 16
  • 127
  • 95
  • @Lukas No, why? I'm not sure what you mean by "lingering". The template I included was self-contained, so I chose to just replace the dom element on which the directive was applied with the template, instead of including it *inside* that element. – Josh David Miller Jan 24 '13 at 22:30
  • 1
    Your answer is the correct way but it won't compile this way. You should assign a value to `replace` property or remove it completely. – Umur Kontacı Jan 25 '13 at 07:26
  • 1
    @Lukas and fastreload - Holy crap! It's amazing what we look at and still don't see. My apologies for the typo; it is fixed now. Thanks! – Josh David Miller Jan 25 '13 at 07:32
6

@Josh already covered ngTransclude. This is the "normal use case" for transclusion.

You were also asking about these statements in the documentation:

controller - Controller constructor function...
The controller is injectable with the following locals:
...
$transclude - A transclude linking function pre-bound to the correct transclusion scope: function(cloneLinkingFn).

and

The compile function deals with transforming the template DOM...
The compile function takes the following arguments.
...
transclude - A transclude linking function: function(scope, cloneLinkingFn).

I consider these esoteric use cases of transclusion. I've personally only seen one mention of these on stackoverflow, and I'll refer you there:
What exactly do you do with the transclude function and the clone linking function?

Quote from @blesh: "these two methods of transclusion are there to give you the ability to control everything about you transclusion via programmatic access to the process."

Update: I found a nice blog post about transclusion.

Community
  • 1
  • 1
Mark Rajcok
  • 362,217
  • 114
  • 495
  • 492
  • +1 This is good additional info, Mark. I've only ever had to use `$transclude` once, but he did ask. :-) – Josh David Miller Jan 24 '13 at 22:32
  • @Josh, please do share your one use case (if you can). – Mark Rajcok Jan 25 '13 at 02:56
  • It can be used, for example, to transclude on a directive with no template, or to transclude using a scope other than the parent. I used it for the former in angular-ui/bootstrap's tooltip plugin: [here](https://github.com/angular-ui/bootstrap/blob/master/src/tooltip/tooltip.js#L22), but I have an open [PR](https://github.com/angular-ui/bootstrap/pull/92) that removes it for something simpler. – Josh David Miller Jan 25 '13 at 03:03
2

Johns "Building Zippy" tutorial on egghead.io is the best description I have seen on transclusion. You are right with both statements, John just gives an example, but whats happening behind the scenes is the html in the markup is put through the compiler with the template. In his tutorial, John leaves content in the template on accident, and you can see how angular's compiler concatenates the markup html and the template html.

Ben Felda
  • 1,474
  • 10
  • 15