Skip to content

Commit 4df0604

Browse files
trotylmhevery
trotyl
authored and
mhevery
committed
docs: cleanup
According to dictionary 'syntax' is countable and according to context it should be plural. fix the broken table of template summary. fix the table in Property Binding. fix a position of right parethesis in Property Binding. fix a occurance of a non-sense underscore. fix a table in Inline Templates. fix a missing '.' in Template Microsyntax. fix the table in '## Binding Events'. fix an article usage of 'an' against 'a' in '## Binding Events'. fix a statement against the usage of plural after 'any'. fix the typo error in former fixes. Closes angular#3994
1 parent a826f22 commit 4df0604

1 file changed

Lines changed: 102 additions & 98 deletions

File tree

‎modules/angular2/docs/core/01_templates.md‎

Lines changed: 102 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Templates are markup which is added to HTML to declaratively describe how the application model should be
44
projected to DOM as well as which DOM events should invoke which methods on the controller. Templates contain
5-
syntax which is core to Angular and allows for data-binding, event-binding, template-instantiation.
5+
syntaxes which are core to Angular and allows for data-binding, event-binding, template-instantiation.
66

77
The design of the template syntax has these properties:
88

@@ -35,183 +35,187 @@ detail in the following sections.
3535
<th>Text Interpolation</th>
3636
<td>
3737
<pre>
38-
```
39-
<div>{{exp}}</div>
40-
```
38+
&lt;div&gt;{{exp}}&lt;/div&gt;
4139
</pre>
4240

4341
Example:
4442
<pre>
45-
```
46-
<div>
43+
&lt;div&gt;
4744
Hello {{name}}!
48-
<br>
45+
&lt;br&gt;
4946
Goodbye {{name}}!
50-
</div>
51-
```
47+
&lt;/div&gt;
5248
</pre>
5349
</td>
5450
<td>
55-
`<div [text|index]=exp>`
51+
<pre>
52+
&lt;div [text|index]="exp"&gt;&lt;/div&gt;
53+
</pre>
5654

5755
Example:
5856
<pre>
59-
```
60-
<div
57+
&lt;div
6158
[text|0]=" 'Hello' + stringify(name) + '!' "
62-
[text|2]=" 'Goodbye' + stringify(name) + '!' ">
63-
_<b>x</b>_
64-
</div>
65-
```
59+
[text|2]=" 'Goodbye' + stringify(name) + '!' "&gt;
60+
&lt;b&gt;x&lt;/b&gt;
61+
&lt;/div&gt;
6662
</pre>
6763
</td>
6864
</tr>
6965
<tr>
7066
<th>Property Interpolation</th>
7167
<td>
7268
<pre>
73-
```
74-
<div name="{{exp}}">
75-
```
69+
&lt;div name="{{exp}}"&gt;&lt;/div&gt;
7670
</pre>
7771

7872
Example:
7973

