John: If I were to put a directive here, and I said, "Transclude to true," then it would transclude the content inside of it, and yank that out, and put it to wherever I wanted to put it. Now, on the other hand, if you say, "Transclude element," you can actually get the entire element.
You'll see this happen with things like ngRepeat and ngIf, where ngRepeat takes the entire element, and clones it, and shows multiple copies of it, or ngIf, which removes the entire element and then brings it back when it's true and false.
For our example of transclude element, I'm going to take these two different templates that I've set up and I'm going to create a wrapWith directive, and basically I'm going to say, "wrapWith well," or, "wrapWith red," meaning that when I use this wrapWith...it's a very contrived example, but just bear with me. When I say, "wrapWith red," then take this whole thing and put it inside of this red template, or when I say, "wrapWith well," take this whole thing and put it inside of this well template.
I'll set up my directive just by saying, "Egghead directive," and then wrapWith, and I will return something that says, "Transclude element," and you can see right away, if I refresh here, that this disappears and there is a comment right here that says, "wrapWith well," meaning that it's put a placeholder there, saying, "This is our new element. I'm just waiting for you to put something back here at this comment level." If I were to log out this element in the linking function, it would say that it's a comment.
Anyway, for now, going to the linking function, we'll pass in the scope, and the element, and the attributes, and we're actually going to do a couple pretty advanced things here, so one is after the scope, and the element, and the attributes, there is a controller, and the last thing is the transclude function. This used to be in the compile phase. Now it's in the link phase. I'm not exactly sure which version that happened, but I think it's 1.2 and above.
I'm going to need the transclusion function to get the cloned element, and I'm also going to need the template cache to get my templates out of, so all these pieces will fit together really easily, so if I get the template cache, and I say, "Get from the attributes the wrapWith," and I just log this out as our template, so you can check this out real quick.
We'll say, "Template," and when I refresh here, you can see in my log that this is just that template, so I passed in well and it's just this template here. I'll actually have to create an Angular element out of this template so that we have an actual, let's call it a template element to work with, and then the funky stuff happens here, where I say, "Take the transclude, invoke it using the current scope," and we'll pass in a function that has the cloned element.
Now I just want to reiterate that if I were to try to access the element here, so if I log out the actual element right now, I would get a comment, not the cloned transcluded stuff, so in the cloned transcluded stuff, I log this out. Then you can see I have the form, which was my original thing that I yanked out. The entire element that I yanked out, I'm going to put back in.
From here, I'll just say, "Element after," so I say, "Add after that comment the template element," template element, and then I just want to append the clone, which is the form. If you're with me here, we've got the comment, "Add our template," which is adding the form.
From here, if I refresh, you can see that we have our final form in side of the well template, and if I were to switch this over to the red, that if I refresh here, now it just changes all the styles to red, and I could set up other templates to wrap this with.
Again, this transclude element scenario is not a very common scenario, but there are certain scenarios where you'd want to use it. Again, it's mainly used for ngRepeat, and ngIf, and things like that. This is kind of a contrived example, but I'm sure you could think of other things that you could use it for in your projects.