Skip to content

Commit 9cee8bc

Browse files
vicbIgorMinar
authored andcommitted
docs(common): add directives docs
Closes angular#11581
1 parent 003294d commit 9cee8bc

5 files changed

Lines changed: 144 additions & 193 deletions

File tree

‎modules/@angular/common/src/directives/ng_class.ts‎

Lines changed: 17 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -11,65 +11,32 @@ import {CollectionChangeRecord, Directive, DoCheck, ElementRef, Input, IterableD
1111
import {isListLikeIterable} from '../facade/collection';
1212
import {isPresent} from '../facade/lang';
1313

14+
15+
1416
/**
15-
* The `NgClass` directive conditionally adds and removes CSS classes on an HTML element based on
16-
* an expression's evaluation result.
17-
*
18-
* The result of an expression evaluation is interpreted differently depending on type of
19-
* the expression evaluation result:
20-
* - `string` - all the CSS classes listed in a string (space delimited) are added
21-
* - `Array` - all the CSS classes (Array elements) are added
22-
* - `Object` - each key corresponds to a CSS class name while values are interpreted as expressions
23-
* evaluating to `Boolean`. If a given expression evaluates to `true` a corresponding CSS class
24-
* is added - otherwise it is removed.
25-
*
26-
* While the `NgClass` directive can interpret expressions evaluating to `string`, `Array`
27-
* or `Object`, the `Object`-based version is the most often used and has an advantage of keeping
28-
* all the CSS class names in a template.
17+
* @ngModule CommonModule
2918
*
30-
* ### Example ([live demo](http://plnkr.co/edit/a4YdtmWywhJ33uqfpPPn?p=preview)):
19+
* @whatItDoes Adds and removes CSS classes on an HTML element.
3120
*
21+
* @howToUse
3222
* ```
33-
* import {Component} from '@angular/core';
34-
* import {NgClass} from '@angular/common';
23+
* <some-element [ngClass]="'first second'">...</some-element>
3524
*
36-
* @Component({
37-
* selector: 'toggle-button',
38-
* inputs: ['isDisabled'],
39-
* template: `
40-
* <div class="button" [ngClass]="{active: isOn, disabled: isDisabled}"
41-
* (click)="toggle(!isOn)">
42-
* Click me!
43-
* </div>`,
44-
* styles: [`
45-
* .button {
46-
* width: 120px;
47-
* border: medium solid black;
48-
* }
25+
* <some-element [ngClass]="['first', 'second']">...</some-element>
4926
*
50-
* .active {
51-
* background-color: red;
52-
* }
27+
* <some-element [ngClass]="{'first': true, 'second': true, 'third': false}">...</some-element>
5328
*
54-
* .disabled {
55-
* color: gray;
56-
* border: medium solid gray;
57-
* }
58-
* `],
59-
* directives: [NgClass]
60-
* })
61-
* class ToggleButton {
62-
* isOn = false;
63-
* isDisabled = false;
64-
*
65-
* toggle(newState) {
66-
* if (!this.isDisabled) {
67-
* this.isOn = newState;
68-
* }
69-
* }
70-
* }
29+
* <some-element [ngClass]="stringExp|arrayExp|objExp">...</some-element>
7130
* ```
7231
*
32+
* @description
33+
*
34+
* The CSS classes are updated as follow depending on the type of the expression evaluation:
35+
* - `string` - the CSS classes listed in a string (space delimited) are added,
36+
* - `Array` - the CSS classes (Array elements) are added,
37+
* - `Object` - keys are CSS class names that get added when the expression given in the value
38+
* evaluates to a truthy value, otherwise class are removed.
39+
*
7340
* @stable
7441
*/
7542
@Directive({selector: '[ngClass]'})

‎modules/@angular/common/src/directives/ng_plural.ts‎

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -14,48 +14,35 @@ import {SwitchView} from './ng_switch';
1414

1515

1616
/**
17-
* `ngPlural` is an i18n directive that displays DOM sub-trees that match the switch expression
18-
* value, or failing that, DOM sub-trees that match the switch expression's pluralization category.
17+
* @ngModule CommonModule
1918
*
20-
* To use this directive you must provide a container element that sets the `[ngPlural]` attribute
21-
* to a
22-
* switch expression.
23-
* - Inner elements defined with an `[ngPluralCase]` attribute will display based on their
24-
* expression.
25-
* - If `[ngPluralCase]` is set to a value starting with `=`, it will only display if the value
26-
* matches the switch expression exactly.
27-
* - Otherwise, the view will be treated as a "category match", and will only display if exact
28-
* value matches aren't found and the value maps to its category for the defined locale.
19+
* @whatItDoes Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization.
20+
*
21+
* @howToUse
22+
* ```
23+
* <some-element [ngPlural]="value">
24+
* <ng-container *ngPluralCase="'=0'">there is nothing</ng-container>
25+
* <ng-container *ngPluralCase="'=1'">there is one</ng-container>
26+
* <ng-container *ngPluralCase="'few'">there are a few</ng-container>
27+
* <ng-container *ngPluralCase="'other'">there are exactly #</ng-container>
28+
* </some-element>
29+
* ```
2930
*
30-
* ```typescript
31-
* @Component({
32-
* selector: 'app',
33-
* // best practice is to define the locale at the application level
34-
* providers: [{provide: LOCALE_ID, useValue: 'en_US'}]
35-
* })
36-
* @View({
37-
* template: `
38-
* <p>Value = {{value}}</p>
39-
* <button (click)="inc()">Increment</button>
31+
* @description
4032
*
41-
* <div [ngPlural]="value">
42-
* <template ngPluralCase="=0">there is nothing</template>
43-
* <template ngPluralCase="=1">there is one</template>
44-
* <template ngPluralCase="few">there are a few</template>
45-
* <template ngPluralCase="other">there is some number</template>
46-
* </div>
47-
* `,
48-
* directives: [NgPlural, NgPluralCase]
49-
* })
50-
* export class App {
51-
* value = 'init';
33+
* Displays DOM sub-trees that match the switch expression value, or failing that, DOM sub-trees
34+
* that match the switch expression's pluralization category.
5235
*
53-
* inc() {
54-
* this.value = this.value === 'init' ? 0 : this.value + 1;
55-
* }
56-
* }
36+
* To use this directive you must provide a container element that sets the `[ngPlural]` attribute
37+
* to a switch expression. Inner elements with a `[ngPluralCase]` will display based on their
38+
* expression:
39+
* - if `[ngPluralCase]` is set to a value starting with `=`, it will only display if the value
40+
* matches the switch expression exactly,
41+
* - otherwise, the view will be treated as a "category match", and will only display if exact
42+
* value matches aren't found and the value maps to its category for the defined locale.
43+
*
44+
* See http://cldr.unicode.org/index/cldr-spec/plural-rules
5745
*
58-
* ```
5946
* @experimental
6047
*/
6148
@Directive({selector: '[ngPlural]'})
@@ -98,6 +85,19 @@ export class NgPlural {
9885
}
9986

10087
/**
88+
* @ngModule CommonModule
89+
*
90+
* @whatItDoes Creates a view that will be added/removed from the parent {@link NgPlural} when the
91+
* given expression matches the plural expression according to CLDR rules.
92+
*
93+
* @howToUse
94+
* <some-element [ngPlural]="value">
95+
* <ng-container *ngPluralCase="'=0'">...</ng-container>
96+
* <ng-container *ngPluralCase="'other'">...</ng-container>
97+
* </some-element>
98+
*
99+
* See {@link NgPlural} for more details and example.
100+
*
101101
* @experimental
102102
*/
103103
@Directive({selector: '[ngPluralCase]'})

‎modules/@angular/common/src/directives/ng_style.ts‎

Lines changed: 11 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -9,56 +9,24 @@
99
import {Directive, DoCheck, ElementRef, Input, KeyValueChangeRecord, KeyValueDiffer, KeyValueDiffers, Renderer} from '@angular/core';
1010

1111
/**
12-
* The `NgStyle` directive changes styles based on a result of expression evaluation.
12+
* @ngModule CommonModule
1313
*
14-
* An expression assigned to the `ngStyle` property must evaluate to an object and the
15-
* corresponding element styles are updated based on changes to this object. Style names to update
16-
* are taken from the object's keys, and values - from the corresponding object's values.
17-
*
18-
* ### Syntax
19-
*
20-
* - `<div [ngStyle]="{'font-style': styleExp}"></div>`
21-
* - `<div [ngStyle]="{'max-width.px': widthExp}"></div>`
22-
* - `<div [ngStyle]="styleExp"></div>` - here the `styleExp` must evaluate to an object
23-
*
24-
* ### Example ([live demo](http://plnkr.co/edit/YamGS6GkUh9GqWNQhCyM?p=preview)):
14+
* @whatItDoes Update an HTML element styles.
2515
*
16+
* @howToUse
2617
* ```
27-
* import {Component} from '@angular/core';
28-
* import {NgStyle} from '@angular/common';
29-
*
30-
* @Component({
31-
* selector: 'ngStyle-example',
32-
* template: `
33-
* <h1 [ngStyle]="{'font-style': style, 'font-size': size, 'font-weight': weight}">
34-
* Change style of this text!
35-
* </h1>
18+
* <some-element [ngStyle]="{'font-style': styleExp}">...</some-element>
3619
*
37-
* <hr>
20+
* <some-element [ngStyle]="{'max-width.px': widthExp}">...</some-element>
3821
*
39-
* <label>Italic: <input type="checkbox" (change)="changeStyle($event)"></label>
40-
* <label>Bold: <input type="checkbox" (change)="changeWeight($event)"></label>
41-
* <label>Size: <input type="text" [value]="size" (change)="size = $event.target.value"></label>
42-
* `,
43-
* directives: [NgStyle]
44-
* })
45-
* export class NgStyleExample {
46-
* style = 'normal';
47-
* weight = 'normal';
48-
* size = '20px';
49-
*
50-
* changeStyle($event: any) {
51-
* this.style = $event.target.checked ? 'italic' : 'normal';
52-
* }
53-
*
54-
* changeWeight($event: any) {
55-
* this.weight = $event.target.checked ? 'bold' : 'normal';
56-
* }
57-
* }
22+
* <some-element [ngStyle]="objExp">...</some-element>
5823
* ```
5924
*
60-
* In this example the `font-style`, `font-size` and `font-weight` styles will be updated
61-
* based on the `style` property's value changes.
25+
* @description
26+
*
27+
* The styles are updated according to the value of the expression evaluation:
28+
* - keys are style names with an option `.<unit>` suffix (ie 'top.px', 'font-style.em'),
29+
* - values are the values assigned to those properties (expressed in the given unit).
6230
*
6331
* @stable
6432
*/

‎modules/@angular/common/src/directives/ng_switch.ts‎

Lines changed: 68 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -22,58 +22,44 @@ export class SwitchView {
2222
}
2323

2424
/**
25-
* Adds or removes DOM sub-trees when their match expressions match the switch expression.
26-
*
27-
* Elements within `NgSwitch` but without `NgSwitchCase` or `NgSwitchDefault` directives will be
28-
* preserved at the location as specified in the template.
29-
*
30-
* `NgSwitch` simply inserts nested elements based on which match expression matches the value
31-
* obtained from the evaluated switch expression. In other words, you define a container element
32-
* (where you place the directive with a switch expression on the
33-
* `[ngSwitch]="..."` attribute), define any inner elements inside of the directive and
34-
* place a `[ngSwitchCase]` attribute per element.
35-
*
36-
* The `ngSwitchCase` property is used to inform `NgSwitch` which element to display when the
37-
* expression is evaluated. If a matching expression is not found via a `ngSwitchCase` property
38-
* then an element with the `ngSwitchDefault` attribute is displayed.
39-
*
40-
* ### Example ([live demo](http://plnkr.co/edit/DQMTII95CbuqWrl3lYAs?p=preview))
41-
*
42-
* ```typescript
43-
* @Component({
44-
* selector: 'app',
45-
* template: `
46-
* <p>Value = {{value}}</p>
47-
* <button (click)="inc()">Increment</button>
48-
*
49-
* <div [ngSwitch]="value">
50-
* <p *ngSwitchCase="'init'">increment to start</p>
51-
* <p *ngSwitchCase="0">0, increment again</p>
52-
* <p *ngSwitchCase="1">1, increment again</p>
53-
* <p *ngSwitchCase="2">2, stop incrementing</p>
54-
* <p *ngSwitchDefault>&gt; 2, STOP!</p>
55-
* </div>
56-
*
57-
* <!-- alternate syntax -->
58-
*
59-
* <p [ngSwitch]="value">
60-
* <template ngSwitchCase="init">increment to start</template>
61-
* <template [ngSwitchCase]="0">0, increment again</template>
62-
* <template [ngSwitchCase]="1">1, increment again</template>
63-
* <template [ngSwitchCase]="2">2, stop incrementing</template>
64-
* <template ngSwitchDefault>&gt; 2, STOP!</template>
65-
* </p>
66-
* `,
67-
* directives: [NgSwitch, NgSwitchCase, NgSwitchDefault]
68-
* })
69-
* export class App {
70-
* value = 'init';
71-
*
72-
* inc() {
73-
* this.value = this.value === 'init' ? 0 : this.value + 1;
74-
* }
75-
* }
25+
* @ngModule CommonModule
26+
*
27+
* @whatItDoes Adds / removes DOM sub-trees when the nest match expressions matches the switch
28+
* expression.
29+
*
30+
* @howToUse
7631
* ```
32+
* <container-element [ngSwitch]="switch_expression">
33+
* <some-element *ngSwitchCase="match_expression_1">...</some-element>
34+
* <some-element *ngSwitchCase="match_expression_2">...</some-element>
35+
* <some-other-element *ngSwitchCase="match_expression_3">...</some-other-element>
36+
* <ng-container *ngSwitchCase="match_expression_3">
37+
* <!-- use a ng-container to group multiple root nodes -->
38+
* <inner-element></inner-element>
39+
* <inner-other-element></inner-other-element>
40+
* </ng-container>
41+
* <some-element *ngSwitchDefault>...</p>
42+
* </container-element>
43+
* ```
44+
* @description
45+
*
46+
* `NgSwitch` stamps out nested views when their match expression value matches the value of the
47+
* switch expression.
48+
*
49+
* In other words:
50+
* - you define a container element (where you place the directive with a switch expression on the
51+
* `[ngSwitch]="..."` attribute)
52+
* - you define inner views inside the `NgSwitch` and place a `*ngSwitchCase` attribute on the view
53+
* root elements.
54+
*
55+
* Elements within `NgSwitch` but outside of a `NgSwitchCase` or `NgSwitchDefault` directives will
56+
* be
57+
* preserved at the location.
58+
*
59+
* The `ngSwitchCase` directive informs the parent `NgSwitch` of which view to display when the
60+
* expression is evaluated.
61+
* When no matching expression is found on a `ngSwitchCase` view, the `ngSwitchDefault` view is
62+
* stamped out.
7763
*
7864
* @stable
7965
*/
@@ -169,10 +155,23 @@ export class NgSwitch {
169155
}
170156

171157
/**
172-
* Insert the sub-tree when the `ngSwitchCase` expression evaluates to the same value as the
173-
* enclosing switch expression.
158+
* @ngModule CommonModule
174159
*
175-
* If multiple match expression match the switch expression value, all of them are displayed.
160+
* @whatItDoes Creates a view that will be added/removed from the parent {@link NgSwitch} when the
161+
* given expression evaluate to respectively the same/different value as the switch
162+
* expression.
163+
*
164+
* @howToUse
165+
* <container-element [ngSwitch]="switch_expression">
166+
* <some-element *ngSwitchCase="match_expression_1">...</some-element>
167+
* </container-element>
168+
*
169+
* @description
170+
*
171+
* Insert the sub-tree when the expression evaluates to the same value as the enclosing switch
172+
* expression.
173+
*
174+
* If multiple match expressions match the switch expression value, all of them are displayed.
176175
*
177176
* See {@link NgSwitch} for more details and example.
178177
*
@@ -202,8 +201,21 @@ export class NgSwitchCase {
202201
}
203202

204203
/**
205-
* Default case statements are displayed when no match expression matches the switch expression
206-
* value.
204+
* @ngModule CommonModule
205+
* @whatItDoes Creates a view that is added to the parent {@link NgSwitch} when no case expressions
206+
* match the
207+
* switch expression.
208+
*
209+
* @howToUse
210+
* <container-element [ngSwitch]="switch_expression">
211+
* <some-element *ngSwitchCase="match_expression_1">...</some-element>
212+
* <some-other-element *ngSwitchDefault>...</some-other-element>
213+
* </container-element>
214+
*
215+
* @description
216+
*
217+
* Insert the sub-tree when no case expressions evaluate to the same value as the enclosing switch
218+
* expression.
207219
*
208220
* See {@link NgSwitch} for more details and example.
209221
*

0 commit comments

Comments
 (0)