Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

Commit f24b830

Browse files
wardbellwardbell
authored
docs(template-syntax/structural-directives): refresh both guides for style, accuracy, understanding (#3110)
Move details of structural directives from template-syntax to structural-directives guide Add <ng-container> to structural-directives Fix samples in both guides Touch up glossary Better conformance to google doc guidelines: we->you closes #2303, #2885
1 parent 390e280 commit f24b830

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+2774
-1332
lines changed

‎public/docs/_examples/ngcontainer/ts/example-config.json

Whitespace-only changes.

‎public/docs/_examples/ngcontainer/ts/plnkr.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"description": "<ng-container>",
3+
"basePath": "src/",
4+
"files": [
5+
"!**/*.d.ts",
6+
"!**/*.js"
7+
],
8+
"tags": [
9+
"ngcontainer", "structural", "directives"
10+
]
11+
}

‎public/docs/_examples/ngcontainer/ts/src/app/app.component.css

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
/* #docregion */
2+
button {
3+
min-width: 100px;
4+
font-size: 100%;
5+
}
6+
7+
code, .code {
8+
background-color: #eee;
9+
color: black;
10+
font-family: Courier, sans-serif;
11+
font-size: 85%;
12+
}
13+
14+
div.code {
15+
width: 400px;
16+
}
17+
18+
.heroic {
19+
font-size: 150%;
20+
font-weight: bold;
21+
}
22+
23+
hr {
24+
margin: 40px 0
25+
}
26+
27+
td, th {
28+
text-align: left;
29+
vertical-align: top;
30+
}
31+
32+
/* #docregion p-span */
33+
p span { color: red; font-size: 70%; }
34+
/* #enddocregion p-span */

