b0e0d94b5c
closes #1818 Previously, the markdown of some chapters was converted to Jade markup to support the conditional exclusion of TS prose parts in Dart chapters. This commit reverts some of that back to clean markdown, thanks to a few custom directives.
187 lines
7.1 KiB
Plaintext
187 lines
7.1 KiB
Plaintext
include ../_util-fns
|
||
|
||
:marked
|
||
# Once Upon a Time
|
||
|
||
Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
|
||
|
||
Run the <live-example></live-example> for this part.
|
||
|
||
Create a folder called `angular2-tour-of-heroes` and follow the [QuickStart](../quickstart.html) steps
|
||
which provide the prerequisites, the folder structure, and the core files for our Tour of Heroes.
|
||
|
||
include ../_quickstart_repo
|
||
:marked
|
||
We should have the following structure:
|
||
|
||
.filetree
|
||
.file angular2-tour-of-heroes
|
||
.children
|
||
.file app
|
||
.children
|
||
.file app.component.ts
|
||
.file main.ts
|
||
.file node_modules ...
|
||
.file typings ...
|
||
.file index.html
|
||
.file package.json
|
||
.file styles.css
|
||
.file systemjs.config.js
|
||
.file tsconfig.json
|
||
.file typings.json
|
||
:marked
|
||
## Keep the app transpiling and running
|
||
We want to start the TypeScript compiler, have it watch for changes, and start our server. We'll do this by typing
|
||
|
||
code-example(language="bash").
|
||
npm start
|
||
|
||
:marked
|
||
This command runs the compiler in watch mode, starts the server, launches the app in a browser,
|
||
and keeps the app running while we continue to build the Tour of Heroes.
|
||
|
||
.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".
|
||
|
||
+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'app-component-1', 'app.component.ts (AppComponent class)')(format=".")
|
||
|
||
:marked
|
||
Now we update the template in the `@Component` decoration with data bindings to these new properties.
|
||
|
||
+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero')
|
||
|
||
: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.html).
|
||
: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.
|
||
For now put this near the top of the `app.component.ts` file, just below the import statement.
|
||
|
||
+makeExample('toh-1/ts/app/app.component.ts', 'hero-class-1', 'app.component.ts (Hero class)')(format=".")
|
||
|
||
:marked
|
||
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".
|
||
|
||
+makeExample('toh-1/ts/app/app.component.ts', 'hero-property-1', 'app.component.ts (hero property)')(format=".")
|
||
|
||
:marked
|
||
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.
|
||
|
||
+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero-2')
|
||
: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`.
|
||
|
||
+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero-properties')
|
||
: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.
|
||
|
||
+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'multi-line-strings', 'app.component.ts (AppComponent\'s template)')
|
||
|
||
.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:
|
||
|
||
+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'editing-Hero', 'app.component.ts (input element)')
|
||
: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 **`ngModel`** built-in directive for two-way binding.
|
||
|
||
.l-sub-section
|
||
:marked
|
||
Learn more about `ngModel` in the
|
||
[Forms](../guide/forms.html#ngModel) and
|
||
[Template Syntax](../guide/template-syntax.html#ngModel) chapters.
|
||
:marked
|
||
Replace the `<input>` with the following HTML
|
||
|
||
code-example(language="html").
|
||
<input [(ngModel)]="hero.name" placeholder="name">
|
||
|
||
:marked
|
||
The browser refreshes. We see our hero again. We can edit the hero’s name and
|
||
see the changes reflected immediately in the `<h2>`.
|
||
|
||
.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 `ngModel` directive.
|
||
* The `ngModel` directive also propagates changes to every other binding of the `hero.name`.
|
||
|
||
Run the <live-example></live-example> for this part.
|
||
|
||
Here's the complete `app.component.ts` as it stands now:
|
||
|
||
+makeExample('toh-1/ts/app/app.component.ts', 'pt1', 'app.component.ts')
|
||
|
||
.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).
|