docs(dart): convert toh-3 to Dart

closes #1071

public/docs/_examples/toh-3/dart/lib/app_component.dart

@@ -0,0 +1,102 @@
+//#docregion
+import 'package:angular2/core.dart';
+
+// #docregion hero-import
+import 'hero.dart';
+// #enddocregion hero-import
+// #docregion hero-detail-import
+import 'hero_detail_component.dart';
+// #enddocregion hero-detail-import
+
+@Component(
+    selector: 'my-app',
+// #docregion hero-detail-template
+    template: '''
+      <h1>{{title}}</h1>
+      <h2>My Heroes</h2>
+      <ul class="heroes">
+        <li *ngFor="#hero of heroes"
+          [class.selected]="hero == selectedHero"
+          (click)="onSelect(hero)">
+          <span class="badge">{{hero.id}}</span> {{hero.name}}
+        </li>
+      </ul>
+      <my-hero-detail [hero]="selectedHero"></my-hero-detail>
+    ''',
+// #enddocregion hero-detail-template
+    styles: const ['''
+      .selected {
+        background-color: #CFD8DC !important;
+        color: white;
+      }
+      .heroes {
+        margin: 0 0 2em 0;
+        list-style-type: none;
+        padding: 0;
+        width: 10em;
+      }
+      .heroes li {
+        cursor: pointer;
+        position: relative;
+        left: 0;
+        background-color: #EEE;
+        margin: .5em;
+        padding: .3em 0em;
+        height: 1.6em;
+        border-radius: 4px;
+      }
+      .heroes li.selected:hover {
+        color: white;
+      }
+      .heroes li:hover {
+        color: #607D8B;
+        background-color: #EEE;
+        left: .1em;
+      }
+      .heroes .text {
+        position: relative;
+        top: -3px;
+      }
+      .heroes .badge {
+        display: inline-block;
+        font-size: small;
+        color: white;
+        padding: 0.8em 0.7em 0em 0.7em;
+        background-color: #607D8B;
+        line-height: 1em;
+        position: relative;
+        left: -1px;
+        top: -4px;
+        height: 1.8em;
+        margin-right: .8em;
+        border-radius: 4px 0px 0px 4px;
+      }
+    '''
+    ],
+// #docregion directives
+    directives: const [
+      HeroDetailComponent
+    ])
+// #enddocregion directives
+class AppComponent {
+  final String title = 'Tour of Heroes';
+  final List<Hero> heroes = mockHeroes;
+  Hero selectedHero;
+
+  onSelect(Hero hero) {
+    selectedHero = hero;
+  }
+}
+
+final List<Hero> mockHeroes = [
+  new Hero(11, "Mr. Nice"),
+  new Hero(12, "Narco"),
+  new Hero(13, "Bombasto"),
+  new Hero(14, "Celeritas"),
+  new Hero(15, "Magneta"),
+  new Hero(16, "RubberMan"),
+  new Hero(17, "Dynama"),
+  new Hero(18, "Dr IQ"),
+  new Hero(19, "Magma"),
+  new Hero(20, "Tornado")
+];

public/docs/_examples/toh-3/dart/lib/hero.dart

@@ -0,0 +1,8 @@
+// #docregion
+class Hero {
+  final int id;
+  String name;
+
+  Hero(this.id, this.name);
+}
+// #enddocregion

public/docs/_examples/toh-3/dart/lib/hero_detail_component.dart

@@ -0,0 +1,39 @@
+// #docplaster
+// #docregion
+// #docregion v1
+import 'package:angular2/core.dart';
+
+// #enddocregion v1
+// #docregion hero-import
+import 'hero.dart';
+// #enddocregion hero-import
+
+// #docregion v1
+@Component(
+    selector: 'my-hero-detail',
+// #enddocregion v1
+    // #docregion template
+    template: '''
+    <div *ngIf="hero != null">
+      <h2>{{hero.name}} details!</h2>
+      <div><label>id: </label>{{hero.id}}</div>
+      <div>
+        <label>name: </label>
+        <input [(ngModel)]="hero.name" placeholder="name">
+      </div>
+    </div>
+  '''
+    // #enddocregion template
+// #docregion v1
+    )
+class HeroDetailComponent {
+// #enddocregion v1
+// #docregion inputs
+  @Input()
+// #docregion hero
+  Hero hero;
+// #enddocregion hero
+// #enddocregion inputs
+// #docregion v1
+}
+// #enddocregion v1

