Document what is <ng-content> tag and how content projection works

[devoto13]

Searching for ng-content on https://angular.io/docs/ts/latest/ doesn't produce any useful results and if I'm not mistaken there is no any detailed description about what it is and how it works. There are quite some blog posts showing examples of using it. It creates a lot of confusion for users, see:

• Template transclusion is evaluated in wrong moment angular#13760
• use ng-content more than once angular#13894
• Transcluded components hooks works incorrectly with upper *ngIf state angular#13921
• ng-content and ViewEncapsulation.Emulated prevents styling in Child Component angular#12639
• Content lifecycle on conditional transclusion angular#13059

Points, which should probably be documented:

• projection just moves nodes from one place to another, which leads to following conclusions:
  • not possible to use projected content multiple times (link)
  • projected nodes/components, will be always created, even if you wrap them into *ngIf, e.g. <div *ngIf="false"><ng-content></ng-content></div>. It is reason for problems in Template transclusion is evaluated in wrong moment angular#13760 and Transcluded components hooks works incorrectly with upper *ngIf state angular#13921 (link)
  • when using ViewEncapsulation.Emulated (and probably Native as well?) projected nodes will have encapsulation of the place, where they were created and not where, they are projected
• how to query only subset of nodes using <ng-content select="<selector>">
  • document, that only top-level nodes can be selected by this approach
• document a recipe with template, Tobias referring here to created projected nodes only when they are needed

PS During work on this issue, it may be good idea to also improve documentation of projectableNodes as they are tied to functionality discussed here.

[artaommahe]

@devoto13 i think that <template>/TemplateRef/ngTemplateOutlet should be added to this section too. Their usage solved my issue with components instantiating with ng-content regardless real DOM state (angular/angular#13921)

[devoto13]

@artaommahe thanks for you addition. Things you mention are actually in the last item of the list. Probably should have wrote it more clear.

[ShadowManu]

bump?

[karptonite]

I agree that documentation on this would be useful, not just to make it easier to use, but to allow us to be confident that we aren't using an "undocumented feature" that could go away unexpectedly.

[Foxandxss]

it is coming it is coming. Sorry, we are preparing cool stuff for the ng-conf and that consumes our time. We will address this shortly

[MarcelHuang]

Has this been forgotten? "We will address this shortly." Though I'm not sure what's your definition of "shortly" but it seems to be at least 50 days.

[klinki]

I'm not sure about shortly, but eventually is more than 190 days (and I'm little bit suspicious if it doesn't mean never :( )

[Foxandxss]

In fact, we have. The problem is that we are migrating to a new site and all the changes are being made in there. We haven't update our live site in a while, that is true, because we are concentrating to this new site.

Sorry for the inconvenience.

[martinmcwhorter]

It looks like the new web site is up and running. Still cannot find any documentation on ngContent.

[Foxandxss]

What kind of documentation are you expecting?

[PadishahTJK]

just usual documentation with explanation end simple how to use and rest

[martinmcwhorter]

Content Projection could probably use its own section in the documentation. Anyone knew to angular may not even know this feature exists. If they do happen to find out about it, they will have to find documentation elsewhere.

…

On Mon, 3 Jul 2017, 11:32 PadishahTJK, ***@***.***> wrote: just usual documentation with explanation end simple how to use and rest — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#3099 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABI5-haPHNy-ockmUuDZghKzQSTnUL-8ks5sKMNBgaJpZM4LjpLg> .

[Foxandxss]

There are 3 guides talk mentions content projection as today.

DI in action, lifecycle hooks and ts to js.

We will see if we can put a better place for it.