Merged Katya's ToH part 1 into the last state of devguide-getting-started-3 branch

public/docs/ts/latest/guide/_data.json

@@ -8,7 +8,9 @@
   "gettingStarted": {
     "title": "Getting Started"
   },
-
+  "toh-pt1": {
+    "title": "Tour of Heros Begins"
+  },
   "displaying-data": {
     "title": "Displaying Data",
     "intro": "Displaying data is job number one for any good application. In Angular, you bind data to elements in HTML templates and Angular automatically updates the UI as data changes."

public/docs/ts/latest/guide/toh-pt1.jade

@@ -0,0 +1,257 @@
+include ../../../../_includes/_util-fns
+
+.l-main-section
+
+  :markdown
+    # Tour of Heroes - Part 1 - We Need A Hero
+
+    ## Once Upon a Time
+    Every story starts somewhere. Our story starts with the Getting Started chapter. Start by following the Getting Started steps and use that as a starting point for Tour of Heroes. This will give us the prerequisites, the folder structure, and the core files for the app.
+
+    ### **The End Game**
+    Before we begin, let’s get an idea of where what we’re going to build.
+
+    The Tour of Heroes is an application that covers the core fundamentals of Angular 2. We will build the Tour of Heroes to allow selecting a hero from a list of heroes, editing hero details, and navigating between different views.
+
+    We’ll use built-in directives to show/hide elements and display lists of heroes data. We’ll  add data binding of hero details, data binding for arrays of heroes, editable fields that update their model, and handling user interaction events. We want heroes to be selectable, so we’ll add selecting heroes from a list, navigating from heroes to hero details, and formatting data with pipes. Our Tour of Heroes will also use routing to navigate between different components.
+
+    We’ll cover just enough of the core fundamentals to get us started and build an app. Since we are covering a lot of ground, we’ll be able to go deeper on topics by following links as we go.
+
+    Selectable List of Heroes
+  figure.image-display
+    img(src='/resources/images/devguide/toh/heroes-list-1.png' alt="Output of heroes list app")
+
+  :markdown
+    Hero Details
+  figure.image-display
+    img(src='/resources/images/devguide/toh/hero-details-1.png' alt="Details of hero in app")
+
+  :markdown
+    ### **This is How We Roll**
+    We’ll be building the Tour of Heroes together, step by step. Along the way we’ll learn many of the core fundamentals of Angular 2 as we construct the application. Each step is motivated by a requirement. Everything has a reason. We’ll motivate the direction the Tour of Heroes takes, and learn how to solve common application needs with Angular 2’s fundamentals.
+
+    ## Getting Started
+
+    ### **Creating Tour of Heroes**
+    After following Getting Started, copy the code to a new folder and rename the folder `angular2-tour-of-heroes`
+
+    *Sidenote: Follow the Getting Start guide in the [getting started chapter]*
+
+    Our starting app from Getting Started should look like the following structure:
+
+  pre.prettyprint.lang-bash
+    |---- node_modules
+    |---- src
+    |    |---- app
+    |    |    |---- app.ts
+    |    |----  typings
+    |    |    |----  tsd.d.ts
+    |    |---- index.html
+    |    |---- tsconfig.json
+    |---- package.json
+
+  :markdown
+    ### **Keeping the App Running**
+    Let’s start the TypeScript compiler and have it watch for changes in one terminal window by typing
+
+  pre.prettyprint.lang-bash
+    code tsc -p src -w
+
+  :markdown
+    We’ll start the server and launch the app in the browser by typing in another terminal window
+
+  pre.prettyprint.lang-bash
+    code live-server --open=src
+
+  :markdown
+    This will keep the application running while we continue to build the Tour of Heroes.
+
+    Note: These steps will watch the existing files and recompile and re-run the app when they change. However, if you notice the watchers do not pick up renamed or new files, stop these commands in terminal by typing `CTRL+C` and then re-run both commands.
+
+.l-main-section
+
+  :markdown
+    ## Let's Show our Hero
+    We want to show data in our app, so let’s start by creating a title for our Tour of Heroes. We’ll also create a hero and display him.
+
+    ### **Displaying Data**
+    We need to add properties in our component to store the title and the hero’s name. Let’s create `title` and  `hero` properties in the component. We’ll set the title to Tour of Heroes and set the hero to Windstorm.
+
+    ```
+    class AppComponent {
+      public title = 'Tour of Heroes';
+      public hero = 'Windstorm';
+    }
+    ```
+
+  :markdown
+    This defines properties on our component that we can bind and display in the HTML template. Now we need to display the properties.
+
+    Let’s change the template to show the name of our hero
+
+    ```javascript
+    @View({
+      template: '<h1>{\{titles}\}</h1><h2>{{hero}} details!</h2>'
+    })```
+
+    The curly braces tell our app to read the `title` and `hero` properties from the component and render them.
+
+    *Sidenote: Learn more about one-way binding in the [data binding chapter]*
+
+    ### **Hero Object**
+    Our hero has a name, but we want to him to have more properties. We’ll do this in TypeScript by creating a `Hero` class.
+
+    Let’s create the `Hero` class with `id` and `name` properties. We’ll put this in the `app.ts` file for now.
+
+    ```
+    class Hero {
+      id: number;
+      name: string;
+    }```
+
+    Now that we have a `Hero` class, let’s refactor our component’s `hero` property to be of type `Hero`. Then we’ll initialize it with an id of 1 and name of Windstorm.
+
+    ```
+    public hero: Hero = {
+      id: 1,
+      name: 'Windstorm'
+    };```
+
+    We just changed the hero from a string to an object. Let’s change the binding in the template to refer to the hero’s `name` property and put it in the `<h2>`.
+
+    ```
+    @View({
+      template: '<h1>{{title}}</h1><h2>{{hero.name}} details!</h2>'
+    })```
+
+    We can now see our hero’s name, Windstorm, is displayed in the browser.
+
+    ## Editing Our Hero
+    Displaying a name is good, but we want to see all of our hero’s properties and allow editing the name. Let’s continue by adding the rest of the hero’s properties to the template so we can see those details.
+
+    ### **Adding more HTML**
+    We’ll add a `<div>` for our hero’s `id` property and another `<div>` for our hero’s `name`.
+
+    ```
+    @View({
+      template: '<h1>{{title}}</h1><h2>{{hero.name}} details!</h2><div><label>id: </label>{{hero.id}}</div><div><label>name: </label>{{hero.name}}</div>'
+    })```
+
+    Uh oh, our string is getting long. We better take care of that to avoid the risk of making a typo in the template.
+
+    ### **Template Strings**
+    Adding more content to the template is making the template extend to multiple lines. We could use string concatenation, but that gets ugly fast, harder to read, and it is easy for us to make a mistake in typing. Instead, let’s solve this by taking advantage of the template strings feature in ES2015 and TypeScript to maintain some sanity.
+
+    Let’s change the quotes around the template to back-ticks
+
+    ```
+    @View({
+      template: <h1>{{title}}</h1><h2>{{hero.name}} details!</h2><div><label>id: </label>{{hero.id}}</div><div><label>name: </label>{{hero.name}}</div>
+    })```
+
+    If we don’t look closely, back-ticks look similar to a single quote. But they operate in an important and different way. Back-ticks permit us to use multiple lines in the template’s string. Everything between the back-ticks is part of the template, even spanning multiple lines.
+
+    Now let’s change the template to be more readable with the `<h1>`, `<h2>` and `<div>` elements each on their own lines.
+
+    ### **Multi-line Templates**
+    Template strings are helpful for embedding a few lines of templates in a component. Once we exceed a few lines, we’ll move the template to an HTML file and point to it. Our small template is not at that point yet, so we’ll stick with the template string.
+
+    Edit the template so it looks like the following:
+
+    ```
+    @View({
+      template:<h1>{{title}}</h1><h2>{{hero.name}} details!</h2><div><label>id: </label>{{hero.id}}</div><div><label> name: </label>{{hero.name}}</div>
+    })```
+
+    ### **Adding an `<INPUT>`**
+    We want to be able to edit the name of our hero. For this we’ll add an `<input>` element as shown below:
+
+    ```
+    @View({
+      template:
+        <h1>{{title}}</h1>
+        <h2>{{hero.name}} details!</h2>
+        <div><label>id: </label>{{hero.id}}</div>
+        <div>
+          <label>name: </label>
+          <div><input value="{{hero.name}}" placeholder="name"></input></div>
+        </div>
+    })```
+
+    We want the hero’s name to appear in the `<input>`. But something doesn’t feel right. When we try changing the name and we notice the hero’s name change is not reflected in the `<h2>`. We don’t want to use one-way binding here.
+
+    ### **Two-Way Binding**
+    We want to display the name of the hero in the `<input>`, be able to change it, and see those changes in every place bound to the hero’s name. In short, we want two-way binding. Let’s make a change to the template to use the special **`ng-model`** built-in directive to achieve this.
+
+    Replace the  `<input>` with the following HTML
+
+    ```
+    <input [(ng-model)]="hero.name" placeholder="name"></input>
+    ```
+
+    Let’s fix that next by letting Angular know we want to use the ng-model directive.
+
+    *Sidenote: Learn more about ng-model in the [data binding chapter]*
+
+    ### **FORM Directives**
+    We just used the `ng-model` directive, but we must tell the component which directives we will use in the template. When we know which directives we want to use, we can import them from Angular 2 and tell the component’s view that we want to use them.
+
+    Let’s go get the `NgModel` directive by importing it from Angular as shown below:
+
+    ````
+    import {bootstrap, Component, View, NgModel} from 'angular2/angular2';
+    ```
+
+    Now let’s tell the component that we will use the  `ng-model` directive in the template by setting the `directives` property in the `@View` decorator of the component:
+
+    ```
+    @View({
+      directives: [NgModel]
+    })```
+
+    The `directives` property accepts an array of directives that will be used in the component’s template.
+
+    Unfortunately when we view the app in the browser we still have an error:
+
+    > *EXCEPTION: No value accessor for ' ' in [null]*
+
+    We added `NgModel`, but that’s not quite enough to support forms.
+
+    ### **Declaring Form Directives**
+    The `ng-model` built-in directive is special as it wraps the functionality needed to bind, in our case, to the `<input>`.  We’ve learned from our latest error message, that we can’t just import `NgModel`. We need a whole bunch of directives to enable this scenario. It would be painful and lengthy burden to remember and list all of the directives. Fortunately, there is a shortcut where we can use a bundle of directives in an array.
+
+    ### Importing FORM_DIRECTIVES
+    The `ng-model` directive is a type of Form directive. Let’s go get the Form directives by importing `FORM_DIRECTIVES` from Angular as shown below:
+
+    ```
+    import {bootstrap, Component, View, FORM_DIRECTIVES} from 'angular2/angular2';
+    ```
+
+    ### Declaring Directives
+    Now let’s tell the component that we will use Form directives in the template by setting the `directives` property in the `@View` decorator of the component.
+
+    ```
+    @View({
+      directives: [FORM_DIRECTIVES]
+    })```
+
+    Now when we view the app in the browser we can edit the hero’s name and we see the changes are reflected in the `<h1>`.
+
+    Angular bundles all the binding directives for forms together into `FORM_DIRECTIVES`. This is all we need to remember to light up our template. Fortunately, we can bundle a collection of directives together in an array, give it a catchy name, and we can plug that array into the `directives` property.
+
+    *Sidenote: Learn more about Angular 2 Forms in the [Forms chapter]*
+
+    ## Recap
+
+    ### **The Road We’ve Travelled**
+    Let’s take stock in what we’ve built.
+
+    > [formatting = undordered list. how?]
+    > Our Tour of Heroes now includes one-way data binding to display a hero by wrapping properties with double curly braces in our template.
+    > || We added two-way data binding so we can change the hero’s name and see those changes throughout all places the hero’s name is bound in the template.
+    > || We built our template in the component’s file using ES2015’s template strings feature.
+    > || We declared that we use the Form directives in our component and view.
+    > || We used the special built-in `ng-model` directive with the `<input>` element to make the hero’s name display in the template.  `ng-model` also helps us propagate any changes we make throughout all places bound to `hero.name` in the template.
+
+    ### **The Road Ahead**
+    Our Tour of Heroes only displays one hero and we really want to display a list of heroes. We also want to allow the user to select a hero and display his details. We’ll learn more about how to retrieve lists, bind them to the template, and allow a user to select it in the next chapter.

public/docs/ts/latest/guide/unit-testing-01.jade

@@ -110,8 +110,10 @@ figure.image-display
 
   It’s a big agenda. Fortunately, you can learn a little bit at a time and put each lesson to use.
 
-.callout.is-critical
+.callout.is-helpful
-  p These Unit Testing chapters build upon each other. We recommend reading them in order. <br/>We assume familiarity with basic Angular 2 concepts and the tools we introduced in <a href="./gettingStarted.html">Getting Started</a> and <a href="./#">Tour of Heroes</a> such as `npm`, `gulp`, and `live-server`.
+  p These Unit Testing chapters build upon each other. We recommend reading them in order. <br/>We assume familiarity with basic Angular 2 concepts and the tools we introduced in
+  <a href="./gettingStarted.html">Getting Started</a> and
+  <a href="./toh-pt1.html">Tour of Heroes</a> such as `npm`, `gulp`, and `live-server`.
 
 :markdown
   Let’s get started!