8074
<pre>
81-
```
82-
<div class="{{selected}}">`
83-
```
75+
&lt;div class="{{selected}}"&gt;&lt;/div&gt;
8476
</pre>
8577
</td>
8678
<td>
8779
<pre>
88-
```
89-
<div [name]="stringify(exp)">
90-
```
80+
&lt;div [name]="stringify(exp)"&gt;&lt;/div&gt;
9181
</pre>
9282

9383
Example:
9484

9585
<pre>
96-
```
97-
<div [title]="stringify(selected)">
98-
```
86+
&lt;div [title]="stringify(selected)"&gt;&lt;/div&gt;
9987
</pre>
10088
</td>
10189
</tr>
10290
<tr>
10391
<th>Property binding</th>
10492
<td>
105-
`<div [prop]="exp">`
93+
<pre>
94+
&lt;div [prop]="exp"&gt;&lt;/div&gt;
95+
</pre>
10696

10797
Example:
10898

109-
`<div [hidden]="true">`
99+
<pre>
100+
&lt;div [hidden]="true"&gt;&lt;/div&gt;
101+
</pre>
110102
</td>
111103
<td>
112-
`<div bind-prop="exp">`
104+
<pre>
105+
&lt;div bind-prop="exp"&gt;&lt;/div&gt;
106+
</pre>
113107

114108
Example:
115109

116-
`<div bind-hidden="true">`
110+
<pre>
111+
&lt;div bind-hidden="true"&gt;&lt;/div&gt;
112+
</pre>
117113
</td>
118114
</tr>
119115
<tr>
120116
<th>Event binding (non-bubbling)</th>
121117
<td>
122-
`<div (event)="statement">`
118+
<pre>
119+
&lt;div (event)="statement"&gt;&lt;/div&gt;
120+
</pre>
123121

124122
Example:
125123

126-
`<div (click)="doX()">`
124+
<pre>
125+
&lt;div (click)="doX()"&gt;&lt;/div&gt;
126+
</pre>
127127
</td>
128128
<td>
129-
`<div on-event="statement">`
129+
<pre>
130+
&lt;div on-event="statement"&gt;&lt;/div&gt;
131+
</pre>
130132

131133
Example:
132134

133135
<pre>
134-
```
135-
<video #player>
136-
<button (click)="player.play()">play</button>
137-
```
136+
&lt;video #player&gt;
137+
&lt;button (click)="player.play()"&gt;play&lt;/button&gt;
138+
&lt;/video&gt;
139+
</pre>
140+
141+
Or:
142+
143+
<pre>
144+
&lt;div def="symbol"&gt;&lt;/div&gt;
138145
</pre>
139-
</td>
140-
<td>
141-
`<div def="symbol">`
142146

143147
Example:
144148

145149
<pre>
146-
```
147-
<video def="player">
148-
<button on-click="player.play()">play</button>
149-
```
150+
&lt;video def="player"&gt;
151+
&lt;button on-click="player.play()"&gt;play&lt;/button&gt;
152+
&lt;/video&gt;
150153
</pre>
151154
</td>
152155
</tr>
153156
<tr>
154157
<th>Inline Template</th>
155158
<td>
156-
`<div template="...">...</div>`
159+
<pre>
160+
&lt;div template="..."&gt;...&lt;/div&gt;
161+
</pre>
157162

158163
Example:
159164

160165
<pre>
161-
```
162-
<ul>
163-
<li template="for: #item of items">
166+
&lt;ul&gt;
167+
&lt;li template="for: #item of items"&gt;
164168
{{item}}
165-
</li>
166-
</ul>
167-
```
169+
&lt;/li&gt;
170+
&lt;/ul&gt;
168171
</pre>
169172
</td>
170173
<td>
171-
`<template>...</template>`
174+
<pre>
175+
&lt;template&gt;...&lt;/template&gt;
176+
</pre>
172177

173178
Example:
174179
<pre>
175-
```
176-
<ul>
177-
<template def-for:"item"
178-
bind-for-in="items">
179-
<li>
180+
&lt;ul&gt;
181+
&lt;template def-for:"item"
182+
bind-for-in="items"&gt;
183+
&lt;li&gt;
180184
{{item}}
181-
</li>
182-
</template>
183-
</ul>
184-
```
185+
&lt;/li&gt;
186+
&lt;/template&gt;
187+
&lt;/ul&gt;
185188
</pre>
186189
</td>
187190
</tr>
188191
<tr>
189192
<th>Explicit Template</th>
190193
<td>
191-
`<template>...</template>`
194+
<pre>
195+
&lt;template&gt;...&lt;/template&gt;
196+
</pre>
192197

193198
Example:
194199

195200
<pre>
196-
```
197-
<template #for="item"
198-
[for-in]="items">
201+
&lt;template #for="item"
202+
[for-in]="items"&gt;
199203
_some_content_to_repeat_
200-
</template>
201-
```
204+
&lt;/template&gt;
202205
</pre>
203206
</td>
204207
<td>
205-
`<template>...</template>`
208+
<pre>
209+
&lt;template&gt;...&lt;/template&gt;
210+
</pre>
206211

207212
Example:
213+
208214
<pre>
209-
```
210-
<template def-for="item"
211-
bind-for-in="items">
215+
&lt;template def-for="item"
216+
bind-for-in="items"&gt;
212217
_some_content_to_repeat_
213-
</template>
214-
```
218+
&lt;/template&gt;
215219
</pre>
216220
</td>
217221
</tr>
@@ -228,11 +232,11 @@ are always in the form of `property-name` which is assigned an `expression`. The
228232
<table>
229233
<tr>
230234
<th>Short form</th>
231-
<td>`<some-element [some-property]="expression">`</td>
235+
<td><pre>&lt;some-element [some-property]="expression"&gt;</pre></td>
232236
</tr>
233237
<tr>
234238
<th>Canonical form</th>
235-
<td>`<some-element bind-some-property="expression">`</td>
239+
<td><pre>&lt;some-element bind-some-property="expression"&gt;</pre></td>
236240
</tr>
237241
</table>
238242

@@ -255,7 +259,7 @@ Key points:
255259
* The binding is to the element property not the element attribute.
256260
* To prevent custom element from accidentally reading the literal `expression` on the title element, the attribute name
257261
is escaped. In our case the `title` is escaped to `[title]` through the addition of square brackets `[]`.
258-
* A binding value (in this case `user.firstName` will always be an expression, never a string literal).
262+
* A binding value (in this case `user.firstName`) will always be an expression, never a string literal.
259263

260264
NOTE: Unlike Angular v1, Angular v2 binds to properties of elements rather than attributes of elements. This is
261265
done to better support custom elements, and to allow binding for values other than strings.
@@ -277,7 +281,7 @@ syntax which is just a short hand for the data binding syntax.
277281
is a short hand for:
278282

279283
```
280-
<span [text|0]=" 'Hello ' + stringify(name) + '!' ">_</span>
284+
<span [text|0]=" 'Hello ' + stringify(name) + '!' "></span>
281285
```
282286

283287
The above says to bind the `'Hello ' + stringify(name) + '!'` expression to the zero-th child of the `span`'s `text`
@@ -317,25 +321,25 @@ Views than can be inserted and removed as needed to change the DOM structure.
317321
<tr>
318322
<th>Short form</th>
319323
<td>
320-
```
324+
<pre>
321325
parent template
322-
<element>
323-
<some-element template="instantiating-directive-microsyntax">child template</some-element>
324-
</element>
325-
```
326+
&lt;element&gt;
327+
&lt;some-element template="instantiating-directive-microsyntax"&gt;child template&lt;/some-element&gt;
328+
&lt;/element&gt;
329+
</pre>
326330
</td>
327331
</tr>
328332
<tr>
329333
<th>Canonical form</th>
330334
<td>
331-
```
335+
<pre>
332336
parent template
333-
<element>
334-
<template instantiating-directive-bindings>
335-
<some-element>child template</some-element>
336-
</template>
337-
</element>
338-
```
337+
&lt;element&gt;
338+
&lt;template instantiating-directive-bindings&gt;
339+
&lt;some-element&gt;child template&lt;/some-element&gt;
340+
&lt;/template&gt;
341+
&lt;/element&gt;
342+
</pre>
339343
</td>
340344
</tr>
341345
</table>
@@ -448,7 +452,7 @@ microsyntax: ([[key|keyExpression|varExport][;|,]?)*
448452
```
449453

