From c8be00378175e9547f66bb309e975ade038ddcd4 Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Mon, 30 Nov 2015 14:13:24 -0800 Subject: [PATCH] (docs) devguide intro - fix typos and infelicities closes #420 --- .../intro/ts/src/app/backend.service.ts | 6 +-- .../ts/src/app/hero-detail.component.html | 8 +++- .../intro/ts/src/app/hero-list.component.ts | 1 + .../docs/_examples/intro/ts/src/app/hero.ts | 9 +++- public/docs/ts/latest/guide/index.jade | 42 +++++++++++-------- 5 files changed, 42 insertions(+), 24 deletions(-) diff --git a/public/docs/_examples/intro/ts/src/app/backend.service.ts b/public/docs/_examples/intro/ts/src/app/backend.service.ts index bfc629fc8c..ad76e0044b 100644 --- a/public/docs/_examples/intro/ts/src/app/backend.service.ts +++ b/public/docs/_examples/intro/ts/src/app/backend.service.ts @@ -10,9 +10,9 @@ export class BackendService { if (type === Hero) { // TODO get from the database and return as a promise return [ - new Hero('Windstorm'), - new Hero('Mr. Nice'), - new Hero('Magneta')]; + new Hero('Windstorm', 'Weather mastery'), + new Hero('Mr. Nice', 'Killing them with kindness'), + new Hero('Magneta', 'Manipulates metalic objects')]; } let err = new Error('Cannot get object of this type'); this._logger.error(err); diff --git a/public/docs/_examples/intro/ts/src/app/hero-detail.component.html b/public/docs/_examples/intro/ts/src/app/hero-detail.component.html index 6e32ecaade..0094c744d2 100644 --- a/public/docs/_examples/intro/ts/src/app/hero-detail.component.html +++ b/public/docs/_examples/intro/ts/src/app/hero-detail.component.html @@ -1,5 +1,9 @@
-Hero name: +

{{hero.name}} Detail

