Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

[WIP] docs(toh): Initial edits with several questions for Naomi and Ward. #2685

Closed
wants to merge 5 commits into from
Closed

[WIP] docs(toh): Initial edits with several questions for Naomi and Ward. #2685

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f34cecd
Initial edits with several questions for Naomi and Ward.
cfranger Oct 21, 2016
4251e8c
WIP: testing push
cfranger Oct 27, 2016
7a6ad3b
WIP: added "CF: " to my comments/questions
cfranger Oct 27, 2016
da4e27d
WIP: 10/27 updates
cfranger Oct 28, 2016
c546dac
WIP: full edit pass on these pages, as well as some questions. Please…
cfranger Oct 29, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 64 additions & 57 deletions public/docs/ts/latest/tutorial/toh-pt1.jade
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,14 @@ 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>.

Run the <live-example></live-example> for this part.

Create a folder called `angular-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.
Create a folder called `angular-tour-of-heroes` and follow the [QuickStart](../quickstart.html) steps,
which provide the prerequisites, folder structure, and core files for the Tour of Heroes.

include ../_quickstart_repo
:marked
We should have the following structure:
You should have the following structure:

.filetree
.file angular-tour-of-heroes
Expand All @@ -32,80 +30,83 @@ include ../_quickstart_repo
.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
Type the following command:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is taking a little too much away. It's important for the reader to know why they are entering the command.

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.
and keeps the app running while you 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".
## Show Your Hero
To display Hero data in the app,
add two properties to the `AppComponent`: a `title` property for the application name and a `hero` property
<!-- Should we use "app" or "application", or if both, is there a distinction? -->
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.
Now 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 browser should refresh and display the title and hero name.
<!-- Do you prefer to present results directly or with "should"? I usually avoid the passive, but in this case
it could be justified. Either way, both styles are used in this chapter; can we choose one and be consistent? -->

The double curly braces tell our app to read the `title` and `hero` properties from the component and render them.
The double curly braces instruct the 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.
Our hero needs more properties.
Copy link
Contributor

@kapunahelewong kapunahelewong Oct 31, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do a global search for "our", "we", "let's", and "us". You want to get rid of all first person. Ideally, we want to minimize second person, too.

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.
For now, add these properties 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".
Now in your `Hero` class, refactor the component’s `hero` property to be of type `Hero`,
<!-- The Angular Team Writing Guidelines says to use straight quotes. Does that also apply to apostrophes?
I see a lot of curly apostrophes in the content, though not consistently. -->
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.
Because you changed the hero from a string to an object,
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.
The browser refreshes and continues to display the hero’s name.
<!-- "should refresh..."? -->

### 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`.
<!-- Can I remove this entire section and just explain the switch to multi-line strings in the next section? -->
Displaying a name is good, but we want to see all of the hero’s properties.
Add a `<div>` for the hero’s `id` property and another `<div>` for the 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.
Uh oh, the template string is getting long. Let's clean up the code to avoid making typos 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.
Let’s use the template strings feature
in ES2015 and TypeScript.

Change the quotes around the template to back-ticks and
Change the quotes around the template to backticks 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)')
Expand All @@ -119,33 +120,33 @@ code-example(language="bash").
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.
<!-- I don't see this content in the browser. Is it supposed to appear? -->

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd get rid of "We want to be able to" and make it more direct. I might even delete the sentence altogether and use the idea to introduce the next sentence.

"To edit the hero name in a textbox, refactor..."


Refactor the hero name `<label>` with `<label>` and `<input>` elements as shown below:
Refactor the hero name `<label>` with `<label>` and `<input>` elements as shown:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd delete "as shown" since that's implied by the use of the colon.


+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>`.
The hero’s name now appears in the `<input>` textbox.
But if you change the name, you'll notice that your change
isn't reflected in the `<h2>`. To get the desired behavior,
you'll implement two-way binding to `<input>`.
Copy link
Contributor

@kapunahelewong kapunahelewong Oct 31, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change you'll to "you can" or reword making it a clear bridge to the next section. I'd even look for a way of getting rid of "you" here. You could do a number of things here like incorporating the imperative or rewording/condensing. Here's a possibility:

"The hero's name now appears in the textbox but the h2 doesn't reflect changes without two-way binding."


### 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.
This is known as two-way data binding.

Before we can use two-way data binding for **form inputs**, we need to import the `FormsModule`
package in our Angular module. We add it to the `NgModule` decorator's `imports` array. This array contains the list
of external modules used by our application.
Now we have included the forms package which includes `ngModel`.
Before using two-way data binding for **form inputs**, import the `FormsModule`
package in your Angular module. Add the `FormsModule` to the `NgModule` decorator's `imports` array, which contains the list
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

your -> the

of external modules that the application uses.
Now you have included the forms package that includes `ngModel`.

+makeExample('toh-1/ts/app/app.module.ts', '', 'app.module.ts (FormsModule import)')

Expand All @@ -156,30 +157,34 @@ code-example(language="bash").
[Template Syntax](../guide/template-syntax.html#ngModel) chapters.

:marked
Let’s update the template to use the **`ngModel`** built-in directive for two-way binding.
Now update the template to use the **`ngModel`** built-in directive for two-way binding.

Replace the `<input>` with the following HTML
Replace the `<input>` with the following HTML:
<!-- Would it be helpful to start this sentence with "In app.component.ts, replace ..."
or will the proper file be obvious to the audience? -->

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

:marked
The browser refreshes. We see our hero again. We can edit the hero’s name and
The browser refreshes. Now you 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.
## The Road You’ve Travelled
Let’s take stock of what you’ve built.

* Our Tour of Heroes uses the double curly braces of interpolation (a kind of one-way data binding)
* The Tour of Heroes app uses the double curly braces of interpolation (a type 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`.
* You wrote a multi-line template using ES2015’s template strings to make the template readable.
* You added a two-way data binding to the `<input>` element
using the built-in `ngModel` directive. This binding both displays the hero’s name and allows users to change it.
* The `ngModel` directive propagates changes to every other binding of the `hero.name`.

Run the <live-example></live-example> for this part.
<!-- This seems unnecessary; users are instructed to run the live example at the beginning of the chapter,
and to refer to it throughout. -->

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

Expand All @@ -188,8 +193,10 @@ code-example(language="html").
.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
In the next chapter, you'll build on the Tour of Heroes app to display a list of heroes.
You'll also allow the user to select heroes and display their details.
You’ll learn more about how to retrieve lists, bind them to the
template, and allow a user to select a hero in the
[next tutorial chapter](./toh-pt2.html).
<!-- There is an auto-generated link to the next chapter at the end of every chapter,
so this link is redundant. Can I remove it? -->