angular · mhevery · Dec 8, 2016 · Dec 8, 2016 · Dec 8, 2016 · Dec 9, 2016
diff --git 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`.
+ *
+ * `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.
+ *
+ * # 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.
  *
- * 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.
+ * {@example common/ngIf/ts/module.ts region='NgIfThenElse'}
  *
- * ### Example ([live demo](http://plnkr.co/edit/fe0kgemFBtmQOY31b4tw?p=preview)):
+ * # 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
@@ -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/compiler/src/template_parser/template_parser.ts b/modules/@angular/compiler/src/template_parser/template_parser.ts
@@ -685,7 +685,7 @@ class TemplateParseVisitor implements html.Visitor {
     }
     elementProps.forEach(prop => {
       this._reportError(
-          `Property binding ${prop.name} not used by any directive on an embedded template. Make sure that the property name is spelled correctly and all directives are listed in the "directives" section.`,
+          `Property binding ${prop.name} not used by any directive on an embedded template. Make sure that the property name is spelled correctly and all directives are listed in the "@NgModule.declarations".`,
              sourceSpan);
     });
   }
@@ -704,7 +704,7 @@ class TemplateParseVisitor implements html.Visitor {
     events.forEach(event => {
       if (isPresent(event.target) || !allDirectiveEvents.has(event.name)) {
         this._reportError(
-            `Event binding ${event.fullName} not emitted by any directive on an embedded template. Make sure that the event name is spelled correctly and all directives are listed in the "directives" section.`,
+            `Event binding ${event.fullName} not emitted by any directive on an embedded template. Make sure that the event name is spelled correctly and all directives are listed in the "@NgModule.declarations".`,
             event.sourceSpan);
       }
     });

diff --git a/modules/@angular/compiler/test/template_parser/template_parser_spec.ts b/modules/@angular/compiler/test/template_parser/template_parser_spec.ts
@@ -1586,9 +1586,9 @@ Parser Error: Unexpected token 'b' at column 3 in [a b] in TestComp@0:5 ("<div [
                        .toSummary();
                expect(() => parse('<template [a]="b" (e)="f"></template>', [dirA]))
                    .toThrowError(`Template parse errors:
-Event binding e not emitted by any directive on an embedded template. Make sure that the event name is spelled correctly and all directives are listed in the "directives" section. ("<template [a]="b" [ERROR ->](e)="f"></template>"): TestComp@0:18
+Event binding e not emitted by any directive on an embedded template. Make sure that the event name is spelled correctly and all directives are listed in the "@NgModule.declarations". ("<template [a]="b" [ERROR ->](e)="f"></template>"): TestComp@0:18
 Components on an embedded template: DirA ("[ERROR ->]<template [a]="b" (e)="f"></template>"): TestComp@0:0
-Property binding a not used by any directive on an embedded template. Make sure that the property name is spelled correctly and all directives are listed in the "directives" section. ("[ERROR ->]<template [a]="b" (e)="f"></template>"): TestComp@0:0`);
+Property binding a not used by any directive on an embedded template. Make sure that the property name is spelled correctly and all directives are listed in the "@NgModule.declarations". ("[ERROR ->]<template [a]="b" (e)="f"></template>"): TestComp@0:0`);
              });
 
           it('should not allow components or element bindings on inline embedded templates', () => {
@@ -1603,7 +1603,7 @@ Property binding a not used by any directive on an embedded template. Make sure
                     .toSummary();
             expect(() => parse('<div *a="b"></div>', [dirA])).toThrowError(`Template parse errors:
 Components on an embedded template: DirA ("[ERROR ->]<div *a="b"></div>"): TestComp@0:0
-Property binding a not used by any directive on an embedded template. Make sure that the property name is spelled correctly and all directives are listed in the "directives" section. ("[ERROR ->]<div *a="b"></div>"): TestComp@0:0`);
+Property binding a not used by any directive on an embedded template. Make sure that the property name is spelled correctly and all directives are listed in the "@NgModule.declarations". ("[ERROR ->]<div *a="b"></div>"): TestComp@0:0`);
           });
         });
 

diff --git a/modules/@angular/examples/README.md b/modules/@angular/examples/README.md
@@ -3,3 +3,32 @@
 This folder contains small example apps that get in-lined into our API docs.
 Each example contains tests for application behavior (as opposed to testing Angular's
 behavior) just like an Angular application developer would write.
+
+# Running the examples
+
+```
+# # execute the following command only when framework code changes
+./build.sh
+
+# run when test change
+./modules/@angular/examples/build.sh  
+
+# start server
+$(npm bin)/gulp serve-examples
+```
+
+navigate to [http://localhost:8001](http://localhost:8001)
+
+# Running the tests
+
+```
+ # run only when framework code changes
+./build.sh
+
+# run to compile tests and run them
+./modules/@angular/examples/test.sh
+```
+
+NOTE: sometimes the http server does not exits properly and it retans the `8001` port.
+ in such a case you can use `lsof -i:8001` to see which process it is and then use `kill` 
+ to remove it. (Or in single command: `lsof -i:8001 -t | xargs kill`)
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
@@ -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!');
+    });
+  });
+});