From b4db73d0bf0bdb0a15f71a9ac6f69284f5c2686a Mon Sep 17 00:00:00 2001
From: Misko Hevery <misko@hevery.com>
Date: Wed, 7 Dec 2016 21:41:27 -0800
Subject: [PATCH] feat: ngIf now supports else; saves condition to local var

NgIf syntax has been extended to support else clause to display template
when the condition is false. In addition the condition value can now
be stored in local variable, for later reuse. This is especially useful
when used with the `async` pipe.

Example:

```
<div *ngIf="userObservable | async; else loading; let user">
  Hello {{user.last}}, {{user.first}}!
</div>
<template #loading>Waiting...</template>
```

closes #13061
closes #13297
---
 .../@angular/common/src/directives/ng_if.ts   | 144 +++++++++++++++---
 .../common/test/directives/ng_if_spec.ts      |  72 +++++++++
 .../common/ngIf/ts/e2e_test/ngIf_spec.ts      |  72 +++++++++
 .../examples/common/ngIf/ts/module.ts         | 128 ++++++++++++++++
 .../language-service/test/test_data.ts        |   2 +-
 .../language-service/test/ts_plugin_spec.ts   |   2 +-
 tools/public_api_guard/common/index.d.ts      |   4 +-
 7 files changed, 402 insertions(+), 22 deletions(-)
 create mode 100644 modules/@angular/examples/common/ngIf/ts/e2e_test/ngIf_spec.ts
 create mode 100644 modules/@angular/examples/common/ngIf/ts/module.ts