‎public/docs/_examples/ngcontainer/ts/src/app/app.component.html

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
<!-- #docplaster -->
2+
<!-- #docregion -->
3+
<h1>&lt;ng-container&gt;</h1>
4+
5+
<!-- #docregion ngif -->
6+
<div *ngIf="hero">{{hero.name}}</div>
7+
<!-- #enddocregion ngif -->
8+
9+
<hr>
10+
11+
<h3>&lt;ng-container&gt; and CSS</h3>
12+
<p>Examples demonstrating issues with rigid CSS styles.</p>
13+
14+
<button (click)="hero = hero ? null : heroes[0]">Toggle hero</button>
15+
16+
<h4>#1 &lt;ng-container&gt; and &lt;p&gt;</h4>
17+
<!-- #docregion ngif-ngcontainer -->
18+
<p>
19+
I turned the corner
20+
<ng-container *ngIf="hero">
21+
and saw {{hero.name}}. I waved
22+
</ng-container>
23+
and continued on my way.
24+
</p>
25+
<!-- #enddocregion ngif-ngcontainer -->
26+
<!-- #docregion ngif-span -->
27+
<p>
28+
I turned the corner
29+
<span *ngIf="hero">
30+
and saw {{hero.name}}. I waved
31+
</span>
32+
and continued on my way.
33+
</p>
34+
<!-- #enddocregion ngif-span -->
35+
36+
<h4>#2 &lt;ng-container&gt; and &lt;p&gt;</h4>
37+
38+
<div *ngIf="hero">
39+
<!-- #docregion ngif-ngcontainer-2 -->
40+
<p>
41+
{{hero.name}} is
42+
<ng-container *ngFor="let trait of heroTraits; let first=first; let last=last">
43+
<ng-container *ngIf="!first">,</ng-container>
44+
<ng-container *ngIf="last">and</ng-container>
45+
{{trait}}
46+
</ng-container>.
47+
</p>
48+
<!-- #enddocregion ngif-ngcontainer-2 -->
49+
50+
<!-- #docregion ngif-span-2 -->
51+
<p>
52+
{{hero.name}} is
53+
<span *ngFor="let trait of heroTraits; let first=first; let last=last">
54+
<span *ngIf="!first">,</span>
55+
<span *ngIf="last">and</span>
56+
{{trait}}
57+
</span>.
58+
</p>
59+
<!-- #enddocregion ngif-span-2 -->
60+
61+
<br>
62+
63+
<h4>#3 &lt;ng-container&gt; and &lt;p&gt;</h4>
64+
<!-- #docregion ngif-span-3 -->
65+
<p>
66+
<label><input type="checkbox" [checked]="showId" (change)="showId=!showId">Show ID</label>
67+
</p>
68+
<!-- #enddocregion ngif-span-3 -->
69+
70+
<div>
71+
The <code>hero.id</code> in the &lt;span&gt;
72+
is caught by the <span>p-span</span> CSS:
73+
<!-- #docregion ngif-span-3 -->
74+
<p>
75+
<span *ngIf="showId">
76+
Id: ({{hero.id}})
77+
</span>
78+
Name: {{hero.name}}
79+
</p>
80+
<!-- #enddocregion ngif-span-3 -->
81+
</div>
82+
83+
<div>
84+
The <code>hero.id</code> in the &lt;ng-container&gt;
85+
is unaffected by the <span>p-span</span> CSS:
86+
<p>
87+
<ng-container *ngIf="showId">
88+
Id: ({{hero.id}})
89+
</ng-container>
90+
Name: {{hero.name}}
91+
</p>
92+
</div>
93+
94+
<div>
95+
The <code>hero.id</code> in the &lt;template *ngIf&gt; disappears:
96+
<p>
97+
<template *ngIf="showId">
98+
Id: ({{hero.id}})
99+
</template>
100+
Name: {{hero.name}}
101+
</p>
102+
</div>
103+
104+
<div>
105+
The <code>hero.id</code> in the &lt;template [ngIf]&gt;
106+
is unaffected by the <span>p-span</span> CSS:
107+
<p>
108+
<template [ngIf]="showId">
109+
Id: ({{hero.id}})
110+
</template>
111+
Name: {{hero.name}}
112+
</p>
113+
</div>
114+
115+
</div>
116+
117+
<hr>
118+
119+
<h3>&lt;ng-container&gt; and layout-sensitive elements</h3>
120+
<p>
121+
Examples demonstrating issues with layout-sensitive elements
122+
such as &lt;select&gt; and &lt;table&gt;.
123+
</p>
124+
125+
<h4>#1 &lt;ng-container&gt; and &lt;options&gt;</h4>
126+
127+
<p><i>&lt;select&gt; with &lt;span&gt;</i></p>
128+
<div>
129+
Pick your favorite hero
130+
(<label><input type="checkbox" checked (change)="showSad=!showSad">show sad</label>)
131+
</div>
132+
<!-- #docregion select-span -->
133+
<select [(ngModel)]="hero">
134+
<span *ngFor="let h of heroes">
135+
<span *ngIf="showSad || h?.emotion != 'sad'">
136+
<option [ngValue]="h">{{h.name}} ({{h?.emotion}})</option>
137+
</span>
138+
</span>
139+
</select>
140+
<!-- #enddocregion select-span -->
141+
142+
<p><i>&lt;select&gt; with &lt;ng-container&gt;</i></p>
143+
<div>
144+
Pick your favorite hero
145+
(<label><input type="checkbox" checked (change)="showSad=!showSad">show sad</label>)
146+
</div>
147+
<!-- #docregion select-ngcontainer -->
148+
<select [(ngModel)]="hero">
149+
<ng-container *ngFor="let h of heroes">
150+
<ng-container *ngIf="showSad || h?.emotion != 'sad'">
151+
<option [ngValue]="h">{{h.name}} ({{h?.emotion}})</option>
152+
</ng-container>
153+
</ng-container>
154+
</select>
155+
<!-- #enddocregion select-ngcontainer -->
156+
157+
<br><br><br><br>
158+
159+
<h4>#2 &lt;ng-container&gt; and &lt;options&gt;</h4>
160+
<p>
161+
<label (change)="traitPicker.value=showDefaultTraits ? 'loyal' : heroTraits[0]">
162+
<input type="checkbox"
163+
[checked]="showDefaultTraits"
164+
(change)="showDefaultTraits=!showDefaultTraits">Show default traits
165+
</label>
166+
</p>
167+
168+
<p>Options with &lt;ng-container&gt;</p>
169+
170+
<select #traitPicker>
171+
<!-- #docregion select-ngcontainer-2 -->
172+
<ng-container *ngIf="showDefaultTraits">
173+
<!-- Default traits -->
174+
<option value="loyal">LOYAL</option>
175+
<option value="clean">CLEAN</option>
176+
<option value="reverent">REVERENT</option>
177+
</ng-container>
178+
<option *ngFor="let trait of heroTraits" [value]="trait">
179+
{{ trait | uppercase }}
180+
</option>
181+
<!-- #enddocregion select-ngcontainer-2 -->
182+
</select>
183+
184+
185+
<p>Options with &lt;span&gt;</p>
186+
<!-- #docregion select-span-2 -->
187+
<select>
188+
<!-- Default traits are always excluded because intermediate <span> is illegal -->
189+
<span *ngIf="showDefaultTraits">
190+
<option value="loyal">LOYAL</option>
191+
<option value="clean">CLEAN</option>
192+
<option value="reverent">REVERENT</option>
193+
</span>
194+
<option *ngFor="let trait of heroTraits" [value]="trait">
195+
{{ trait | uppercase }}
196+
</option>
197+
</select>
198+
<!-- #enddocregion select-span-2 -->
199+
200+
<br>
201+
202+
<h4>&lt;ng-container&gt; and &lt;table&gt;</h4>
203+
<p>
204+
<label><input type="checkbox" checked (change)="attrDirs=!attrDirs">Attribute directives</label>
205+
<label><input type="checkbox" checked (change)="strucDirs=!strucDirs">Structural directives</label>
206+
<label><input type="checkbox" (change)="divNgIf=!divNgIf">div with *ngIf</label>
207+
</p>
208+
209+
<table>
210+
<tr>
211+
<th width="20%">Directive</th>
212+
<th width="10%">Type</th>
213+
<th>Description</th>
214+
</tr>
215+
216+
<tr *ngIf="attrDirs">
217+
<td>NgClass</td><td>A</td><td>Add or remove multiple CSS classes.</td>
218+
</tr>
219+
220+
<ng-container *ngIf="divNgIf">
221+
<!-- #docregion ngif-div -->
222+
<div *ngIf="strucDirs">
223+
<tr>
224+
<td>xxx</td><td>S</td><td>div with *ngIf formats crazy.</td>
225+
</tr>
226+
<tr>
227+
<td>yyy</td><td>S</td><td>div with *ngIf formats crazy.</td>
228+
</tr>
229+
</div>
230+
<!-- #enddocregion ngif-div -->
231+
</ng-container>
232+
233+
<!-- #docregion ngif-ngcontainer-4 -->
234+
<ng-container *ngIf="strucDirs">
235+
<tr>
236+
<td>NgFor</td><td>S</td><td>Repeat the template for each item in a list.</td>
237+
</tr>
238+
<tr>
239+
<td>NgIf</td><td>S</td><td>Add or remove DOM elements.</td>
240+
</tr>
241+
</ng-container>
242+
<!-- #enddocregion ngif-ngcontainer-4 -->
243+
244+
<ng-container *ngIf="attrDirs">
245+
<tr>
246+
<td>NgStyle</td><td>A</td><td>Add or remove multiple style attributes.</td>
247+
</tr>
248+
</ng-container>
249+
250+
<!-- #docregion ngif-tr -->
251+
<tr *ngIf="strucDirs">
252+
<td>NgSwitch</td><td>S</td><td>Include in DOM if case matches the switch value.</td>
253+
</tr>
254+
<!-- #enddocregion ngif-tr -->
255+
256+
</table>
257+
258+
<hr>
259+
260+
<h3>Do not confuse &lt;ng-container&gt; with &lt;ng-content&gt;</h3>
261+
262+
<p>&lt;ng-container&gt;Inside ng-container&lt;/ng-container&gt;</p>
263+
<!-- #docregion ngcontainer-bare -->
264+
<ng-container>Inside ng-container</ng-container>
265+
<!-- #enddocregion ngcontainer-bare -->
266+
267+
<p>&lt;ng-content&gt;this is an Angular parse error&lt;/ng-content&gt;</p>
268+
<!-- #docregion ngcontent-bad -->
269+
<!-- <ng-content>this is an Angular parse error</ng-content> -->
270+
<!-- #enddocregion ngcontent-bad -->
271+
<div class="code">Template parse errors:<br>
272+
&lt;ng-content&gt; element cannot have content.</div>
273+
274+
<p>Demo of &lt;/ng-content&gt;</p>
275+
<!-- #docregion content-comp -->
276+
<content-comp>
277+
Projected content
278+
</content-comp>
279+
<!-- #enddocregion content-comp -->

