1
|
/**
|
2
|
* @license
|
3
|
* Copyright Google Inc. All Rights Reserved.
|
4
|
*
|
5
|
* Use of this source code is governed by an MIT-style license that can be
|
6
|
* found in the LICENSE file at https://angular.io/license
|
7
|
*/
|
8
|
import { TemplateRef, ViewContainerRef } from '@angular/core';
|
9
|
/**
|
10
|
* Conditionally includes a template based on the value of an `expression`.
|
11
|
*
|
12
|
* `ngIf` evaluates the `expression` and then renders the `then` or `else` template in its place
|
13
|
* when expression is truthy or falsy respectively. Typically the:
|
14
|
* - `then` template is the inline template of `ngIf` unless bound to a different value.
|
15
|
* - `else` template is blank unless it is bound.
|
16
|
*
|
17
|
* ## Most common usage
|
18
|
*
|
19
|
* The most common usage of the `ngIf` directive is to conditionally show the inline template as
|
20
|
* seen in this example:
|
21
|
* {@example common/ngIf/ts/module.ts region='NgIfSimple'}
|
22
|
*
|
23
|
* ## Showing an alternative template using `else`
|
24
|
*
|
25
|
* If it is necessary to display a template when the `expression` is falsy use the `else` template
|
26
|
* binding as shown. Note that the `else` binding points to a `<ng-template>` labeled `#elseBlock`.
|
27
|
* The template can be defined anywhere in the component view but is typically placed right after
|
28
|
* `ngIf` for readability.
|
29
|
*
|
30
|
* {@example common/ngIf/ts/module.ts region='NgIfElse'}
|
31
|
*
|
32
|
* ## Using non-inlined `then` template
|
33
|
*
|
34
|
* Usually the `then` template is the inlined template of the `ngIf`, but it can be changed using
|
35
|
* a binding (just like `else`). Because `then` and `else` are bindings, the template references can
|
36
|
* change at runtime as shown in this example.
|
37
|
*
|
38
|
* {@example common/ngIf/ts/module.ts region='NgIfThenElse'}
|
39
|
*
|
40
|
* ## Storing conditional result in a variable
|
41
|
*
|
42
|
* A common pattern is that we need to show a set of properties from the same object. If the
|
43
|
* object is undefined, then we have to use the safe-traversal-operator `?.` to guard against
|
44
|
* dereferencing a `null` value. This is especially the case when waiting on async data such as
|
45
|
* when using the `async` pipe as shown in following example:
|
46
|
*
|
47
|
* ```
|
48
|
* Hello {{ (userStream|async)?.last }}, {{ (userStream|async)?.first }}!
|
49
|
* ```
|
50
|
*
|
51
|
* There are several inefficiencies in the above example:
|
52
|
* - We create multiple subscriptions on `userStream`. One for each `async` pipe, or two in the
|
53
|
* example above.
|
54
|
* - We cannot display an alternative screen while waiting for the data to arrive asynchronously.
|
55
|
* - We have to use the safe-traversal-operator `?.` to access properties, which is cumbersome.
|
56
|
* - We have to place the `async` pipe in parenthesis.
|
57
|
*
|
58
|
* A better way to do this is to use `ngIf` and store the result of the condition in a local
|
59
|
* variable as shown in the the example below:
|
60
|
*
|
61
|
* {@example common/ngIf/ts/module.ts region='NgIfAs'}
|
62
|
*
|
63
|
* Notice that:
|
64
|
* - We use only one `async` pipe and hence only one subscription gets created.
|
65
|
* - `ngIf` stores the result of the `userStream|async` in the local variable `user`.
|
66
|
* - The local `user` can then be bound repeatedly in a more efficient way.
|
67
|
* - No need to use the safe-traversal-operator `?.` to access properties as `ngIf` will only
|
68
|
* display the data if `userStream` returns a value.
|
69
|
* - We can display an alternative template while waiting for the data.
|
70
|
*
|
71
|
* ### Syntax
|
72
|
*
|
73
|
* Simple form:
|
74
|
* - `<div *ngIf="condition">...</div>`
|
75
|
* - `<div template="ngIf condition">...</div>`
|
76
|
* - `<ng-template [ngIf]="condition"><div>...</div></ng-template>`
|
77
|
*
|
78
|
* Form with an else block:
|
79
|
* ```
|
80
|
* <div *ngIf="condition; else elseBlock">...</div>
|
81
|
* <ng-template #elseBlock>...</ng-template>
|
82
|
* ```
|
83
|
*
|
84
|
* Form with a `then` and `else` block:
|
85
|
* ```
|
86
|
* <div *ngIf="condition; then thenBlock else elseBlock"></div>
|
87
|
* <ng-template #thenBlock>...</ng-template>
|
88
|
* <ng-template #elseBlock>...</ng-template>
|
89
|
* ```
|
90
|
*
|
91
|
* Form with storing the value locally:
|
92
|
* ```
|
93
|
* <div *ngIf="condition as value; else elseBlock">{{value}}</div>
|
94
|
* <ng-template #elseBlock>...</ng-template>
|
95
|
* ```
|
96
|
*
|
97
|
* @stable
|
98
|
*/
|
99
|
export declare class NgIf {
|
100
|
private _viewContainer;
|
101
|
private _context;
|
102
|
private _thenTemplateRef;
|
103
|
private _elseTemplateRef;
|
104
|
private _thenViewRef;
|
105
|
private _elseViewRef;
|
106
|
constructor(_viewContainer: ViewContainerRef, templateRef: TemplateRef<NgIfContext>);
|
107
|
ngIf: any;
|
108
|
ngIfThen: TemplateRef<NgIfContext>;
|
109
|
ngIfElse: TemplateRef<NgIfContext>;
|
110
|
private _updateView();
|
111
|
}
|
112
|
/**
|
113
|
* @stable
|
114
|
*/
|
115
|
export declare class NgIfContext {
|
116
|
$implicit: any;
|
117
|
ngIf: any;
|
118
|
}
|