+
Id: {{hero.id}}
+
Name: - \ No newline at end of file + +
+
Power:
\ No newline at end of file diff --git a/public/docs/_examples/intro/ts/src/app/hero-list.component.ts b/public/docs/_examples/intro/ts/src/app/hero-list.component.ts index 120665b0ec..b583d4f390 100644 --- a/public/docs/_examples/intro/ts/src/app/hero-list.component.ts +++ b/public/docs/_examples/intro/ts/src/app/hero-list.component.ts @@ -29,6 +29,7 @@ export class HeroListComponent { this.heroes = service.getHeroes(); } // #enddocregion ctor + heroes:Hero[]; selectedHero:Hero; selectHero(hero: Hero) { this.selectedHero = hero; } diff --git a/public/docs/_examples/intro/ts/src/app/hero.ts b/public/docs/_examples/intro/ts/src/app/hero.ts index 4ff4d73792..df6c37a0f5 100644 --- a/public/docs/_examples/intro/ts/src/app/hero.ts +++ b/public/docs/_examples/intro/ts/src/app/hero.ts @@ -1,3 +1,10 @@ export class Hero { - constructor(public name:string){} + id:number + constructor( + public name:string, + public power?:string){ + this.id = nextId++; + } } + +var nextId = 1; diff --git a/public/docs/ts/latest/guide/index.jade b/public/docs/ts/latest/guide/index.jade index fb8b1ae3b7..8c59624adc 100644 --- a/public/docs/ts/latest/guide/index.jade +++ b/public/docs/ts/latest/guide/index.jade @@ -15,9 +15,9 @@ figure * What are the essential Angular building blocks and how do they help? * How do we minimize routine, mechanical coding in favor of declarative, higher level constructs without losing control? - This chapter is an introduction in two parts. + This chapter begins the journey. It's an introduction to Angular in two parts. 1. [How to read this guide](#how-to-read) - 2. [An Angular architectural overview](#architecture) + 2. [An architecture overview](#architecture) .l-main-section @@ -77,9 +77,9 @@ figure The framework consists of several cooperating libraries, some of them core and some optional. - We write applications by composing HTML templates with Angularized-markup, - writing "Component" classes to manage those templates, adding application logic in services, - and handing the top root component to Angular's bootstrapper. + We write applications by composing HTML *templates* with Angularized-markup, + writing *component* classes to manage those templates, adding application logic in *services*, + and handing the top root component to Angular's *bootstrapper*. Angular takes over, presenting our application content in a browser and responding to user interactions according to the instructions we provided. @@ -88,9 +88,12 @@ figure img(src="/resources/images/devguide/intro/airplane.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:10px" ) :marked Of course there is more to it than this. - We're cruising at high altitude in this chapter. - We're looking for landmarks. We should expect the details to be fuzzy and obscured by occasional clouds. + We're cruising at high altitude in this overview. + We're looking for landmarks. We should expect the object below to be fuzzy and obscured by occasional clouds. + Details become more clear and precise when we land in the chapters themselves. +
+:marked An Angular 2 application rests on seven main building blocks: 1. [Component](#component) 1. [Template](#template) @@ -112,11 +115,11 @@ figure figure img(src="/resources/images/devguide/intro/hero-component.png" alt="Component" align="left" style="width:200px; margin-left:-40px;margin-right:10px" ) :marked - A **Component** controls a patch of screen real estate that we could call a "view". + A **Component** controls a patch of screen real estate that we could call a *view*. The shell at the application root with navigation links, that list of heroes, the hero editor ... they're all views controlled by Components. - We define a Component's "application logic" - what it does to support the view - inside a class. + We define a Component's application logic - what it does to support the view - inside a class. The class interacts with the view through an API of properties and methods. @@ -131,9 +134,11 @@ figure The developer can take action at each moment in this lifecycle through optional [Lifecycle Hooks](#). .l-sub-section :marked - Our example shows the service arriving via the class constructor. - Who calls that constructor? Who provides the service? - For the moment, have faith that Angular is going to deliver an + We're not showing those hooks in this example + but we are making a mental note to find out about them later. + + We may wonder who is calling that constructor? Who provides the service parameter? + For the moment, have faith that Angular will call the constructor and deliver an appropriate `HeroService` when we need it. .l-main-section @@ -143,11 +148,11 @@ figure figure img(src="/resources/images/devguide/intro/template.png" alt="Template" align="left" style="width:200px; margin-left:-40px;margin-right:10px" ) :marked - We define a Component's view with its companion **Template**. A template is a form of HTML + We define a Component's view with its companion **template**. A template is a form of HTML that tells Angular how to render the Component. A template looks like regular HTML much of the time ... and then it gets a bit strange. Here is a - template for our `HeroList` Component + template for our `HeroList` component +makeExample('intro/ts/src/app/hero-list.component.html') :marked We recognize `

` and `
`. @@ -272,7 +277,8 @@ figure **Two-way data binding** is an important fourth form that combines property and event binding in a single notation using the `ng-model` directive. - We didn't have a two-way binding in the `HeroListComponent` template; here's an example from a different template: + We didn't have a two-way binding in the `HeroListComponent` template; + here's an example from the `HeroDetailComponent` template (not shown): +makeExample('intro/ts/src/app/hero-detail.component.html', 'ng-model')(format=".") :marked @@ -285,7 +291,7 @@ figure figure img(src="/resources/images/devguide/intro/component-databinding.png" alt="Data Binding" style="float:left; width:300px; margin-left:-40px;margin-right:10px" ) :marked - We don't know all the details yet + We don't know all the details yet but it's clear from these examples that data binding plays an important role in communication between a template and its component ...
@@ -303,7 +309,7 @@ figure img(src="/resources/images/devguide/intro/directive.png" alt="Parent child" style="float:left; width:150px; margin-left:-40px;margin-right:10px" ) :marked Our Angular templates are *dynamic*. When Angular renders them, it transforms the DOM - according to the instructions given by a **Directive**. + according to the instructions given by a **directive**. A directive is a class with directive metadata. In TypeScript we'd apply the `@Directive` decorator to attach metadata to the class. @@ -315,7 +321,7 @@ figure .l-sub-section :marked While the **component is technically a directive**, - it is so distictive and central to Angular applications that we chose + it is so distinctive and central to Angular applications that we chose to separate the component from the directive in our architectural overview. :marked There are two *other* kinds of directives as well that we call "structural" and "attribute" directives.