450454
Where
451-
* `expression` is an Angular expression as defined in section: Expressions
455+
* `expression` is an Angular expression as defined in section: Expressions.
452456
* `local` is a local identifier for local variables.
453457
* `internal` is an internal variable which the directive exports for binding.
454458
* `key` is an attribute name usually only used to trigger a specific directive.
@@ -473,11 +477,11 @@ Binding events allows wiring events from DOM (or other components) to the Angula
473477
<table>
474478
<tr>
475479
<th>Short form</th>
476-
<td>`<some-element (some-event)="statement">`</td>
480+
<td><pre>&lt;some-element (some-event)="statement"&gt;</pre></td>
477481
</tr>
478482
<tr>
479483
<th>Canonical form</th>
480-
<td>`<some-element on-some-event="statement">`</td>
484+
<td><pre>&lt;some-element on-some-event="statement"&gt;</pre></td>
481485
</tr>
482486
</table>
483487

@@ -493,11 +497,11 @@ Angular listens to bubbled DOM events (as in the case of clicking on any child),
493497
<table>
494498
<tr>
495499
<th>Short form</th>
496-
<td>`<some-element (some-event)="statement">`</td>
500+
<td><pre>&lt;some-element (some-event)="statement"&gt;</pre></td>
497501
</tr>
498502
<tr>
499503
<th>Canonical form</th>
500-
<td>`<some-element on-some-event="statement">`</td>
504+
<td><pre>&lt;some-element on-some-event="statement"&gt;</pre></td>
501505
</tr>
502506
</table>
503507

@@ -519,7 +523,7 @@ component's controller.
519523

520524

521525
NOTE: Unlike Angular v1, Angular v2 treats event bindings as core constructs not as directives. This means that there
522-
is no need to create a event directive for each kind of event. This makes it possible for Angular v2 to easily
526+
is no need to create an event directive for each kind of event. This makes it possible for Angular v2 to easily
523527
bind to custom events of Custom Elements, whose event names are not known ahead of time.
524528

525529

@@ -534,7 +538,7 @@ have different semantics.
534538
### Expressions
535539

536540
Expressions can be used to bind to properties only. Expressions represent how data should be projected to the View.
537-
Expressions should not have any side effects and should be idempotent. Examples of where expressions can be used in
541+
Expressions should not have any side effect and should be idempotent. Examples of where expressions can be used in
538542
Angular are:
539543
```
540544
<div title="{{expression}}">{{expression}}</div>

0 commit comments

Comments
 (0)