honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

(docs): Update ToH Pt1 and revise.

This commit is contained in:
Ward Bell 2015-10-12 18:36:33 -07:00
parent 53597ab601
commit c0fbf406b5
1 changed files with 255 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

409
public/docs/ts/latest/guide/toh-pt1.jade
View File

@ -3,87 +3,118 @@ include ../../../../_includes/_util-fns
.l-main-section
:markdown
# Tour of Heroes - Part 1 - We Need A Hero
# Tour of Heroes - Part 1
## 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 Tour of Heroes tutorial takes us through the steps of creating an Angular application.
Our grand vision is to build an app to help a staffing agency manage its stable of heroes.
Even heroes need to find work.
### **The End Game**
Before we begin, let’s get an idea of where what we’re going to build.
Of course we'll only make a little progress in this tutorial. What we do build will
have many of the features we expect to find in a full-blown, data-driven application: acquiring and displaying
a list of heroes, editing a selected hero's detail, and navigating among different
views of heroic data.
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.
The Tour of Heroes covers the core fundamentals of Angular.
We’ll use built-in directives to show/hide elements and display lists of hero data.
We’ll create a component to display hero details and another to show an array of heroes.
We'll use one-way data binding for read-only data. We'll add editable fields to update a model
with two-way data binding. We'll bind component method to user events like key strokes and clicks.
We’ll learn to select a hero from a master list and edit that hero in the details view. We'll
format data with pipes. And we'll use routing to navigate among different views and their components.
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 learn enough core Angular to get started and gain confidence that
Angular can do whatever we need it to do.
We'll be covering a lot of ground at an introductory level but we’ll find plenty of links
to chapters with greater depth.
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.
## The End Game
Let's get a visual idea of where we're going in this tour, beginning with the "Heroes"
view and its list of heroes:
**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**
Above the list are two links ("Dashboard" and "Heroes").
We click them to navigate between a Dashboard view and this Heroes view.
After selecting a hero, we can click the "View Details" button and be
wisked away by the router to a "Hero Details" view
where we can change the hero's name.
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.
Links at the top take us back to either of the main views.
The "Back" button returns us to the "Heroes" view.
## Initial App Setup
<aside class="is-right">Find the basics of app setup in the Getting Started chapter.</aside>
## How We Roll
### **Creating Tour of Heroes**
We’ll build this Tour of Heroes together, step by step.
We'll motiviate each step with a requirement that we've
met in countless applications. Everything has a reason.
After following [Getting Started](../guide/gettingStarted.html), copy the code to a new folder and rename the folder
`angular2-tour-of-heroes`
And we’ll meet many of the core fundamentals of Angular along the way.
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
.l-main-section
:markdown
### **Keeping the App Running**
Let’s start the TypeScript compiler and have it watch for changes in one terminal window by typing
# Once Upon a Time
Every story starts somewhere. Our story starts where the [Getting Started chapter]('./gettingstarted') ends.
Follow the "Getting Started" steps. They provide the prerequisites, the folder structure,
and the core files for our Tour of Heroes.
Copy the "Getting Started" 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
| ├── typings
| | └── tsd.d.ts
| ├── index.html
| └── tsconfig.json
└── package.json
:markdown
## 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 tsc -p src -w
:markdown
We’ll start the server and launch the app in the browser by typing in another terminal window
Now open another terminal window and start the server by typing
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.
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.
<!--TODO: style this with callout style and set a header-->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.
.alert.is-helpful
:markdown
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
: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 her.
# Show our Hero
We want to display Hero data in our app
### **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.
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 {
@ -93,178 +124,248 @@ include ../../../../_includes/_util-fns
```
:markdown
This defines properties on our component that we can bind and display in the HTML template. Now we need to display the properties.
Now we update the template in the `@Component` decoration with data bindings to these new properties.
Let’s change the template to show the name of our hero
code-example(format="linenums").
template: '&lt;h1>{{title}}&lt/h1>&lth2>{{hero}} details!&lt/h2>'
:markdown
The browser should refresh and display our title and hero.
```javascript
@View({
template: '<h1>{\{titles}\}</h1><h2>{{hero}} details!</h2>'
})```
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;
we can learn more about interpolation in the [Displaying Data chapter](displaying-data).
The curly braces tell our app to read the `title` and `hero` properties from the component and render them.
## Hero Object
Learn more about one-way binding in the <!--TODO link-->Data Binding chapter.
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.
### **Hero Object**
Our hero has a name, but we want to her 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.
Create a `Hero` class with `id` and `name` properties.
Keep this near the top of hte `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.
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'
};```
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.
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.
## 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.
code-example(format="linenums").
template: '&lt;h1>{{title}}&lt/h1>&lth2>{{hero.name}} details!&lt/h2>'
:markdown
The browser refreshes and continues to display our hero’s name.
### **Adding more HTML**
## **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`.
```
@View({
template: '<h1>{{title}}</h1><h2>{{hero.name}} details!</h2><div><label>id: </label>{{hero.id}}</div><div><label>name: </label>{{hero.name}}</div>'
})```
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>'
:markdown
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.
Uh oh, our 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
### **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.
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.
Let’s change the quotes around the template to back-ticks
Change the quotes around the template to back-ticks and
put the `<h1>`, `<h2>` and `<div>` elements on their own lines.
```
@View({
template: <h1>{{title}}</h1><h2>{{hero.name}} details!</h2><div><label>id: </label>{{hero.id}}</div><div><label>name: </label>{{hero.name}}</div>
})```
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>
`
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.
.callout.is-important
header A back-tick is not a single quote
:markdown
**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.
Now let’s change the template to be more readable with the `<h1>`, `<h2>` and `<div>` elements each on their own lines.
.l-main-section
### **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.
:markdown
# Editing Our Hero
Edit the template so it looks like the following:
We want to be able to edit the hero name in a textbox.
```
@View({
template:<h1>{{title}}</h1><h2>{{hero.name}} details!</h2><div><label>id: </label>{{hero.id}}</div><div><label> name: </label>{{hero.name}}</div>
})```
Replace the hero name `<label>` with an `<input>` element 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/input>&lt/div>
&lt/div>
`
:markdown
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>`.
### **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:
## Two-Way Binding
```
@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 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.
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.
Let’s update the template to use the **`ng-model`** built-in directive for two-way binding.
### **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.
<!-- TODO style with a class and add a link
*Sidenote: Learn more about ng-model in the [Using Forms chapter]*
-->
Replace the `<input>` with the following HTML
```
<input [(ng-model)]="hero.name" placeholder="name"></input>
```
Unfortunately, that change broke our application and we're no longer displaying the hero in the browser.
Let’s fix that next.
Let’s fix that next by letting Angular know we want to use the ng-model directive.
.l-main-section
<!-- TODO style with a class and add a link *Sidenote: Learn more about ng-model in the [data
binding chapter]* -->
:markdown
# Declaring Template Directives
### **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.
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 go get the `NgModel` directive by importing it from Angular as shown below:
Let’s first gain access to the `NgModel` directive class by importing it from Angular as shown below:
````
import {bootstrap, Component, View, NgModel} from 'angular2/angular2';
import {bootstrap, Component, View, NgModel} from 'angular2/core';
```
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:
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:
```
@View({
directives: [NgModel]
})```
directives: [NgModel]
```
The `directives` property accepts an array of directives that will be used in the component’s template.
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:
> *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';
*EXCEPTION: No value accessor for ' ' in [null]*
```
### 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.
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`.
<!-- TODO *Sidenote: Learn more about Angular Forms in the [Forms chapter]* -->
Let’s forget about importing `NgModel` and import the `FORM_DIRECTIVES` array instead:
```
@View({
directives: [FORM_DIRECTIVES]
})```
import {bootstrap, Component, View, FORM_DIRECTIVES} from 'angular2/core';
```
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>`.
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>`.
### 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.
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.
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.
<!-- TODO *Sidenote: Learn more about Angular 2 Forms in the [Forms chapter]* -->
## Recap
### **The Road We’ve Travelled**
# The Road We’ve Travelled
Let’s take stock of what we’ve built.
* 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.
* 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.
<!-- TODO: Add this in when the next chapter exists ### **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 chapter. -->
Here's the complete `AppComponent.ts` as it stands now:
code-example(format="linenums").
import {bootstrap, Component, View, FORM_DIRECTIVES} from 'angular2/core';
class Hero {
id: number;
name: string;
}
@Component({
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/input>&lt/div>
&lt/div>
`,
directives: [FORM_DIRECTIVES]
})
class AppComponent {
public title = 'Tour of Heroes';
public hero: Hero = {
id: 1,
name: 'Windstorm'
};
}
bootstrap(AppComponent);
<!-- TODO: Add this in when the next chapter exists
# **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 chapter.
-->