angular-cn/public/docs/ts/latest/tutorial/toh-pt1.jade

include ../../../../_includes/_util-fns

.l-main-section
  :marked
    # Once Upon a Time

    Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.

    Follow the "QuickStart" steps. They provide the prerequisites, the folder structure,
    and the core files for our Tour of Heroes.

    Copy the "QuickStart" code to a new folder and rename the folder `angular2-tour-of-heroes`.
    We should have the following structure:

  code-example.
      angular2-tour-of-heroes
        ├── node_modules
        ├── src
        |    ├── app
        |    |    └── app.ts
        |    ├── index.html
        |    └── tsconfig.json
        └── package.json

  :marked
    ### Keep the app running
    Start the TypeScript compiler and have it watch for changes in one terminal window by typing

  pre.prettyprint.lang-bash
    code npm run tsc

  :marked
    Now open another terminal window and start the server by typing

  pre.prettyprint.lang-bash
    code npm start

  :marked
    This command starts the server, launches the app in a browser,
    and keeps the app running while we continue to build the Tour of Heroes.

  .l-sub-section
    :marked
      These two steps watch all project files. They recompile TypeScript files and re-run
      the app when any file changes.
      If the watchers fail to detect renamed or new files,
      stop these commands in each terminal by typing `CTRL+C` and then re-run them.

