I've always had a problem with transclusion. Though I've used it from time to time, using it always felt uncomfortable. I was never really sure what exactly the API was doing, or more importantly, what exactly I was supposed to do when using it.
Based on what I've heard, I'm not alone in this. Transclusion is one of those things people often mention when they talk about their difficulties with Angular.
What is it that makes this a difficult topic then? Conceptually we're not talking about anything hugely complicated - it's essentially just moving some DOM elements around. I think the bigger problems are tangential:
- The API is tricky, with its higher-order functions and "magic arguments".
- Parts of the API are deprecated, and it can be hard to figure out which parts.
- The documentation uses lots of big words ("a transclude linking function pre-bound to the correct transclusion scope").
- There are actually two separate features provided by the same API: Regular transclusion and element transclusion.
It wasn't until writing the transclusion chapter for my book that I felt I had fully grasped this topic. While the book covers the internals of the API, this article is an attempt to write the user guide I wish I'd had before. I want to describe what you can do with transclusion and how you can do it.