‎public/docs/_examples/ngcontainer/ts/src/app/app.component.ts

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// #docregion
2+
import { Component } from '@angular/core';
3+
4+
import { heroes } from './hero';
5+
6+
@Component({
7+
moduleId: module.id,
8+
selector: 'my-app',
9+
templateUrl: './app.component.html',
10+
styleUrls: [ './app.component.css' ]
11+
})
12+
export class AppComponent {
13+
heroes = heroes;
14+
hero = this.heroes[0];
15+
heroTraits = [ 'honest', 'brave', 'considerate' ];
16+
17+
// flags for the table
18+
attrDirs = true;
19+
strucDirs = true;
20+
divNgIf = false;
21+
22+
showId = true;
23+
showDefaultTraits = true;
24+
showSad = true;
25+
}

‎public/docs/_examples/ngcontainer/ts/src/app/app.module.ts

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// #docregion
2+
import { NgModule } from '@angular/core';
3+
import { FormsModule } from '@angular/forms';
4+
import { BrowserModule } from '@angular/platform-browser';
5+
6+
import { AppComponent } from './app.component';
7+
import { ContentComponent } from './content.component';
8+
import { heroComponents } from './hero.components';
9+
10+
@NgModule({
11+
imports: [ BrowserModule, FormsModule ],
12+
declarations: [
13+
AppComponent,
14+
ContentComponent,
15+
heroComponents
16+
],
17+
bootstrap: [ AppComponent ]
18+
})
19+
export class AppModule { }

‎public/docs/_examples/ngcontainer/ts/src/app/content.component.ts

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// #docregion
2+
import { Component } from '@angular/core';
3+
4+
@Component({
5+
selector: 'content-comp',
6+
// #docregion template
7+
template:
8+
`<div>
9+
<ng-content></ng-content>
10+
</div>`,
11+
// #enddocregion template
12+
styles: [ `
13+
div { border: medium dashed green; padding: 1em; width: 150px; text-align: center}
14+
`]
15+
})
16+
export class ContentComponent { }

0 commit comments

Comments
 (0)