.l-main-section
  :marked
    ## Show our Hero
    We want to display Hero data in our app

    Let's add two properties to our `AppComponent`, a `title` property for the application name and a `hero` property
    for a hero named "Windstorm".

    ```
    class AppComponent {
      public title = 'Tour of Heroes';
      public hero = 'Windstorm';
    }
    ```

  :marked
    Now we update the template in the `@Component` decoration with data bindings to these new properties.

  code-example(format="").
    template: '<h1>{{title}}&lt/h1>&lth2>{{hero}} details!&lt/h2>'
  :marked
    The browser should refresh and display our title and hero.

    The double curly braces tell our app to read the `title` and `hero` properties from the component and render them.
    This is the "interpolation" form of one-way data binding.
  .l-sub-section
    :marked
      Learn more about interpolation in the [Displaying Data chapter](../guide/displaying-data).
  :marked
    ### Hero object

    At the moment, our hero is just a name.  Our hero needs more properties.
    Let's convert the `hero` from a literal string to a class.

    Create a `Hero` class with `id` and `name` properties.
    Keep this near the top of 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 initialize it with an id of `1` and the name, "Windstorm".

    ```
    public hero: Hero = {
      id: 1,
      name: 'Windstorm'
    };
    ```

    Because we changed the hero from a string to an object,
    we update the binding in the template to refer to the hero’s `name` property.

  code-example(format="").
    template: '<h1>{{title}}&lt/h1>&lth2>{{hero.name}} details!&lt/h2>'
  :marked
    The browser refreshes and continues to display our hero’s name.

    ### Adding more HTML
    Displaying a name is good, but we want to see all of our hero’s properties.
    We’ll add a `<div>` for our hero’s `id` property and another `<div>` for our hero’s `name`.

  code-example(format="linenums").
    template: '&lt;h1>{{title}}&lt/h1>&lth2>{{hero.name}} details!&lt/h2>&ltdiv>&ltlabel>id: &lt/label>{{hero.id}}&lt/div>&ltdiv>&ltlabel>name: &lt/label>{{hero.name}}&lt/div>'
  :marked
    Uh oh, our template string is getting long. We better take care of that to avoid the risk of making a typo in the template.

    ### Multi-line template strings

    We could make a more readable template with string concatenation
    but that gets ugly fast, it is harder to read, and
    it is easy to make a spelling error. Instead,
    let’s take advantage of the template strings feature
    in ES2015 and TypeScript to maintain our sanity.

    Change the quotes around the template to back-ticks and
    put the `<h1>`, `<h2>` and `<div>` elements on their own lines.

  code-example(format="linenums").
    template:`
      &lt;h1>{{title}}&lt/h1>
      &lth2>{{hero.name}} details!&lt/h2>
      &ltdiv>&ltlabel>id: &lt/label>{{hero.id}}&lt/div>
      &ltdiv>&ltlabel>name: &lt/label>{{hero.name}}&lt/div>
      `

  .callout.is-important
    header A back-tick is not a single quote
    :marked
      **Be careful!** A back-tick (`) looks a lot like a single quote (').
      It's actually a completely different character.
      Back-ticks can do more than demarcate a string.
      Here we use them in a limited way to spread the template over multiple lines.
      Everything between the back-ticks at the beginning and end of the template
      is part of a single template string.

.l-main-section
  :marked
    ## Editing Our Hero

    We want to be able to edit the hero name in a textbox.

    Refactor the hero name `<label>` with `<label>` and `<input>` elements as shown below:
  code-example(format="linenums").
    template:`
      &lt;h1>{{title}}&lt/h1>
      &lth2>{{hero.name}} details!&lt/h2>
      &ltdiv>&ltlabel>id: &lt/label>{{hero.id}}&lt/div>
      &ltdiv>
        &ltlabel>name: &lt/label>
        &ltdiv>&ltinput value="{{hero.name}}" placeholder="name">&lt/div>
      &lt/div>
      `
  :marked
    We see in the browser that the hero’s name does appear in the `<input>` textbox.
    But something doesn’t feel right.
    When we change the name, we notice that our change
    is not reflected in the `<h2>`. We won't get the desired behavior
    with a one-way binding to `<input>`.

    ### Two-Way Binding

    We intend to display the name of the hero in the `<input>`, change it,
    and see those changes wherever we bind to the hero’s name.
    In short, we want two-way data binding.

    Let’s update the template to use the  **`ng-model`** built-in directive for two-way binding.

  .l-sub-section
    :marked
      Learn more about `ng-model` in the [Template Syntax chapter](../guide/template-syntax.html#ng-model)
  :marked
    Replace the `<input>` with the following HTML

  code-example(language="html").
     &lt;input [(ng-model)]="hero.name" placeholder="name">

  :marked
    Unfortunately, that change broke our application and we're no longer displaying the hero in the browser.
    Let’s fix that next.

.l-main-section
  :marked
    ## Declaring Template Directives

    We added the `ng-model` directive but we didn't tell Angular about it.
    A component must disclose every directive that appears in its template.

    Let’s first gain access to the `NgModel` directive class by importing it from Angular as shown below:

    ````
    import {bootstrap, Component, NgModel} from 'angular2/angular2';
    ```

    Now tell the component that we will use the  `ng-model` directive in the template
    by adding the `directives` property to the `@Component` decoration
    immediately below the `template` string:

    ```
    directives: [NgModel]
    ```

    The `directives` property is an array holding all directive classes that
    are used by the component’s template.

    Unfortunately when we view the app in the browser we still have an error:

  code-example(language="html").
    EXCEPTION: No value accessor for ' ' in [null]

  :marked
    Apparently declaring the `NgModel` is not quite enough.

    ## Declare Multiple Form Directives

    We learned from our latest error message that we can’t the import `NgModel` alone.
    We need additional directives to enable two-way data binding with `NgModel`.

    We could hunt them down and add each of them to the `directives` array one by one.
    That's painful. No one wants to remember all of the necessary directives and
    type them correctly. Fortunately, there is a shortcut.

    The `ng-model` directive is one of many Forms directives which happen to be
    bundled in a convenient array called `FORM_DIRECTIVES`.
  .l-sub-section
    :marked
      Learn more about Angular Forms in the [Forms chapter](../guide/forms)
  :marked
    Let’s forget about importing `NgModel` and import the `FORM_DIRECTIVES` array instead:
    ```
    import {bootstrap, Component, FORM_DIRECTIVES} from 'angular2/angular2';
    ```
    Now we tell the component that our template can use `FORM_DIRECTIVES`
    by updating the `directives` property of the `@Component` decorator.
    ```
    directives: [FORM_DIRECTIVES]
    ```
    The browser refreshes. We see our hero again. We can edit the hero’s name and
    see the changes reflected immediately in the `<h2>`.

    ### Bundled directives
    Angular bundled the Form-related directives together in a convenient `FORM_DIRECTIVES` array.
    That's all we need to remember to light up our template.

    We may wish to use this trick ourselves someday.
    We too can bundle a collection of directives in an array, give it a catchy name,
    and plug that array into the `directives` property.

.l-main-section
  :marked
    ## The Road We’ve Travelled
    Let’s take stock of what we’ve built.

    * Our Tour of Heroes uses the double curly braces of interpolation (a form of one-way data binding)
    to display the application title and properties of a `Hero` object.
    * We wrote a multi-line template using ES2015’s template strings to make our template readable.
    * We can both display and change the hero’s name after adding a two-way data binding to the `<input>` element
    using the built-in `ng-model` directive.
    * The `ng-model` directive also propagates changes to every other binding of the `hero.name`.
    * We declared our use of `NgModel` and other Form directives
    by setting the component's `directives` metadata property to the `FORMS_DIRECTIVES` array.

    Here's the complete `app.ts` as it stands now:

  code-example(format="linenums").
    import {bootstrap, Component, FORM_DIRECTIVES} from 'angular2/angular2';

    class Hero {
      id: number;
      name: string;
    }

    @Component({
      selector: 'my-app',
      template:`
        &lt;h1>{{title}}&lt/h1>
        &lth2>{{hero.name}} details!&lt/h2>
        &ltdiv>&ltlabel>id: &lt/label>{{hero.id}}&lt/div>
        &ltdiv>
          &ltlabel>name: &lt/label>
          &ltdiv>&ltinput [(ng-model)]="hero.name" placeholder="name">&lt/div>
        &lt/div>
        `,
      directives: [FORM_DIRECTIVES]
    })
    class AppComponent {
      public title = 'Tour of Heroes';
      public hero: Hero = {
        id: 1,
        name: 'Windstorm'
      };
    }

    bootstrap(AppComponent);

.l-main-section
  :marked
    ## 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 their 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 tutorial chapter](./toh-pt2.html).