Skip to content

Commit 71921e8

Browse files
kapunahelewongzarend
kapunahelewong
authored and
zarend
committed
docs: rewrite structural-directives.md (#40015)
PR Close #40015
1 parent 3f90336 commit 71921e8

File tree

16 files changed

+161
-782
lines changed

16 files changed

+161
-782
lines changed

‎aio/content/examples/structural-directives/src/app/app.component.css‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,7 @@ td, th {
4242
vertical-align: top;
4343
}
4444

45-
/* #docregion p-span */
4645
p span { color: red; font-size: 70%; }
47-
/* #enddocregion p-span */
4846

4947
.unless {
5048
border: 2px solid;

‎aio/content/examples/structural-directives/src/app/app.component.html‎

Lines changed: 7 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,27 +5,21 @@ <h1>Structural Directives</h1>
55
<p>Conditional display of hero</p>
66

77
<blockquote>
8-
<!-- #docregion built-in, asterisk, ngif -->
8+
<!-- #docregion asterisk -->
99
<div *ngIf="hero" class="name">{{hero.name}}</div>
10-
<!-- #enddocregion built-in, asterisk, ngif -->
10+
<!-- #enddocregion asterisk -->
1111
</blockquote>
1212

1313
<p>List of heroes</p>
14-
<!-- #docregion built-in -->
1514

1615
<ul>
17-
<!-- #docregion ngfor-li -->
1816
<li *ngFor="let hero of heroes">{{hero.name}}</li>
19-
<!-- #enddocregion ngfor-li -->
2017
</ul>
2118

22-
<!-- #enddocregion built-in -->
23-
2419
<hr>
2520

2621
<h2 id="ngIf">NgIf</h2>
2722

28-
<!-- #docregion ngif-true -->
2923
<p *ngIf="true">
3024
Expression is true and ngIf is true.
3125
This paragraph is in the DOM.
@@ -34,9 +28,7 @@ <h2 id="ngIf">NgIf</h2>
3428
Expression is false and ngIf is false.
3529
This paragraph is not in the DOM.
3630
</p>
37-
<!-- #enddocregion ngif-true -->
3831

39-
<!-- #docregion display-none -->
4032
<p [style.display]="'block'">
4133
Expression sets display to "block".
4234
This paragraph is visible.
@@ -45,7 +37,6 @@ <h2 id="ngIf">NgIf</h2>
4537
Expression sets display to "none".
4638
This paragraph is hidden but still in the DOM.
4739
</p>
48-
<!-- #enddocregion display-none -->
4940

5041
<h4>NgIf with template</h4>
5142
<p>&lt;ng-template&gt; element</p>
@@ -72,18 +63,17 @@ <h4>*ngIf with a &lt;ng-container&gt;</h4>
7263
and continued on my way.
7364
</p>
7465
<!-- #enddocregion ngif-ngcontainer -->
75-
<!-- #docregion ngif-span -->
66+
7667
<p>
7768
I turned the corner
7869
<span *ngIf="hero">
7970
and saw {{hero.name}}. I waved
8071
</span>
8172
and continued on my way.
8273
</p>
83-
<!-- #enddocregion ngif-span -->
8474

8575
<p><i>&lt;select&gt; with &lt;span&gt;</i></p>
86-
<!-- #docregion select-span -->
76+
8777
<div>
8878
Pick your favorite hero
8979
(<label><input type="checkbox" checked (change)="showSad = !showSad">show sad</label>)
@@ -95,7 +85,6 @@ <h4>*ngIf with a &lt;ng-container&gt;</h4>
9585
</span>
9686
</span>
9787
</select>
98-
<!-- #enddocregion select-span -->
9988

10089
<p><i>&lt;select&gt; with &lt;ng-container&gt;</i></p>
10190
<!-- #docregion select-ngcontainer -->
@@ -148,17 +137,14 @@ <h2 id="ngSwitch">NgSwitch</h2>
148137

149138
<h4>NgSwitch</h4>
150139

151-
<!-- #docregion built-in , ngswitch -->
152140
<div [ngSwitch]="hero?.emotion">
153141
<app-happy-hero *ngSwitchCase="'happy'" [hero]="hero"></app-happy-hero>
154142
<app-sad-hero *ngSwitchCase="'sad'" [hero]="hero"></app-sad-hero>
155143
<app-confused-hero *ngSwitchCase="'confused'" [hero]="hero"></app-confused-hero>
156144
<app-unknown-hero *ngSwitchDefault [hero]="hero"></app-unknown-hero>
157145
</div>
158-
<!-- #enddocregion built-in, ngswitch -->
159146

160147
<h4>NgSwitch with &lt;ng-template&gt;</h4>
161-
<!-- #docregion ngswitch-template -->
162148
<div [ngSwitch]="hero?.emotion">
163149
<ng-template [ngSwitchCase]="'happy'">
164150
<app-happy-hero [hero]="hero"></app-happy-hero>
@@ -173,7 +159,6 @@ <h4>NgSwitch with &lt;ng-template&gt;</h4>
173159
<app-unknown-hero [hero]="hero"></app-unknown-hero>
174160
</ng-template>
175161
</div>
176-
<!-- #enddocregion ngswitch-template -->
177162

178163
<hr>
179164

@@ -189,6 +174,7 @@ <h2>&lt;ng-template&gt;</h2>
189174
<hr>
190175

191176
<h2 id="appUnless">UnlessDirective</h2>
177+
<!-- #docregion toggle-info -->
192178
<p>
193179
The condition is currently
194180
<span [ngClass]="{ 'a': !condition, 'b': condition, 'unless': true }">{{condition}}</span>.
@@ -198,6 +184,8 @@ <h2 id="appUnless">UnlessDirective</h2>
198184
Toggle condition to {{condition ? 'false' : 'true'}}
199185
</button>
200186
</p>
187+
<!-- #enddocregion toggle-info -->
188+
201189
<!-- #docregion appUnless-->
202190
<p *appUnless="condition" class="unless a">
203191
(A) This paragraph is displayed because the condition is false.

‎aio/content/examples/structural-directives/src/app/app.component.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,9 @@ import { Hero, heroes } from './hero';
1010
export class AppComponent {
1111
heroes = heroes;
1212
hero = this.heroes[0];
13-
13+
// #docregion condition
1414
condition = false;
15+
// #enddocregion condition
1516
logs: string[] = [];
1617
showSad = true;
1718
status = 'ready';

‎aio/content/guide/ajs-quick-reference.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ The following table lists some of the key AngularJS template features with their
140140

141141
Angular has true template input variables that are explicitly defined using the `let` keyword.
142142

143-
For more information, see the [Template input variables](guide/structural-directives#template-input-variable) section of [Structural Directives](guide/structural-directives).
143+
For more information, see the [Structural directive shorthand](guide/structural-directives#shorthand) section of [Structural Directives](guide/structural-directives).
144144
</td>
145145

146146
</tr>

‎aio/content/guide/architecture-components.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -166,8 +166,8 @@ The example template uses two built-in structural directives to add application
166166

167167
<code-example path="architecture/src/app/hero-list.component.1.html" header="src/app/hero-list.component.html (structural)" region="structural"></code-example>
168168

169-
* [`*ngFor`](guide/structural-directives#inside-ngfor) is an iterative; it tells Angular to stamp out one `<li>` per hero in the `heroes` list.
170-
* [`*ngIf`](guide/structural-directives#ngif-case-study) is a conditional; it includes the `HeroDetail` component only if a selected hero exists.
169+
* [`*ngFor`](guide/built-in-directives#ngFor) is an iterative; it tells Angular to stamp out one `<li>` per hero in the `heroes` list.
170+
* [`*ngIf`](guide/built-in-directives#ngIf) is a conditional; it includes the `HeroDetail` component only if a selected hero exists.
171171

172172
#### Attribute directives
173173

‎aio/content/guide/built-in-directives.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ The string `"let item of items"` instructs Angular to do the following:
198198
* Translate `"let item of items"` into an `<ng-template>` around the host element
199199
* Repeat the `<ng-template>` for each `item` in the list
200200

201-
For more information see the [`<ng-template>` section](guide/structural-directives#the-ng-template) of [Structural directives](guide/structural-directives).
201+
For more information see the [Structural directive shorthand](guide/structural-directives#shorthand) section of [Structural directives](guide/structural-directives).
202202
### Repeating a component view
203203

204204
To repeat a component element, apply `*ngFor` to the selector.
@@ -215,7 +215,7 @@ The following example references `item` first in an interpolation and then passe
215215

216216
<code-example path="built-in-directives/src/app/app.component.html" region="NgFor-1-2" header="src/app/app.component.html"></code-example>
217217

218-
For more information about template input variables, see [Structural Directives](guide/structural-directives#template-input-variable).
218+
For more information about template input variables, see [Structural directive shorthand](guide/structural-directives#shorthand).
219219

220220
### Getting the `index` of `*ngFor`
221221

@@ -228,8 +228,12 @@ The following example gets the `index` in a variable named `i` and displays it w
228228

229229
The index property of the `NgFor` directive context returns the zero-based index of the item in each iteration.
230230

231-
{@a one-per-element}
231+
Angular translates this instruction into an `<ng-template>` around the host element,
232+
then uses this template repeatedly to create a new set of elements and bindings for each `item`
233+
in the list.
234+
For more information about shorthand, see the [Structural Directives](guide/structural-directives#shorthand) guide.
232235

236+
{@a one-per-element}
233237
## Repeating elements when a condition is true
234238

235239
To repeat a block of HTML when a particular condition is true, put the `*ngIf` on a container element that wraps an `*ngFor` element.
@@ -278,7 +282,7 @@ They do not have special access to any private APIs that other directives can't
278282

279283
The Angular `<ng-container>` is a grouping element that doesn't interfere with styles or layout because Angular doesn't put it in the DOM.
280284

281-
You can use [`<ng-container>`](guide/structural-directives#ngcontainer) when there's no single element to host the directive.
285+
You can use `<ng-container>` when there's no single element to host the directive.
282286

283287
Here's a conditional paragraph using `<ng-container>`.
284288

@@ -339,8 +343,6 @@ For example, you could replace the `<app-best-item>` switch case with a `<div>`
339343

340344
<code-example path="built-in-directives/src/app/app.component.html" region="NgSwitch-div" header="src/app/app.component.html"></code-example>
341345

342-
<hr />
343-
344346
## What's next
345347

346348
For information on how to build your own custom directives, see [Attribute Directives](guide/attribute-directives) and [Structural Directives](guide/structural-directives).

‎aio/content/guide/example-apps-list.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ For more information, see [Template reference variables](guide/template-referenc
180180
<live-example name="ngcontainer"></live-example>
181181

182182
Demonstrates `<ngcontainer>`.
183-
For more information, see the [ngtemplate section](guide/structural-directives#ngcontainer) of [Structural directives](guide/structural-directives) .
183+
For more information, see the [ng-container section](guide/built-in-directives#ngcontainer) of [Built-in directives](guide/structural-directives) .
184184

185185
### Pipes
186186

‎aio/content/guide/glossary.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -340,6 +340,12 @@ Angular supplies a number of built-in directives that begin with the `ng` prefix
340340
You can also create new directives to implement your own functionality.
341341
You associate a *selector* (an HTML tag such as `<my-directive>`) with a custom directive, thereby extending the [template syntax](guide/template-syntax) that you can use in your apps.
342342

343+
**UpperCamelCase**, such as `NgIf`, refers to a directive class.
344+
You can use **UpperCamelCase** when describing properties and directive behavior.
345+
346+
**lowerCamelCase**, such as `ngIf` refers to a directive's attribute name.
347+
You can use **lowerCamelCase** when describing how to apply the directive to an element in the HTML template.
348+
343349
{@a dom}
344350

345351
## domain-specific language (DSL)

‎aio/content/guide/interpolation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ In the following snippet, the expression `recommended` and the expression `itemI
8686

8787
<code-example path="interpolation/src/app/app.component.html" region="component-context" header="src/app/app.component.html"></code-example>
8888

89-
An expression can also refer to properties of the _template's_ context such as a [template input variable](guide/structural-directives#template-input-variables) or a [template reference variable](guide/template-reference-variables).
89+
An expression can also refer to properties of the _template's_ context such as a [template input variable](guide/structural-directives#shorthand) or a [template reference variable](guide/template-reference-variables).
9090

9191
The following example uses a template input variable of `customer`.
9292

0 commit comments

Comments
 (0)