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

Show file tree
Hide file tree
Changes from all commits
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
156 changes: 68 additions & 88 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 @@ -2,17 +2,18 @@ include ../_util-fns

:marked
# Once Upon a Time

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

Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
**Try it out**. Here's a link to a <live-example></live-example>.
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 probably strike "Try it out", though it's better because it's shorter and more to the point than the original. How about something like what's on the Architecture page?

"The code referenced on this page is available as a 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,164 +33,143 @@ 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
To start the TypeScript compiler in watch mode and start the server, type the following:


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.
This command launches the app in a browser
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 app 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.
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 refreshes and display the title and hero name.
Copy link
Contributor

Choose a reason for hiding this comment

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

"and displays"


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).
Learn more about interpolation in the [Displaying Data page](../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.
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`,
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 change "Now in your" to "In the"

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.

### 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.
The browser refreshes and continues to display the hero's name.

### Multi-line template strings
### Adding HTML with multi-line template strings
Copy link
Contributor

Choose a reason for hiding this comment

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

What's your thought process on the headlines? (Maybe I've missed something - are we standardizing the grammar on them?)


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.
Displaying a name is good, but we want to see all of the hero's properties.
For this update, you'll add a `<div>` for the hero's `id` property and another `<div>` for the hero's `name`.
Copy link
Contributor

Choose a reason for hiding this comment

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

In this and the following sentence, remove the future tense (two instance of "you'll"). Sometimes "you can" works. For the sentence "Displaying a name is good...", you could remove it altogether, turn it into a phrase and start the next sentence with it. For example, "To show all of the hero's properties, you can...".

To keep the template readable, you'll make some additional changes using the template strings feature
in ES2015 and TypeScript:
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)')

.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.
// CF: I removed the note about backticks. It wasn't appearing in the browser and Naomi didn't think it was necessary.

.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
### 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.
and see those changes wherever we bind to the hero's name.
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 app uses.
Now you have included the forms package that includes `ngModel`.

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

.l-sub-section
:marked
Learn more about the `FormsModule` and `ngModel` in the
[Forms](../guide/forms.html#ngModel) and
[Template Syntax](../guide/template-syntax.html#ngModel) chapters.
[Template Syntax](../guide/template-syntax.html#ngModel) pages.

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

Replace the `<input>` with the following HTML
Now update the template to use the **`ngModel`** built-in directive for two-way binding.
In app.component.ts, replace the `<input>` with the following HTML:

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.

* Our Tour of Heroes uses the double curly braces of interpolation (a kind 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.

## The road you've travelled
Let's take stock of what you've built.

* The Tour of Heroes app uses the double curly braces of interpolation (a type of one-way data binding)
to display the app title and properties of a `Hero` object.
* 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`.

**Try it out**. Here's a link to a <live-example></live-example>.
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.

I prefer the way this sentence was originally since we don't need to specify that it's a link. That should be clear by the styles. We don't want it to read like "click here for more".

I'd check globally for consistency on this point whichever way you go on it.

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 a hero in the
[next tutorial chapter](./toh-pt2.html).
## The road ahead
In the [next tutorial page](./toh-pt2.html), 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.
Loading