diff --git a/modules/@angular/common/src/directives/ng_if.ts b/modules/@angular/common/src/directives/ng_if.ts
index 9d8f42f36a..ddecc54d06 100644
--- a/modules/@angular/common/src/directives/ng_if.ts
+++ b/modules/@angular/common/src/directives/ng_if.ts
@@ -6,46 +6,152 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {Directive, Input, TemplateRef, ViewContainerRef} from '@angular/core';
+import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef} from '@angular/core';
+
 
 /**
- * Removes or recreates a portion of the DOM tree based on an {expression}.
+ * Conditionally includes a template based on the value of an `expression`.
  *
- * If the expression assigned to `ngIf` evaluates to a falsy value then the element
- * is removed from the DOM, otherwise a clone of the element is reinserted into the DOM.
+ * `ngIf` evaluates the `expression` and then renders the `then` or `else` template in its place
+ * when expression is thruthy or falsy respectively. Typically the:
+ *  - `then` template is the inline template of `ngIf` unless bound to a different value.
+ *  - `else` template is blank unless its bound.
  *
- * ### Example ([live demo](http://plnkr.co/edit/fe0kgemFBtmQOY31b4tw?p=preview)):
+ * # Most common usage
+ *
+ * The most common usage of the `ngIf` is to conditionally show the inline template as seen in this
+ * example:
+ * {@example common/ngIf/ts/module.ts region='NgIfSimple'}
+ *
+ * # Showing an alternative template using `else`
+ *
+ * If it is necessary to display a template when the `expression` is falsy use the `else` template
+ * binding as shown. Note that the `else` binding points to a `<template>` labeled `#elseBlock`.
+ * The template can be defined anywhere in the component view but is typically placed right after
+ * `ngIf` for readability.
+ *
+ * {@example common/ngIf/ts/module.ts region='NgIfElse'}
+ *
+ * # Using non-inlined `then` template
+ *
+ * Usually the `then` template is the inlined template of the `ngIf`, but it can be changed using
+ * a binding (just like `else`). Because `then` and `else` are bindings, the template references can
+ * change at runtime as shown in thise example.
+ *
+ * {@example common/ngIf/ts/module.ts region='NgIfThenElse'}
+ *
+ * # Storing conditional result in a variable
+ *
+ * A common patter is that we need to show a set of properties from the same object. if the
+ * object is undefined, then we have to use the safe-traversal-operator `?.` to guard against
+ * dereferencing a `null` value. This is especially the case when waiting on async data such as
+ * when using the `async` pipe as shown in folowing example:
  *
  * ```
- * <div *ngIf="errorCount > 0" class="error">
- *   <!-- Error message displayed when the errorCount property in the current context is greater
- * than 0. -->
- *   {{errorCount}} errors detected
- * </div>
+ * Hello {{ (userStream|async)?.last }}, {{ (userStream|async)?.first }}!
  * ```
  *
+ * There are several inefficiencies in the above example.
+ *  - We create multiple subscriptions on the `userStream`. One for each `async` pipe, or two
+ *    as shown in the example above.
+ *  - We can not display an alternative screen while waiting for the data to arrive asynchronously.
+ *  - We have to use the safe-traversal-operator `?.` to access properties, which is cumbersome.
+ *  - We have to place the `async` pipe in parenthesis.
+ *
+ * A better way to do this is to use `ngIf` and store the result of the condition in a local
+ * variable as shown in the the example below:
+ *
+ * {@example common/ngIf/ts/module.ts region='NgIfLet'}
+ *
+ * Notice that:
+ *  - We use only one `async` pipe and hence only one subscription gets created.
+ *  - `ngIf` stores the result of the `userStream|async` in the local variable `user`.
+ *  - The local `user` can than be bound repeatedly in a more efficient way.
+ *  - No need to use the safe-traversal-operator `?.` to access properties as `ngIf` will only
+ *    display the data if `userStream` returns a value.
+ *  - We can display an alternative template while waiting for the data.
+ *
  * ### Syntax
  *
+ * Simple form:
  * - `<div *ngIf="condition">...</div>`
  * - `<div template="ngIf condition">...</div>`
- * - `<template [ngIf]="condition"><div>...</div></template>`
+ * - `<ng-container [ngIf]="condition"><div>...</div></ng-container>`
+ *
+ * Form with an else block:
+ * ```
+ * <div *ngIf="condition; else elseBlock">...</div>
+ * <template #elseBlock>...</template>
+ * ```
+ *
+ * Form with a `then` and `else` block:
+ * ```
+ * <div *ngIf="condition; then thenBlock else elseBlock"></div>
+ * <template #thenBlock>...</template>
+ * <template #elseBlock>...</template>
+ * ```
+ *
+ * Form with storing the value locally:
+ * ```
+ * <div *ngIf="condition; else elseBlock; let value">{{value}}</div>
+ * <template #elseBlock>...</template>
+ * ```
  *
  * @stable
  */
 @Directive({selector: '[ngIf]'})
 export class NgIf {
-  private _hasView = false;
+  private _context: NgIfContext = new NgIfContext();
+  private _thenTemplateRef: TemplateRef<NgIfContext> = null;
+  private _elseTemplateRef: TemplateRef<NgIfContext> = null;
+  private _thenViewRef: EmbeddedViewRef<NgIfContext> = null;
+  private _elseViewRef: EmbeddedViewRef<NgIfContext> = null;
 
-  constructor(private _viewContainer: ViewContainerRef, private _template: TemplateRef<Object>) {}
+  constructor(private _viewContainer: ViewContainerRef, templateRef: TemplateRef<NgIfContext>) {
+    this._thenTemplateRef = templateRef;
+  }
 
   @Input()
   set ngIf(condition: any) {
-    if (condition && !this._hasView) {
-      this._hasView = true;
-      this._viewContainer.createEmbeddedView(this._template);
-    } else if (!condition && this._hasView) {
-      this._hasView = false;
-      this._viewContainer.clear();
+    this._context.$implicit = condition;
+    this._updateView();
+  }
+
+  @Input()
+  set ngIfThen(templateRef: TemplateRef<NgIfContext>) {
+    this._thenTemplateRef = templateRef;
+    this._thenViewRef = null;  // clear previous view if any.
+    this._updateView();
+  }
+
+  @Input()
+  set ngIfElse(templateRef: TemplateRef<NgIfContext>) {
+    this._elseTemplateRef = templateRef;
+    this._elseViewRef = null;  // clear previous view if any.
+    this._updateView();
+  }
+
+  private _updateView() {
+    if (this._context.$implicit) {
+      if (!this._thenViewRef) {
+        this._viewContainer.clear();
+        this._elseViewRef = null;
+        if (this._thenTemplateRef) {
+          this._thenViewRef =
+              this._viewContainer.createEmbeddedView(this._thenTemplateRef, this._context);
+        }
+      }
+    } else {
+      if (!this._elseViewRef) {
+        this._viewContainer.clear();
+        this._thenViewRef = null;
+        if (this._elseTemplateRef) {
+          this._elseViewRef =
+              this._viewContainer.createEmbeddedView(this._elseTemplateRef, this._context);
+        }
+      }
     }
   }
 }
+
+export class NgIfContext { public $implicit: any = null; }
diff --git a/modules/@angular/common/test/directives/ng_if_spec.ts b/modules/@angular/common/test/directives/ng_if_spec.ts
index 39c30a6422..a05ecd4882 100644
--- a/modules/@angular/common/test/directives/ng_if_spec.ts
+++ b/modules/@angular/common/test/directives/ng_if_spec.ts
@@ -153,6 +153,78 @@ export function main() {
          expect(getDOM().hasClass(getDOM().querySelector(fixture.nativeElement, 'span'), 'foo'))
              .toBe(true);
        }));
