docs(guide): add Dart forms guide

closes #409

public/docs/_examples/forms/dart/lib/hero.dart

@@ -1,3 +1,4 @@
+// #docregion all
 library hero_form.hero;
 
 class Hero {
@@ -6,8 +7,16 @@ class Hero {
   String power;
   String alterEgo;
 
-  Hero(this.number, this.name, this.power, {this.alterEgo});
+  Hero(this.number, this.name, this.power, [this.alterEgo]);
 
-  Map toJson() =>
-      {'number': number, 'name': name, 'power': power, 'alterEgo': alterEgo};
+  String toString() => '$number: $name ($alterEgo). Super power: $power';
+}
+// #enddocregion all
+
+main() {
+  // #docregion newhero
+  var myHero = new Hero(
+      42, 'SkyDog', 'Fetch any object at any distance', 'Leslie Rollover');
+  print('My hero is ${myHero.name}.'); // "My hero is SkyDog."
+  // #enddocregion newhero
 }

public/docs/_examples/forms/dart/lib/hero_form_component.dart

@@ -1,3 +1,6 @@
+// #docplaster
+// #docregion
+// #docregion no-todo
 library hero_form.hero_form_component;
 
 import 'package:angular2/angular2.dart';
@@ -10,18 +13,25 @@ const List<String> _powers = const [
   'Weather Changer'
 ];
 
-@Component(selector: 'hero-form')
-@View(
+@Component(
+    selector: 'hero-form',
     templateUrl: 'hero_form_component.html',
+    // Soon specifying directives here will be unnecessary.
     directives: const [CORE_DIRECTIVES, FORM_DIRECTIVES])
 class HeroFormComponent {
   List<String> get powers => _powers;
-
+// #docregion submitted
   bool submitted = false;
-
-  Hero model = new Hero(18, 'Dr IQ', _powers[0], alterEgo: 'Chuck Overstreet');
+// #enddocregion submitted
+  Hero model = new Hero(18, 'Dr IQ', _powers[0], 'Chuck Overstreet');
+// #docregion submitted
+// #enddocregion no-todo
+  // TODO: Remove this when we're done
+  String get diagnostic => 'DIAGNOSTIC: $model';
+// #docregion no-todo
 
   onSubmit() {
     submitted = true;
   }
+// #enddocregion submitted
 }

public/docs/_examples/forms/dart/lib/hero_form_component.html

@@ -1,42 +1,67 @@
-<div class="container" [hidden]="submitted">
-    {{model.toJson()}}
+<!-- #docplaster ... all of the form ... -->
+<!-- #docregion -->
+<div class="container">
+  <!-- #docregion edit-div -->
+  <div [hidden]="submitted">
     <h1>Hero Form</h1>
+	  <!-- #docregion ng-submit -->
     <form (ng-submit)="onSubmit()" #hf="form">
-        <div class="form-group">
-            <label for="name">Name</label>
-            <input type="text" class="form-control" required [(ng-model)]="model.name" ng-control="name" #name="form"  >
-            <div [hidden]="name.valid" class="alert alert-danger">
-                Name is required
-            </div>
+    <!-- #enddocregion ng-submit -->
+    <!-- #enddocregion edit-div -->
+      <div class="form-group">
+        <label for="name">Name</label>
+	      <!-- #docregion name-with-error-msg -->
+        <input type="text" class="form-control" required
+               [(ng-model)]="model.name"
+               ng-control="name" #name="form" >
+        <div [hidden]="name.valid" class="alert alert-danger">
+          Name is required
         </div>
-        <div class="form-group">
-            <label for="alterEgo">Alter Ego</label>
-            <input type="text" class="form-control" [(ng-model)]="model.alterEgo" ng-control="alterEgo" >
-        </div>
-        <div class="form-group">
-            <label for="power">Hero Power</label>
-            <select class="form-control" required [(ng-model)]="model.power" ng-control="power" >
-                <option *ng-for="#p of powers" [value]="p">{{p}}</option>
-            </select>
-        </div>
-        <button type="submit" class="btn btn-default" [disabled]="!hf.form.valid">Submit</button>
-    </form>
-</div>
+	      <!-- #enddocregion name-with-error-msg -->
+      </div>
 
-<div [hidden]="!submitted">
+      <div class="form-group">
+        <label for="alterEgo">Alter Ego</label>
+        <input type="text" class="form-control"
+               [(ng-model)]="model.alterEgo"
+               ng-control="alterEgo" >
+      </div>
+
+      <div class="form-group">
+        <label for="power">Hero Power</label>
+        <select class="form-control" required
+                [(ng-model)]="model.power"
+                ng-control="power" >
+          <option *ng-for="#p of powers" [value]="p">{{p}}</option>
+        </select>
+      </div>
+
+	    <!-- #docregion submit-button -->
+      <button type="submit" class="btn btn-default"
+              [disabled]="!hf.form.valid">Submit</button>
+	    <!-- #enddocregion submit-button -->
+  <!-- #docregion edit-div -->
+    </form>
+  </div>
+  <!-- #enddocregion edit-div -->
+
+  <!-- #docregion submitted -->
+  <div [hidden]="!submitted">
     <h2>You submitted the following:</h2>
     <div class="row">
-        <div class="col-xs-3">Name</div>
-        <div class="col-xs-9  pull-left">{{ model.name }}</div>
+      <div class="col-xs-3">Name</div>
+      <div class="col-xs-9  pull-left">{{ model.name }}</div>
     </div>
     <div class="row">
-        <div class="col-xs-3">Alter Ego</div>
-        <div class="col-xs-9 pull-left">{{ model.alterEgo }}</div>
+      <div class="col-xs-3">Alter Ego</div>
+      <div class="col-xs-9 pull-left">{{ model.alterEgo }}</div>
     </div>
     <div class="row">
-        <div class="col-xs-3">Power</div>
-        <div class="col-xs-9 pull-left">{{ model.power }}</div>
+      <div class="col-xs-3">Power</div>
+      <div class="col-xs-9 pull-left">{{ model.power }}</div>
     </div>
     <br>
     <button class="btn btn-default" (click)="submitted=false">Edit</button>
+  </div>
+  <!-- #enddocregion submitted -->
 </div>

public/docs/_examples/forms/dart/lib/hero_form_component_initial.dart

@@ -0,0 +1,7 @@
+// #docregion
+library hero_form.hero_form_component;
+
+import 'package:angular2/angular2.dart';
+
+@Component(selector: 'hero-form', template: 'Hero form will go here')
+class HeroFormComponent {}

public/docs/_examples/forms/dart/lib/hero_form_component_initial.html

@@ -0,0 +1,15 @@
+<!-- #docregion -->
+<div class="container">
+  <h1>Hero Form</h1>
+  <form>
+    <div class="form-group">
+      <label for="name">Name</label>
+      <input type="text" class="form-control" required>
+    </div>
+    <div class="form-group">
+      <label for="alterEgo">Alter Ego</label>
+      <input type="text" class="form-control">
+    </div>
+    <button type="submit" class="btn btn-default">Submit</button>
+  </form>
+</div>

public/docs/_examples/forms/dart/lib/hero_form_component_ngcontrol.html

@@ -0,0 +1,32 @@
+<!-- #docregion -->
+<div class="container">
+  <h1>Hero Form</h1>
+  <form>
+    <div class="form-group">
+      <label for="name">Name</label>
+      <!-- #docregion ng-control-1 -->
+      <input type="text" class="form-control" required
+             [(ng-model)]="model.name"
+             ng-control="name" >
+      <!-- #enddocregion ng-control-1 -->
+    </div>
+
+    <div class="form-group">
+      <label for="alterEgo">Alter Ego</label>
+      <input type="text" class="form-control"
+             [(ng-model)]="model.alterEgo"
+             ng-control="alterEgo" >
+    </div>
+
+    <div class="form-group">
+      <label for="power">Hero Power</label>
+      <select class="form-control" required
+              [(ng-model)]="model.power"
+              ng-control="power" >
+        <option *ng-for="#p of powers" [value]="p">{{p}}</option>
+      </select>
+    </div>
+
+    <button type="submit" class="btn btn-default">Submit</button>
+  </form>
+</div>

public/docs/_examples/forms/dart/lib/hero_form_component_ngmodel2.html

@@ -0,0 +1,30 @@
+<!-- #docregion -->
+<div class="container">
+  <h1>Hero Form</h1>
+  <form>
+	  <!-- #docregion ng-model-2 -->
+    {{diagnostic}}
+    <div class="form-group">
+      <label for="name">Name</label>
+      <input type="text" class="form-control" required
+             [(ng-model)]="model.name" >
+    </div>
+
+    <div class="form-group">
+      <label for="alterEgo">Alter Ego</label>
+      <input type="text" class="form-control"
+             [(ng-model)]="model.alterEgo">
+    </div>
+
+    <div class="form-group">
+      <label for="power">Hero Power</label>
+      <select class="form-control" required
+              [(ng-model)]="model.power">
+        <option *ng-for="#p of powers" [value]="p">{{p}}</option>
+      </select>
+    </div>
+	  <!-- #enddocregion ng-model-2 -->
+
+    <button type="submit" class="btn btn-default">Submit</button>
+  </form>
+</div>

public/docs/_examples/forms/dart/lib/hero_form_component_ngmodel_ngfor.html

@@ -0,0 +1,30 @@
+<!-- #docregion -->
+<div class="container">
+  <h1>Hero Form</h1>
+  <form>
+    <div class="form-group">
+	    <label for="name">Name</label>
+      <!-- #docregion ng-model-1 -->
+      <input type="text" class="form-control" required
+             [(ng-model)]="model.name" >
+      TODO: remove this: {{model.name}}
+      <!-- #enddocregion ng-model-1 -->
+    </div>
+
+    <div class="form-group">
+      <label for="alterEgo">Alter Ego</label>
+      <input type="text" class="form-control">
+    </div>
+
+	  <!-- #docregion powers -->
+    <div class="form-group">
+      <label for="power">Hero Power</label>
+      <select class="form-control" required>
+        <option *ng-for="#p of powers" [value]="p">{{p}}</option>
+      </select>
+    </div>
+	  <!-- #enddocregion powers -->
+
+    <button type="submit" class="btn btn-default">Submit</button>
+  </form>
+</div>

public/docs/_examples/forms/dart/lib/hero_form_component_ngmodelchange.html

@@ -0,0 +1,31 @@
+<!-- #docregion -->
+<div class="container">
+  <h1>Hero Form</h1>
+  <form>
+    <div class="form-group">
+      <label for="name">Name</label>
+	    <!-- #docregion ng-model-3 -->
+      <input type="text" class="form-control" required
+             [ng-model]="model.name"
+             (ng-model-change)="model.name = $event" >
+      TODO: remove this: {{model.name}}
+	    <!-- #enddocregion ng-model-3 -->
+    </div>
+
+    <div class="form-group">
+      <label for="alterEgo">Alter Ego</label>
+      <input type="text" class="form-control"
+             [(ng-model)]="model.alterEgo">
+    </div>
+
+    <div class="form-group">
+      <label for="power">Hero Power</label>
+      <select class="form-control" required
+              [(ng-model)]="model.power">
+        <option *ng-for="#p of powers" [value]="p">{{p}}</option>
+      </select>
+    </div>
+
+    <button type="submit" class="btn btn-default">Submit</button>
+  </form>
+</div>

public/docs/_examples/forms/dart/lib/hero_form_component_spy.html

@@ -0,0 +1,33 @@
+<!-- #docregion -->
+<div class="container">
+  <h1>Hero Form</h1>
+  <form>
+    <div class="form-group">
+      <label for="name">Name</label>
+      <!-- #docregion ng-control-2 -->
+      <input type="text" class="form-control" required
+             [(ng-model)]="model.name"
+             ng-control="name" #spy >
+      TODO: remove this: {{spy.className}}
+      <!-- #enddocregion ng-control-2 -->
+    </div>
+
+    <div class="form-group">
+      <label for="alterEgo">Alter Ego</label>
+      <input type="text" class="form-control"
+             [(ng-model)]="model.alterEgo"
+             ng-control="alterEgo" >
+    </div>
+
+    <div class="form-group">
+      <label for="power">Hero Power</label>
+      <select class="form-control" required
+              [(ng-model)]="model.power"
+              ng-control="power" >
+        <option *ng-for="#p of powers" [value]="p">{{p}}</option>
+      </select>
+    </div>
+
+    <button type="submit" class="btn btn-default">Submit</button>
+  </form>
+</div>

public/docs/_examples/forms/dart/pubspec.yaml

@@ -1,9 +1,11 @@
+# #docregion
 name: hero_form
 description: Form example
 version: 0.0.1
 dependencies:
-  angular2: 2.0.0-alpha.45
+  angular2: 2.0.0-alpha.47
   browser: ^0.10.0
 transformers:
 - angular2:
     entry_points: web/main.dart
+

public/docs/_examples/forms/dart/web/index.html

@@ -1,13 +1,24 @@
+<!-- #docplaster -->
+<!-- #docregion -->
+<!-- #docregion initial -->
 <!DOCTYPE html>
 <html>
-<head>
-    <title>Displaying Data</title>
+  <head>
+    <title>Hero Form</title>
+	  <!-- #enddocregion initial -->
+	  <!-- #docregion styles -->
+	  <!-- #docregion bootstrap-and-script -->
     <link rel="stylesheet" href="bootstrap.min.css">
+	  <!-- #enddocregion bootstrap-and-script -->
     <link rel="stylesheet" href="styles.css">
-    <script async src="main.dart" type="application/dart"></script>
-    <script async src="packages/browser/dart.js"></script>
-</head>
-<body>
-<hero-form></hero-form>
-</body>
+	  <!-- #enddocregion styles -->
+	  <!-- #docregion initial -->
+	  <!-- #docregion bootstrap-and-script -->
+    <script defer src="main.dart" type="application/dart"></script>
+    <script defer src="packages/browser/dart.js"></script>
+	  <!-- #enddocregion bootstrap-and-script -->
+  </head>
+  <body>
+    <hero-form>Loading...</hero-form>
+  </body>
 </html>

public/docs/_examples/forms/dart/web/main.dart

@@ -1,3 +1,4 @@
+// #docregion
 import 'package:angular2/bootstrap.dart';
 import 'package:hero_form/hero_form_component.dart';
 

public/docs/_examples/forms/dart/web/styles.css

@@ -1,6 +1,7 @@
+/* #docregion */
 .ng-valid[required] {
     border-left: 5px solid #42A948; /* green */
 }
-.ng-invalid {
+.ng-invalid, .ng-invalid:focus {
     border-left: 5px solid #a94442; /* red */
 }