docs(NgClass): update docs, add example

pkozlowski-opensource · pkozlowski-opensource · commit df09389df83b · 2015-10-10T11:42:25.000Z
Closes angular#4520
diff --git a/modules/angular2/src/core/directives/ng_class.ts b/modules/angular2/src/core/directives/ng_class.ts
@@ -12,23 +12,63 @@ import {Renderer} from 'angular2/src/core/render';
 import {StringMapWrapper, isListLikeIterable} from 'angular2/src/core/facade/collection';
 
 /**
- * Adds and removes CSS classes based on an {expression} value.
+ * The `NgClass` directive conditionally adds and removes CSS classes on an HTML element based on
+ * an expression's evaluation result.
  *
- * The result of expression is used to add and remove CSS classes using the following logic,
- * based on expression's value type:
- * - {string} - all the CSS classes (space - separated) are added
- * - {Array} - all the CSS classes (Array elements) are added
- * - {Object} - each key corresponds to a CSS class name while values
- * are interpreted as {boolean} expression. If a given expression
- * evaluates to {true} a corresponding CSS class is added - otherwise
- * it is removed.
+ * The result of an expression evaluation is interpreted differently depending on type of
+ * the expression evaluation result:
+ * - `string` - all the CSS classes listed in a string (space delimited) are added
+ * - `Array` - all the CSS classes (Array elements) are added
+ * - `Object` - each key corresponds to a CSS class name while values are interpreted as expressions
+ * evaluating to `Boolean`. If a given expression evaluates to `true` a corresponding CSS class
+ * is added - otherwise it is removed.
  *
- * # Example:
+ * While the `NgClass` directive can interpret expressions evaluating to `string`, `Array`
+ * or `Object`, the `Object`-based version is the most often used and has an advantage of keeping
+ * all the CSS class names in a template.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/a4YdtmWywhJ33uqfpPPn?p=preview)):
  *
  * ```
- * <div class="message" [ng-class]="{error: errorCount > 0}">
- *     Please check errors.
- * </div>
+ * import {Component, View, NgClass} from 'angular2/angular2';
+ *
+ * @Component({
+ *    selector: 'toggle-button',
+ *    inputs: ['isDisabled']
+ * })
+ * @View({
+ *   template: `
+ *      <div class="button" [ng-class]="{active: isOn, disabled: isDisabled}"
+ *          (click)="toggle(!isOn)">
+ *          Click me!
+ *      </div>`,
+ *   styles: [`
+ *     .button {
+ *       width: 120px;
+ *       border: medium solid black;
+ *     }
+ *
+ *     .active {
+ *       background-color: red;
+ *    }
+ *
+ *     .disabled {
+ *       color: gray;
+ *       border: medium solid gray;
+ *     }
+ *   `]
+ *   directives: [NgClass]
+ * })
+ * class ToggleButton {
+ *   isOn = false;
+ *   isDisabled = false;
+ *
+ *   toggle(newState) {
+ *     if (!this.isDisabled) {
+ *       this.isOn = newState;
+ *     }
+ *   }
+ * }
  * ```
  */
 @Directive({selector: '[ng-class]', inputs: ['rawClass: ng-class', 'initialClasses: class']})