+
+    describe('else', () => {
+      it('should support else', async(() => {
+           const template = '<div>' +
+               '<span *ngIf="booleanCondition; else elseBlock">TRUE</span>' +
+               '<template #elseBlock>FALSE</template>' +
+               '</div>';
+
+           fixture = createTestComponent(template);
+
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('TRUE');
+
+           getComponent().booleanCondition = false;
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('FALSE');
+         }));
+
+      it('should support then and else', async(() => {
+           const template = '<div>' +
+               '<span *ngIf="booleanCondition; then thenBlock; else elseBlock">IGNORE</span>' +
+               '<template #thenBlock>THEN</template>' +
+               '<template #elseBlock>ELSE</template>' +
+               '</div>';
+
+           fixture = createTestComponent(template);
+
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('THEN');
+
+           getComponent().booleanCondition = false;
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('ELSE');
+         }));
+
+      it('should support dynamic else', async(() => {
+           const template = '<div>' +
+               '<span *ngIf="booleanCondition; else nestedBooleanCondition ? b1 : b2">TRUE</span>' +
+               '<template #b1>FALSE1</template>' +
+               '<template #b2>FALSE2</template>' +
+               '</div>';
+
+           fixture = createTestComponent(template);
+
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('TRUE');
+
+           getComponent().booleanCondition = false;
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('FALSE1');
+
+           getComponent().nestedBooleanCondition = false;
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('FALSE2');
+         }));
+
+      it('should support binding to variable', async(() => {
+           const template = '<div>' +
+               '<span *ngIf="booleanCondition; else elseBlock; let v">{{v}}</span>' +
+               '<template #elseBlock let-v>{{v}}</template>' +
+               '</div>';
+
+           fixture = createTestComponent(template);
+
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('true');
+
+           getComponent().booleanCondition = false;
+           fixture.detectChanges();
+           expect(fixture.nativeElement).toHaveText('false');
+         }));
+    });
   });
 }
 
