[2.0] Drop `<template [ngIf]="">` syntax from docs & examples

[vicb]

While working on the NgIf API docs we first thought about documenting:

• <single-root *ngIf=exp>
• `<template [ngIf]=exp>

However this is confusing, we will drop the <template []> notation from the API docs - note that it will still be supported and there is no plan to remove the support.

The preferred way will be <ng-container *ngIf=exp><root1><root2></ng-container>

The <ng-container> tag is used to group nodes together and is not stamped out in the resulting DOM. It is not a directive but a special angular construct.

We think that this change will remove some confusion and hard to remember syntax.

Please ping me if you need additional info.

/cc @IgorMinar

[wardbell]

@vicb Can you point to where this appears in our docs and what we should be doing? As I recall, our only mention of <template [ngIf]="" is during our discussion of how Angular desugars <something *ngIf=""

In that discussion we have illustrative code. But that is in keeping with the explanation of how it works, not a recommendation.

<ng-container> is not yet documented in angular.io. Didn't know it existed. <ng-content> I knew about. How would we know about <ng-container> ? It's not in the API docs (as you say, it's a "special Angular construct", not a class). What is it for?

[vicb]

@wardbell sorry can't tell where this is used in the docs - done a quick search before submitting the issue and the only place I can remember is indeed the template desugaring.

What needs to be done is to convert <template> to <ng-container> in examples - template desugaring should probably be moved to some annexe.

How would we know about <ng-container> ?

My mistake - I thought I had created an issue here but I realized it was actually for NgProjectAs when I search the tracker before opening this one.

Sorry for that, we all have been very busy for the past weeks.

To come back top our tag: <ng-container> is a "logical" container. Childs nodes are rendered but the tag itself is not rendered:

<a>
<ng-container>
  <b>
</ng-container>
<c>

gets rendered as <a><b><c>

it was first introduce for i18n plurals: you want to be able to render ~"you have (no|one|x) messages" without adding extra markup around the counter. It was not possible before ng-container (you would have to add a <span> for ngSwitch to work here).

Then while working on the API docs we realized that using different syntaxes if you have multiple root nodes is very confusing:

<p *ngIf="enabled">wouhou</p>

<!-- vs -->

<template [ngIf]="enabled">
  <p>wouhou</p>
  <p>but why ??</p>
</template>

<!-- vs -->

<ng-container *ngIf="enabled">
  <p>wouhou</p>
  <p>neat !</p>
</ng-container>

Hope this all make sense, and sorry again for the lack of coordination/anticipation on this one

[wardbell]

@vicb At long last, I'm working on this in #3110