diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index 323f39208f..18cb772d07 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/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." diff --git a/public/docs/ts/latest/guide/displaying-data.jade b/public/docs/ts/latest/guide/displaying-data.jade index 3926087275..6ef37cb15b 100644 --- a/public/docs/ts/latest/guide/displaying-data.jade +++ b/public/docs/ts/latest/guide/displaying-data.jade @@ -3,22 +3,21 @@ include ../../../../_includes/_util-fns :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) + .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 (\`) — which is *not* the same character as a single + quote (') — 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 `
  • ` element. That's the Angular "repeater" directive. - It's presence on the `
  • ` tag marks that `
  • ` element (and its children) as the "repeater template". + Its presence on the `
  • ` tag marks that `
  • ` 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 `
  • ` for each item in the list, setting the `hero` variable + Angular duplicates the `
  • ` 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,10 +169,10 @@ 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 — 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 = ".") @@ -179,56 +180,56 @@ figure.image-display :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. .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 — 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.