diff --git a/modules/@angular/examples/common/ngIf/ts/e2e_test/ngIf_spec.ts b/modules/@angular/examples/common/ngIf/ts/e2e_test/ngIf_spec.ts
new file mode 100644
index 0000000000..d2648be31c
--- /dev/null
+++ b/modules/@angular/examples/common/ngIf/ts/e2e_test/ngIf_spec.ts
@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {$, ExpectedConditions, browser, by, element} from 'protractor';
+import {verifyNoBrowserErrors} from '../../../../_common/e2e_util';
+
+function waitForElement(selector: string) {
+  const EC = ExpectedConditions;
+  // Waits for the element with id 'abc' to be present on the dom.
+  browser.wait(EC.presenceOf($(selector)), 20000);
+}
+
+describe('ngIf', () => {
+  const URL = 'common/ngIf/ts/';
+  afterEach(verifyNoBrowserErrors);
+
+  describe('ng-if-simple', () => {
+    var comp = 'ng-if-simple'
+    it('should hide/show content', () => {
+      browser.get(URL);
+      waitForElement(comp);
+      expect(element.all(by.css(comp)).get(0).getText()).toEqual('hide show = true\nText to show');
+      element(by.css(comp + ' button')).click();
+      expect(element.all(by.css(comp)).get(0).getText()).toEqual('show show = false');
+    });
+  });
+
+  describe('ng-if-else', () => {
+    var comp = 'ng-if-else'
+    it('should hide/show content', () => {
+      browser.get(URL);
+      waitForElement(comp);
+      expect(element.all(by.css(comp)).get(0).getText()).toEqual('hide show = true\nText to show');
+      element(by.css(comp + ' button')).click();
+      expect(element.all(by.css(comp)).get(0).getText())
+          .toEqual('show show = false\nAlternate text while primary text is hidden');
+    });
+  });
+
+  describe('ng-if-then-else', () => {
+    var comp = 'ng-if-then-else'
+    it('should hide/show content', () => {
+      browser.get(URL);
+      waitForElement(comp);
+      expect(element.all(by.css(comp)).get(0).getText())
+          .toEqual('hide Switch Primary show = true\nPrimary text to show');
+      element.all(by.css(comp + ' button')).get(1).click();
+      expect(element.all(by.css(comp)).get(0).getText())
+          .toEqual('hide Switch Primary show = true\nSecondary text to show');
+      element.all(by.css(comp + ' button')).get(0).click();
+      expect(element.all(by.css(comp)).get(0).getText())
+          .toEqual('show Switch Primary show = false\nAlternate text while primary text is hidden');
+    });
+  });
+
+  describe('ng-if-let', () => {
+    var comp = 'ng-if-let'
+    it('should hide/show content', () => {
+      browser.get(URL);
+      waitForElement(comp);
+      expect(element.all(by.css(comp)).get(0).getText())
+          .toEqual('Next User\nWaiting... (user is null)');
+      element(by.css(comp + ' button')).click();
+      expect(element.all(by.css(comp)).get(0).getText()).toEqual('Next User\nHello Smith, John!');
+    });
+  });
+});
diff --git a/modules/@angular/examples/common/ngIf/ts/module.ts b/modules/@angular/examples/common/ngIf/ts/module.ts
new file mode 100644
index 0000000000..2eff3c6258
--- /dev/null
+++ b/modules/@angular/examples/common/ngIf/ts/module.ts
@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Component, NgModule, OnInit, TemplateRef, ViewChild} from '@angular/core';
+import {BrowserModule} from '@angular/platform-browser';
+import {Subject} from 'rxjs/Subject';
+
+
+// #docregion NgIfSimple
+@Component({
+  selector: 'ng-if-simple',
+  template: `
+    <button (click)="show = !show">{{show ? 'hide' : 'show'}}</button>
+    show = {{show}}
+    <br>
+    <div *ngIf="show">Text to show</div>
+`
+})
+class NgIfSimple {
+  show: boolean = true;
+}
+// #enddocregion
+
+// #docregion NgIfElse
+@Component({
+  selector: 'ng-if-else',
+  template: `
+    <button (click)="show = !show">{{show ? 'hide' : 'show'}}</button>
+    show = {{show}}
+    <br>
+    <div *ngIf="show; else elseBlock">Text to show</div>
+    <template #elseBlock>Alternate text while primary text is hidden</template>
+`
+})
+class NgIfElse {
+  show: boolean = true;
+}
+// #enddocregion
+
+// #docregion NgIfThenElse
+@Component({
+  selector: 'ng-if-then-else',
+  template: `
+    <button (click)="show = !show">{{show ? 'hide' : 'show'}}</button>
+    <button (click)="switchPrimary()">Switch Primary</button>
+    show = {{show}}
+    <br>
+    <div *ngIf="show; then thenBlock; else elseBlock">this is ignored</div>
+    <template #primaryBlock>Primary text to show</template>
+    <template #secondaryBlock>Secondary text to show</template>
+    <template #elseBlock>Alternate text while primary text is hidden</template>
+`
+})
+class NgIfThenElse implements OnInit {
+  thenBlock: TemplateRef<any> = null;
+  show: boolean = true;
+
+  @ViewChild('primaryBlock')
+  primaryBlock: TemplateRef<any> = null;
+  @ViewChild('secondaryBlock')
+  secondaryBlock: TemplateRef<any> = null;
+
+  switchPrimary() {
+    this.thenBlock = this.thenBlock === this.primaryBlock ? this.secondaryBlock : this.primaryBlock;
+  }
+
+  ngOnInit() { this.thenBlock = this.primaryBlock; }
+}
+// #enddocregion
+
+// #docregion NgIfLet
+@Component({
+  selector: 'ng-if-let',
+  template: `
+    <button (click)="nextUser()">Next User</button>
+    <br>
+    <div *ngIf="userObservable | async; else loading; let user">
+      Hello {{user.last}}, {{user.first}}!
+    </div>
+    <template #loading let-user>Waiting... (user is {{user|json}})</template>
+`
+})
+class NgIfLet {
+  userObservable = new Subject<{first: string, last: string}>();
+  first = ['John', 'Mike', 'Mary', 'Bob'];
+  firstIndex = 0;
+  last = ['Smith', 'Novotny', 'Angular'];
+  lastIndex = 0;
+
+  nextUser() {
+    var first = this.first[this.firstIndex++];
+    if (this.firstIndex >= this.first.length) this.firstIndex = 0;
+    var last = this.last[this.lastIndex++];
+    if (this.lastIndex >= this.last.length) this.lastIndex = 0;
+    this.userObservable.next({first, last});
+  }
+}
+// #enddocregion
+
+
+@Component({
+  selector: 'example-app',
+  template: `
+    <ng-if-simple></ng-if-simple>
+    <hr>
+    <ng-if-else></ng-if-else>
+    <hr>
+    <ng-if-then-else></ng-if-then-else>
+    <hr>
+    <ng-if-let></ng-if-let>
+    <hr>
+`
+})
+class ExampleApp {
+}
+
+@NgModule({
+  imports: [BrowserModule],
+  declarations: [ExampleApp, NgIfSimple, NgIfElse, NgIfThenElse, NgIfLet],
+  bootstrap: [ExampleApp]
+})
+export class AppModule {
+}
diff --git a/modules/@angular/language-service/test/test_data.ts b/modules/@angular/language-service/test/test_data.ts
index 7e4aded2a0..85d37c4022 100644
--- a/modules/@angular/language-service/test/test_data.ts
+++ b/modules/@angular/language-service/test/test_data.ts
@@ -213,7 +213,7 @@ export class UnknownTrackBy {
     'ng-if-cases.ts': `
 import {Component} from '@angular/core';
 
-@Component({template: '<div ~{implicit}*ngIf="show; let l"~{implicit-end}>Showing now!</div>'})
+@Component({template: '<div ~{implicit}*ngIf="show; let l=unknown"~{implicit-end}>Showing now!</div>'})
 export class ShowIf {
   show = false;
 }
diff --git a/modules/@angular/language-service/test/ts_plugin_spec.ts b/modules/@angular/language-service/test/ts_plugin_spec.ts
index 3aec4dff9b..7dabc12168 100644
--- a/modules/@angular/language-service/test/ts_plugin_spec.ts
+++ b/modules/@angular/language-service/test/ts_plugin_spec.ts
@@ -186,7 +186,7 @@ describe('plugin', () => {
         expectSemanticError('app/ng-if-cases.ts', locationMarker, message);
       }
       it('should report an implicit context reference', () => {
-        expectError('implicit', 'The template context does not have an implicit value');
+        expectError('implicit', "The template context does not defined a member called 'unknown'");
       });
     });
   });
diff --git a/tools/public_api_guard/common/index.d.ts b/tools/public_api_guard/common/index.d.ts
index 223641ddb2..6003a60e65 100644
--- a/tools/public_api_guard/common/index.d.ts
+++ b/tools/public_api_guard/common/index.d.ts
@@ -130,7 +130,9 @@ export declare class NgFor implements DoCheck, OnChanges {
 /** @stable */
 export declare class NgIf {
     ngIf: any;
-    constructor(_viewContainer: ViewContainerRef, _template: TemplateRef<Object>);
+    ngIfElse: TemplateRef<NgIfContext>;
+    ngIfThen: TemplateRef<NgIfContext>;
+    constructor(_viewContainer: ViewContainerRef, templateRef: TemplateRef<NgIfContext>);
 }
 
 /** @experimental */