docs(guide): copyedit displaying-data

Also fix a few intros while I'm in _data.json.

closes #659

Author: kwalrath

public/docs/ts/latest/guide/_data.json

@@ -15,12 +15,12 @@
 
   "displaying-data": {
     "title": "Displaying Data",
-    "intro": "In Angular, we display data by binding component properties to elements in HTML templates using interpolation and other forms of Property Binding."
+    "intro": "Interpolation and other forms of property binding help us show app data in the UI."
   },
 
   "user-input": {
     "title": "User Input",
-    "intro": "User input triggers DOM events. We listen to those events with EventBindings that funnel updated values back into our components and models."
+    "intro": "User input triggers DOM events. We listen to those events with event bindings that funnel updated values back into our components and models."
   },
 
   "forms": {
@@ -35,24 +35,24 @@
 
   "template-syntax": {
     "title": "Template Syntax",
-    "intro": "How to write templates that display data and consume user events with the help of data binding."
+    "intro": "Learn how to write templates that display data and consume user events with the help of data binding."
   },
 
   "pipes": {
     "title": "Pipes",
-    "intro": "Pipes transform displayed values within a template"
+    "intro": "Pipes transform displayed values within a template."
   },
 
   "router": {
     "title": "Routing & Navigation",
-    "intro": "Discover the basics of screen navigation with the Angular 2 router"
+    "intro": "Discover the basics of screen navigation with the Angular 2 router."
   },
-  
+
   "lifecycle-hooks": {
     "title": "Lifecycle Hooks",
-    "intro": "Angular calls lifecycle hook methods on our directives and components as it creates, changes, and destroys them."
+    "intro": "Angular calls lifecycle hook methods on directives and components as it creates, changes, and destroys them."
   },
-  
+
   "attribute-directives": {
     "title": "Attribute Directives",
     "intro": "Attribute directives attach behavior to elements."

public/docs/ts/latest/guide/displaying-data.jade

@@ -3,22 +3,21 @@ include ../../../../_includes/_util-fns
 <!-- http://plnkr.co/edit/x9JYbC -->
 
 :marked
-  ## Displaying Component Properties
-
   We typically display data in Angular by binding controls in an HTML template
-  to properties of an Angular Component.
+  to properties of an Angular component.
 
   In this chapter, we'll create a component with a list of heroes. Each hero has a name.
   We'll display the list of hero names and
   conditionally show a selected hero in a detail area below the list.
 
-  [Live Example](/resources/live-examples/displaying-data/ts/plnkr.html)
-
-  Our final UI looks like this:
+  The final UI looks like this:
 
 figure.image-display
   img(src="/resources/images/devguide/displaying-data/final.png" alt="Final UI")
 
+:marked
+  [Run the live example](/resources/live-examples/displaying-data/ts/plnkr.html)
+
 <a id="interpolation"></a>
 .l-main-section
 :marked
@@ -39,25 +38,25 @@ figure.image-display
 :marked
   We added two properties to the formerly empty component: `title` and `myHero`.
 
-  Our revised template displays the two component properties using the double curly brace
+  Our revised template displays the two component properties using double curly brace
   interpolation:
 
 +makeExample('displaying-data/ts/app/app.component.1.ts', 'template')(format=".")
 .l-sub-section
   :marked
-    The template is a multi-line string within ECMAScript 2015 back-tics (\`).
-    The back-tick (\`) is not the same character as a single quote (').
-    It has many nice features. The feature we're exploiting is
-    the ability to compose the string over several lines which
-    makes for much more readable HTML.
+    The template is a multi-line string within ECMAScript 2015 backticks (\`).
+    The backtick (\`) &mdash; which is *not* the same character as a single
+    quote (') &mdash; has many nice features. The feature we're exploiting here
+    is the ability to compose the string over several lines, which makes for
+    much more readable HTML.
 
 :marked
   Angular automatically pulls the value of the `title` and `myHero` properties from the component and
-  inserts those values into the browser. Angular will update the display
+  inserts those values into the browser. Angular updates the display
   when these properties change.
 .l-sub-section
   :marked
-    More precisely, the re-display occurs after some kind of asynchronous event related to
+    More precisely, the redisplay occurs after some kind of asynchronous event related to
     the view such as a keystroke, a timer completion, or an async `XHR` response.
     We don't have those in this sample.
     But then the properties aren't changing on their own either. For the moment we must operate on faith.
@@ -88,12 +87,14 @@ figure.image-display
   ## Template inline or template file?
 
   We can store our component's template in one of two places.
-  We can define it "inline" using the template property as we do here.
+  We can define it *inline* using the `template` property, as we do here.
   Or we can define the template in a separate HTML file and link to it in
   the component metadata using the `@Component` decorator's `templateUrl` property.
 
-  We're using the *inline* style because the template is small and it makes for clearer demonstration.
-  The choice between them is a matter of taste, circumstances, and organization policy.
+  The choice between inline and separate HTML is a matter of taste,
+  circumstances, and organization policy.
+  Here we're using inline HTML because the template is small, and the demo
+  is simpler without the HTML file.
 
   In either style, the template data bindings have the same access to the component's properties.
 
@@ -106,7 +107,7 @@ figure.image-display
 +makeExample('displaying-data/ts/app/app-ctor.component.ts', 'app-ctor')(format=".")
 
 :marked
-  That's fine too. The choice between them is a matter of taste and organization policy.
+  That's fine too. The choice is a matter of taste and organization policy.
   We'll adopt the more terse "variable assignment" style in this chapter simply because
   there will be less code to read.
 
@@ -116,11 +117,11 @@ figure.image-display
   ## Showing an array property with NgFor
 
   We want to display a list of heroes. We begin by adding a mock heroes name array to the component,
-  just above `myHero` and redefine `myHero` to be the first name in the array.
+  just above `myHero`, and redefine `myHero` to be the first name in the array.
 +makeExample('displaying-data/ts/app/app.component.2.ts', 'mock-heroes', 'app/app.component.ts (class)')(format=".")
 
 :marked
-  Now we use the Angular `NgFor` "repeater" Directive in the template to display
+  Now we use the Angular `NgFor` "repeater" directive in the template to display
   each item in the `heroes` list.
 
 +makeExample('displaying-data/ts/app/app.component.2.ts', 'template','app/app.component.ts (template)')(format=".")
@@ -132,19 +133,19 @@ figure.image-display
 :marked
   We added a somewhat mysterious `*ngFor` to the `<li>` element.
   That's the Angular "repeater" directive.
-  It's presence on the `<li>` tag marks that `<li>` element (and its children) as the "repeater template".
+  Its presence on the `<li>` tag marks that `<li>` element (and its children) as the "repeater template".
 
 .alert.is-important
   :marked
-    Don't forget the leading asterisk (\*) in front of `*ngFor`. It is an essential part of the syntax.
+    Don't forget the leading asterisk (\*) in `*ngFor`. It is an essential part of the syntax.
     Learn more about this and `NgFor` in the [Template Syntax](./template-syntax.html#ngFor) chapter.
 
 :marked
   Notice the `#hero` in the `NgFor` double-quoted instruction.
-  The `#hero` is a "[template local variable](./template-syntax.html#local-vars")"  *declaration*.
-  The (#) prefix declares a local variable name named `hero`.
+  The `#hero` is a [local template variable](./template-syntax.html#local-vars) declaration.
+  The `#` prefix declares a local variable name named `hero`.
 
-  Angular will duplicate the `<li>` for each item in the list, setting the `hero` variable
+  Angular duplicates the `<li>` for each item in the list, setting the `hero` variable
   to the item (the hero) in the current iteration. Angular uses that variable as the
   context for the interpolation in the double curly braces.
 
@@ -168,67 +169,67 @@ figure.image-display
   That's fine for a demo but certainly isn't a best practice. It's not even a good practice.
   Although we won't do anything about that in this chapter, we'll make a mental note to fix this down the road.
 
-  At the moment, we're binding to an array of strings. We do that occasionally in real applications but
-  most of the time we're displaying objects, potentially instances of classes.
+  At the moment, we're binding to an array of strings. We do that occasionally in real applications, but
+  most of the time we're displaying objects &mdash; potentially instances of classes.
 
-  Let's turn our array of hero names into an array of `Hero` objects. For that we'll need a `Hero' class.
+  Let's turn our array of hero names into an array of `Hero` objects. For that we'll need a `Hero` class.
 
   Create a new file in the `app/` folder called `hero.ts` with the following short bit of code.
 +makeExample('displaying-data/ts/app/hero.ts', null, 'app/hero.ts')(format = ".")
 
 :marked
   We've defined a class with a constructor and two properties: `id` and `name`.
 
-  If we are new to TypeScript, it may not look like we have properties. But we do. We're taking
-  advantage of a TypeScript short-cut in our declaration of the constructor parameters.
+  It might not look like we have properties, but we do. We're taking
+  advantage of a TypeScript shortcut in our declaration of the constructor parameters.
 
   Consider the first parameter:
 +makeExample('displaying-data/ts/app/hero.ts', 'id-parameter')
 
 :marked
-  That brief syntax simultaneously
+  That brief syntax does a lot:
   * declares a constructor parameter and its type
-  * declare a public property of the same name
-  * initializes that property with the corresponding argument when we "new" an instance of the class.
+  * declares a public property of the same name
+  * initializes that property with the corresponding argument when we "new" an instance of the class
 
 .l-main-section
 :marked
-  ## Use the Hero class
-  Let's redefine the heroes property in our component to return an array of these Heroes
+  ## Using the Hero class
+  Let's redefine the `heroes` property in our component to return an array of these Hero objects
   and also set the `myHero` property with the first of these mock heroes.
 +makeExample('displaying-data/ts/app/app.component.3.ts', 'heroes', 'app.component.ts (excerpt)')(format=".")
 
 :marked
   We'll have to update the template.
-  At the moment it displays the entire hero object which used to be a string value.
-  Let's fix that so we interpolate the `hero.name` property
+  At the moment it displays the entire `hero` object, which used to be a string value.
+  Let's fix that so we interpolate the `hero.name` property.
 +makeExample('displaying-data/ts/app/app.component.3.ts', 'template','app.component.ts (template)')(format=".")
 
 :marked
-  Our display looks the same but we know how much better it is under the hood.
+  Our display looks the same, but now we know much better what a hero really is.
 
 <a id="ngIf"></a>
 .l-main-section
 :marked
   ## Conditional display with NgIf
 
-  Sometimes the app should display a view or a portion of a view only under prescribed circumstances.
+  Sometimes the app should display a view or a portion of a view only under specific circumstances.
 
-  In our example, we'd like to display a message if we have a large number of heroes ... say more than 3.
+  In our example, we'd like to display a message if we have a large number of heroes &mdash; say, more than 3.
 
-  The Angular `NgIf` directive will insert or remove an element based on a truthy/falsey condition.
+  The Angular `NgIf` directive inserts or removes an element based on a truthy/falsey condition.
   We can see it in action by adding the following paragraph at the bottom of the template:
 +makeExample('displaying-data/ts/app/app.component.ts', 'message')
 .alert.is-important
   :marked
-    Don't forget the leading asterisk (\*) in front of `*ngIf`. It is an essential part of the syntax.
+    Don't forget the leading asterisk (\*) in `*ngIf`. It is an essential part of the syntax.
     Learn more about this and `NgIf` in the [Template Syntax](./template-syntax.html#ngIf) chapter.
 
 :marked
   The [template expression](./template-syntax.html#template-expressions) inside the double quotes
-  looks much like JavaScript and it is much like JavaScript.
+  looks much like JavaScript and it _is_ much like JavaScript.
   When the component's list of heroes has more than 3 items, Angular adds the paragraph to the DOM and the message appears.
-  If there were 3 or fewer items, Angular omits the paragraph and there is no message.
+  If there are 3 or fewer items, Angular omits the paragraph, so no message appears.
 
 .alert.is-helpful
   :marked
@@ -237,31 +238,23 @@ figure.image-display
     we were conditionally including or excluding a big chunk of HTML with many data bindings.
 
 :marked
-  Try it out. We have four items in the array so the message should appear.
+  Try it out. Because the array has four items, the message should appear.
   Go back into `app.component.ts` and delete or comment out one of the elements from the hero array.
   The browser should refresh automatically and the message should disappear.
 
-  Play with it.
-
 .l-main-section
 :marked
   ## Summary
-  Now we know how to
-  - use **interpolation** with the double curly braces to display a component property,
-  - use **`NgFor`** to display a list of items,
-  - use a TypeScript class to shape the model data for our component and display properties of that model,
-  - use **`NgIf`** to conditionally display a chunk of HTML based on a boolean expression.
+  Now we know how to use:
+  - **interpolation** with double curly braces to display a component property
+  - **`NgFor`** to display a list of items
+  - a TypeScript class to shape the **model data** for our component and display properties of that model
+  - **`NgIf`** to conditionally display a chunk of HTML based on a boolean expression
 
-  Our final code:
+  Here's our final code:
 
 +makeTabs(`displaying-data/ts/app/app.component.ts,
            displaying-data/ts/app/hero.ts,
            displaying-data/ts/app/boot.ts`,
            'final,,',
            'app/app.component.ts, app/hero.ts, boot.ts')
-
-.l-main-section
-:marked
-  ## Next Steps
-  In addition to displaying data, most applications need to respond to user input.
-  Learn about that in the [User Input](./user-input.html) chapter.