public/docs/_examples/toh-3/dart/pubspec.yaml

@@ -0,0 +1,15 @@
+name: angular2_tour_of_heroes
+version: 0.0.1
+environment:
+  sdk: '>=1.13.0 <2.0.0'
+dependencies:
+  angular2: 2.0.0-beta.14
+  browser: ^0.10.0
+  dart_to_js_script_rewriter: ^1.0.1
+transformers:
+- angular2:
+    platform_directives:
+    - package:angular2/common.dart#COMMON_DIRECTIVES
+    platform_pipes:
+     - package:angular2/common.dart#COMMON_PIPES
+    entry_points: web/main.dart

public/docs/_examples/toh-3/dart/web/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Angular 2 Tour of Heroes</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href="styles.css">
+
+    <script defer src="main.dart" type="application/dart"></script>
+    <script defer src="packages/browser/dart.js"></script>
+  </head>
+  <body>
+    <my-app>Loading...</my-app>
+  </body>
+</html>

public/docs/_examples/toh-3/dart/web/main.dart

@@ -0,0 +1,9 @@
+// #docregion pt1
+import 'package:angular2/bootstrap.dart';
+
+import 'package:angular2_tour_of_heroes/app_component.dart';
+
+main() {
+  bootstrap(AppComponent);
+}
+// #enddocregion pt1

public/docs/dart/latest/tutorial/toh-pt2.jade

@@ -35,7 +35,7 @@ include ../_util-fns
       .file main.dart
     .file pubspec.yaml
 :marked
-  ### Keep the app transpiling and running
+  ### Keep the app compiling and running
   We want to start the Dart compiler, have it watch for changes, and start our server. We'll do this by typing
 
 code-example(format="." language="bash").

public/docs/dart/latest/tutorial/toh-pt3.jade

@@ -1,14 +1,251 @@
 include ../_util-fns
 
 :marked
-  We're working on the Dart version of this case study.
+  Our app is growing.
-  In the meantime, please see these resources:
+  Use cases are flowing in for reusing components, passing data to components, and creating more reusable assets. Let's separate the heroes list from the hero details and make the details component reusable.
 
