docs(template-syntax): ngClass and ngStyle binding examples not horrible (#3076)

closes #3072, whose criticism prompted these changes.

Author: wardbell

public/docs/_examples/template-syntax/ts/app/app.component.html

@@ -409,15 +409,23 @@ <h3>Result: {{currentHero.firstName}}</h3>
 <!-- NgClass binding -->
 <hr><h2 id="ngClass">NgClass Binding</h2>
 
-<p>setClasses returns {{setClasses() | json}}</p>
+<p>currentClasses returns {{currentClasses | json}}</p>
 <!-- #docregion NgClass-1 -->
-<div [ngClass]="setClasses()">This div is saveable and special</div>
+<div [ngClass]="currentClasses">This div is initially saveable, unchanged, and special</div>
 <!-- #enddocregion NgClass-1 -->
-<div [ngClass]="setClasses()" #classDiv>
-  After setClasses(), the classes are "{{classDiv.className}}"
-</div>
 
 <!-- not used in chapter -->
+<br>
+<label>saveable   <input type="checkbox" [(ngModel)]="canSave"></label> |
+<label>modified: <input type="checkbox" [value]="!isUnchanged" (change)="isUnchanged=!isUnchanged"></label> |
+<label>special:   <input type="checkbox" [(ngModel)]="isSpecial"></label>
+<button (click)="setCurrentClasses()">Refresh currentClasses</button>
+<br><br>
+<div [ngClass]="currentClasses">
+  This div should be {{ canSave ? "": "not"}} saveable,
+                  {{ isUnchanged ? "unchanged" : "modified" }} and,
+                  {{ isSpecial ? "": "not"}} special after clicking "refresh".</div>
+<br><br>
 
 <div [ngClass]="isSpecial ? 'special' : ''">This div is special</div>
 
@@ -429,38 +437,32 @@ <h3>Result: {{currentHero.firstName}}</h3>
 <!-- NgStyle binding -->
 <hr><h2 id="ngStyle">NgStyle Binding</h2>
 
-<!-- #docregion NgStyle -->
-<div>
-  <p [ngStyle]="setStyle()" #styleP>Change style of this text!</p>
-
-  <label>Italic: <input type="checkbox" [(ngModel)]="isItalic"></label> |
-  <label>Bold: <input type="checkbox" [(ngModel)]="isBold"></label> |
-  <label>Size: <input type="text" [(ngModel)]="fontSize"></label>
-
-  <p>Style set to: <code>'{{styleP.style.cssText}}'</code></p>
-</div>
-<!-- #enddocregion NgStyle -->
-
 <!-- #docregion NgStyle-1 -->
 <div [style.font-size]="isSpecial ? 'x-large' : 'smaller'" >
   This div is x-large.
 </div>
 <!-- #enddocregion NgStyle-1 -->
 
-<h3>Use setStyles() - CSS property names</h3>
-<p>setStyles returns {{setStyles() | json}}</p>
+<h3>[ngStyle] binding to `currentStyles` - CSS property names</h3>
+<p>currentStyles returns {{currentStyles | json}}</p>
 <!-- #docregion NgStyle-2 -->
-<div [ngStyle]="setStyles()">
-  This div is italic, normal weight, and extra large (24px).
+<div [ngStyle]="currentStyles">
+  This div is initially italic, normal weight, and extra large (24px).
 </div>
 <!-- #enddocregion NgStyle-2 -->
-<p>After setStyles(), the DOM confirms that the styles are
-  <span [ngStyle]="setStyles()" #styleDiv>
-    {{getStyles(styleDiv)}}
-  </span>.
-</p>
 
 <!-- not used in chapter -->
+<br>
+<label>italic: <input type="checkbox" [(ngModel)]="canSave"></label> |
+<label>normal: <input type="checkbox" [(ngModel)]="isUnchanged"></label> |
+<label>xlarge: <input type="checkbox" [(ngModel)]="isSpecial"></label>
+<button (click)="setCurrentStyles()">Refresh currentStyles</button>
+<br><br>
+<div [ngStyle]="currentStyles">
+  This div should be {{ canSave ? "italic": "plain"}},
+                  {{ isUnchanged ? "normal weight" : "bold" }} and,
+                  {{ isSpecial ? "extra large": "normal size"}} after clicking "refresh".</div>
+<br>
 
 <a class="to-toc" href="#toc">top</a>
 

public/docs/_examples/template-syntax/ts/app/app.component.ts

@@ -25,6 +25,8 @@ export class AppComponent implements AfterViewInit, OnInit {
 
   ngOnInit() {
     this.refreshHeroes();
+    this.setCurrentClasses();
+    this.setCurrentStyles();
   }
 
   ngAfterViewInit() {
@@ -56,14 +58,10 @@ export class AppComponent implements AfterViewInit, OnInit {
 
   title = 'Template Syntax';
 
-  // DevMode memoization fields
-  private priorClasses: {};
-  private _priorStyles: {};
-
   getStyles(el: Element) {
     let styles = window.getComputedStyle(el);
     let showStyles = {};
-    for (let p in this.setStyles()) {
+    for (let p in this.currentStyles) { // only interested in these styles
       showStyles[p] = styles[p];
     }
     return JSON.stringify(showStyles);
@@ -141,58 +139,29 @@ export class AppComponent implements AfterViewInit, OnInit {
   }
 
   // #docregion setClasses
-  setClasses() {
-    let classes =  {
-      saveable: this.canSave,      // true
-      modified: !this.isUnchanged, // false
-      special: this.isSpecial,     // true
+  currentClasses: {};
+  setCurrentClasses() {
+    // CSS classes: added/removed per current state of component properties
+    this.currentClasses =  {
+      saveable: this.canSave,
+      modified: !this.isUnchanged,
+      special:  this.isSpecial
     };
-    // #enddocregion setClasses
-    // compensate for DevMode (sigh)
-    if (JSON.stringify(classes) === JSON.stringify(this.priorClasses)) {
-       return this.priorClasses;
-    }
-    this.priorClasses = classes;
-    // #docregion setClasses
-    return classes;
   }
   // #enddocregion setClasses
 
-
   // #docregion setStyles
-  setStyles() {
-    let styles = {
-      // CSS property names
-      'font-style':  this.canSave      ? 'italic' : 'normal',  // italic
-      'font-weight': !this.isUnchanged ? 'bold'   : 'normal',  // normal
-      'font-size':   this.isSpecial    ? '24px'   : '8px',     // 24px
+  currentStyles: {};
+  setCurrentStyles() {
+    this.currentStyles = {
+      // CSS styles: set per current state of component properties
+      'font-style':  this.canSave      ? 'italic' : 'normal',
+      'font-weight': !this.isUnchanged ? 'bold'   : 'normal',
+      'font-size':   this.isSpecial    ? '24px'   : '12px'
     };
-    // #enddocregion setStyles
-    // compensate for DevMode (sigh)
-    if (JSON.stringify(styles) === JSON.stringify(this._priorStyles)) {
-       return this._priorStyles;
-    }
-    this._priorStyles = styles;
-    // #docregion setStyles
-    return styles;
   }
   // #enddocregion setStyles
 
-  // #docregion NgStyle
-  isItalic = false;
-  isBold = false;
-  fontSize: string = 'large';
-  fontSizePx: number | string = 14;
-
-  setStyle() {
-    return {
-      'font-style': this.isItalic ? 'italic' : 'normal',
-      'font-weight': this.isBold ? 'bold' : 'normal',
-      'font-size': this.fontSize
-    };
-  }
-  // #enddocregion NgStyle
-
   toeChoice = '';
   toeChooser(picker: HTMLFieldSetElement) {
     let choices = picker.children;
@@ -202,7 +171,6 @@ export class AppComponent implements AfterViewInit, OnInit {
     }
   }
 
-
   // #docregion trackByHeroes
   trackByHeroes(index: number, hero: Hero) { return hero.id; }
   // #enddocregion trackByHeroes

public/docs/_examples/template-syntax/ts/template-syntax.css

@@ -6,7 +6,8 @@ img {height: 100px;}
 .parent-div {margin-top: 1em; font-weight: bold}
 .special {font-weight:bold; font-size: x-large}
 .bad {color: red;}
-.curly {font-family: "Brush Script MT"}
+.saveable {color: limegreen;}
+.curly, .modified {font-family: "Brush Script MT"}
 .toe {margin-left: 1em; font-style: italic;}
 little-hero {color:blue; font-size: smaller; background-color: Turquoise }
-.to-toc {margin-top: 10px; display: block}
+.to-toc {margin-top: 10px; display: block}

public/docs/ts/latest/guide/template-syntax.jade

@@ -997,15 +997,22 @@ figure.image-display
   The `NgClass` directive may be the better choice
   when we want to add or remove *many* CSS classes at the same time.
 
-  A good way to apply `NgClass` is by binding it to a key:value control !{__objectAsMap}. Each key of the object is a CSS class name; its value is `true` if the class should be added, `false` if it should be removed.
+  A good way to apply `NgClass` is by binding it to a key:value control !{__objectAsMap}. 
+  Each key of the object is a CSS class name; its value is `true` if the class should be added, 
+  `false` if it should be removed.
 
 :marked
-  Consider a component method such as `setClasses` that manages the state of three CSS classes:
+  Consider a 
+  `setCurrentClasses` component method that sets a component property, `currentClasses`
+  with an object that adds or removes three classes based on the 
+  `true`/`false` state of three other component propertes:
 +makeExample('template-syntax/ts/app/app.component.ts', 'setClasses')(format=".")
 :marked
-  Now we can add an `NgClass` property binding that calls `setClasses`
-  and sets the element's classes accordingly:
+  Adding an `NgClass` property binding to `currentClasses` sets the element's classes accordingly:  
 +makeExample('template-syntax/ts/app/app.component.html', 'NgClass-1')(format=".")
+.l-sub-section
+  :marked
+    It's up to you to call `setCurrentClassess()`, both initially and when the dependent properties change.
 
 <a id="ngStyle"></a>
 .l-main-section
@@ -1023,12 +1030,15 @@ figure.image-display
   We apply `NgStyle` by binding it to a key:value control !{__objectAsMap}.
   Each key of the object is a style name; its value is whatever is appropriate for that style.
 
-  Consider a component method such as `setStyles` that returns an object defining three styles:
+  Consider a `setCurrentStyles` component method that sets a component property, `currentStyles`
+  with an object that defines three styles, based on the state of three other component propertes:
 +makeExample('template-syntax/ts/app/app.component.ts', 'setStyles')(format=".")
 :marked
-  Now we just add an `NgStyle` property binding that calls `setStyles`
-  and sets the element's styles accordingly:
+  Adding an `NgStyle` property binding to `currentStyles` sets the element's styles accordingly:
 +makeExample('template-syntax/ts/app/app.component.html', 'NgStyle-2')(format=".")
+.l-sub-section
+  :marked
+    It's up to you to call `setCurrentStyles()`, both initially and when the dependent properties change.
 
 <a id="ngIf"></a>
 .l-main-section