-  * [Multiple Components](/docs/ts/latest/tutorial/toh-pt3.html):
+  The complete source code for the example app in this chapter is
-    The TypeScript version of this chapter
+  [in GitHub](https://github.com/angular/angular.io/tree/master/public/docs/_examples/toh-3/dart).
 
-  * [Dart source code](https://github.com/angular/angular.io/tree/master/public/docs/_examples/toh-5/dart):
+.l-main-section
-    A preliminary Dart version of the Tour of Heroes app,
+:marked
-    featuring the hero editor, a master/detail page,
+  ## Where We Left Off
-    multiple components, services, and routing
+  Before we continue with our Tour of Heroes, let’s verify we have the following structure. If not, we’ll need to go back and follow the previous chapters.
 
+.filetree
+  .file angular2_tour_of_heroes
+  .children
+    .file lib
+    .children
+      .file app_component.dart
+    .file web
+    .children
+      .file index.html
+      .file main.dart
+    .file pubspec.yaml
+:marked
+  ### Keep the app compiling and running
+  We want to start the Dart compiler, have it watch for changes, and start our server. We'll do this by typing
+
+code-example(format="." language="bash").
+  pub serve
+
+:marked
+  This will keep the application running while we continue to build the Tour of Heroes.
+
+  ## Making a Hero Detail Component
+  Our heroes list and our hero details are in the same component in the same file.
+  They're small now but each could grow.
+  We are sure to receive new requirements for one and not the other.
+  Yet every change puts both components at risk and doubles the testing burden without benefit.
+  If we had to reuse the hero details elsewhere in our app,
+  the heroes list would tag along for the ride.
+
+  Our current component violates the
+  [Single Responsibility Principle](https://blog.8thlight.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html).
+  It's only a tutorial but we can still do things right —
+  especially if doing them right is easy and we learn how to build Angular apps in the process.
+
+  Let’s break the hero details out into its own component.
+
+  ### Separating the Hero Detail Component
+  Add a new file named `hero_detail_component.dart` to the `lib` folder and create `HeroDetailComponent` as follows.
+
++makeExample('toh-3/dart/lib/hero_detail_component.dart', 'v1', 'hero_detail_component.dart (initial version)')(format=".")
+.l-sub-section
+  :marked
+    ### Naming conventions
+    We like to identify at a glance which classes are components and which files contain components.
+
+    Notice that  we have an `AppComponent` in a file named `app_component.dart` and our new
+    `HeroDetailComponent` is in a file named `hero_detail_component.dart`.
+
+    All of our component names end in "Component".  All of our component file names end in "_component".
+
+    We spell our file names in lower dash case (AKA "kebab case") so we don't worry about
+    case sensitivity on the server or in source control.
+
+    <!-- TODO
+    .l-sub-section
+      :marked
+        Learn more about naming conventions in the chapter [Naming Conventions]
+    :marked
+    -->
+:marked
+  We begin by importing the Angular `core.dart` file,
+  so that we can use common types like `@Component` when we create
+  our component.
+
+  We create metadata with the `@Component` annotation where we
+  specify the selector name that identifies this component's element.
+
+  When we finish here, we'll import it into `AppComponent` and create a corresponding `<my-hero-detail>`  element.
+:marked
+  #### Hero Detail Template
+  At the moment, the *Heroes* and *Hero Detail* views are combined in one template in `AppComponent`.
+  Let’s **cut** the *Hero Detail* content from `AppComponent` and **paste** it into the new template property of  `HeroDetailComponent`.
+
+  We previously bound to the `selectedHero.name` property of the `AppComponent`.
+  Our `HeroDetailComponent` will have a `hero` property, not a `selectedHero` property.
+  So we replace `selectedHero` with `hero` everywhere in our new template. That's our only change.
+  The result looks like this:
+
++makeExample('toh-3/dart/lib/hero_detail_component.dart', 'template', 'hero_detail_component.dart (template)')(format=".")
+
+:marked
+  Now our hero detail layout exists only in the `HeroDetailComponent`.
+
+  #### Add the *hero* property
+  Let’s add that `hero` property we were talking about to the component class.
++makeExample('toh-3/dart/lib/hero_detail_component.dart', 'hero')(format=".")
+:marked
+  Uh oh. We declared the `hero` property as type `Hero` but our `Hero` class is over in the `app_component.dart` file.
+  We have two components, each in their own file, that need to reference the `Hero` class.
+
+  We solve the problem by relocating the `Hero` class from `app_component.dart` to its own `hero.dart` file.
+
++makeExample('toh-3/dart/lib/hero.dart', null, 'hero.dart (Exported Hero class)')(format=".")
+
+:marked
+  Add the following import statement near the top of both `app_component.dart` and `hero_detail_component.dart`.
+
++makeExample('toh-3/dart/lib/hero_detail_component.dart', 'hero-import', 'hero_detail_component.dart and app_component.dart (Import the Hero class)')(format=".")
+
+:marked
+  #### The *hero* property is an ***input***
+
+  The `HeroDetailComponent` must be told what hero to display. Who will tell it? The parent `AppComponent`!
+
+  The `AppComponent` knows which hero to show: the hero that the user selected from the list.
+  The user's selection is in its `selectedHero` property.
+
+  We will soon update the `AppComponent` template so that it binds its `selectedHero` property
+  to the `hero` property of our `HeroDetailComponent`. The binding *might* look like this:
+code-example(format=".").
+  &lt;my-hero-detail [hero]="selectedHero">&lt;/my-hero-detail>
+:marked
+  Notice that the `hero` property is the ***target*** of a property binding &mdash; it's in square brackets to the left of the (=).
+
+  Angular insists that we declare a ***target*** property to be an ***input*** property.
+  If we don't, Angular rejects the binding and throws an error.
+.l-sub-section
+  :marked
+    We explain input properties in more detail [here](../guide/attribute-directives.html#why-input)
+    where we also explain why *target* properties require this special treament and
+    *source* properties do not.
+:marked
+  There are a couple of ways we can declare that `hero` is an *input*.
+  We'll do it the way we *prefer*, by annotating the `hero` property with the `@Input` decorator.
++makeExample('toh-3/dart/lib/hero_detail_component.dart', 'inputs')(format=".")
+
+.l-sub-section
+  :marked
+    Learn more about the `@Input()` annotation way in the
+    [Attribute Directives](../guide/attribute-directives.html#input) chapter.
+
+.l-main-section
+:marked
+  ## Refresh the AppComponent
+  We return to the `AppComponent` and teach it to use the `HeroDetailComponent`.
+
+  We begin by importing the `HeroDetailComponent` so we can refer to it.
+
++makeExample('toh-3/dart/lib/app_component.dart', 'hero-detail-import')(format=".")
+
+:marked
+  Find the location in the template where we removed the *Hero Detail* content
+  and add an element tag that represents the `HeroDetailComponent`.
+code-example(format=".").
+  &lt;my-hero-detail>&lt;/my-hero-detail>
+.l-sub-section
+  :marked
+    *my-hero-detail* is the name we set as the  `selector` in the `HeroDetailComponent` metadata.
+:marked
+ The two components won't coordinate until we bind the `selectedHero` property of the `AppComponent`
+ to the `HeroDetailComponent` element's `hero` property  like this:
+code-example(format=".")
+  &lt;my-hero-detail [hero]="selectedHero">&lt;/my-hero-detail>
+:marked
+  The `AppComponent`’s template should now look like this
+
++makeExample('toh-3/dart/lib/app_component.dart', 'hero-detail-template', 'app_component.dart (Template)')(format=".")
+:marked
+  Thanks to the binding, the `HeroDetailComponent` should receive the hero from the `AppComponent` and display that hero's detail beneath the list.
+  The detail should update every time the user picks a new hero.
+
+  It's not happening yet!
+
+  We click among the heroes. No details. We look for an error in the console of the browser development tools. No error.
+
+  It is as if Angular were ignoring the new tag. That's because *it is ignoring the new tag*.
+
+  ### The *directives* list
+  A browser ignores HTML tags and attributes that it doesn't recognize. So does Angular.
+
+  We've imported `HeroDetailComponent`, we've used it in the template, but we haven't told Angular about it.
+
+  We tell Angular about it by listing it in the metadata `directives` list. Let's add that list property to the bottom of the
+  `@Component` configuration object, immediately after the `template` and `styles` properties.
++makeExample('toh-3/dart/lib/app_component.dart', 'directives')(format=".")
+
+
+:marked
+  ### It works!
+  When we view our app in the browser we see the list of heroes.
+  When we select a hero we can see the selected hero’s details.
+
+  What's fundamentally new is that we can use this `HeroDetailComponent`
+  to show hero details anywhere in the app.
+
+  We’ve created our first reusable component!
+
+  ### Reviewing the App Structure
+  Let’s verify that we have the following structure after all of our good refactoring in this chapter:
+
+.filetree
+  .file angular2_tour_of_heroes
+  .children
+    .file lib
+    .children
+      .file app_component.dart
+      .file hero.dart
+      .file hero_detail_component.dart
+    .file web
+    .children
+      .file index.html
+      .file main.dart
+    .file pubspec.yaml
+:marked
+  Here are the code files we discussed in this chapter.
+
++makeTabs(`
+  toh-3/dart/lib/hero_detail_component.dart,
+  toh-3/dart/lib/app_component.dart,
+  toh-3/dart/lib/hero.dart
+  `,'',`
+  lib/hero_detail_component.dart,
+  lib/app_component.dart,
+  lib/hero.dart
+  `)
+
+.l-main-section
+:marked
+  ## The Road We’ve Travelled
+  Let’s take stock of what we’ve built.
+
+  * We created a reusable component
+  * We learned how to make a component accept input
+  * We learned to bind a parent component to a child component.
+  * We learned to declare the application directives we need in a `directives` list.
+
+.l-main-section
+:marked
+  ## The Road Ahead
+  Our Tour of Heroes has become more reusable with shared components.
+
+  We're still getting our (mock) data within the `AppComponent`.
+  That's not sustainable.
+  We should refactor data access to a separate service
+  and share it among the components that need data.
+
+  We’ll learn to create services in the [next tutorial](toh-pt4.html) chapter.