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

Commit a678d57

Browse files
kwalrathkwalrath
committed
docs(dart/toh): add intro & toh-1 pages (#1063)
1 parent a5be02e commit a678d57

File tree

9 files changed

+300
-17
lines changed

9 files changed

+300
-17
lines changed

‎public/docs/_examples/toh-1/dart-snippets/app_component_snippets_pt1.dart

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// #docregion show-hero
2+
template: '<h1>{{title}}</h1><h2>{{hero}} details!</h2>'
3+
// #enddocregion show-hero
4+
5+
// #docregion show-hero-2
6+
template: '<h1>{{title}}</h1><h2>{{hero.name}} details!</h2>'
7+
// #enddocregion show-hero-2
8+
9+
// #docregion show-hero-properties
10+
template: '<h1>{{title}}</h1><h2>{{hero.name}} details!</h2><div><label>id: </label>{{hero.id}}</div><div><label>name: </label>{{hero.name}}</div>'
11+
// #enddocregion show-hero-properties
12+
13+
// #docregion multi-line-strings
14+
template: '''
15+
<h1>{{title}}</h1>
16+
<h2>{{hero.name}} details!</h2>
17+
<div><label>id: </label>{{hero.id}}</div>
18+
<div><label>name: </label>{{hero.name}}</div>'''
19+
// #enddocregion multi-line-strings
20+
21+
// #docregion editing-Hero
22+
template: '''
23+
<h1>{{title}}</h1>
24+
<h2>{{hero.name}} details!</h2>
25+
<div><label>id: </label>{{hero.id}}</div>
26+
<div>
27+
<label>name: </label>
28+
<div><input value="{{hero.name}}" placeholder="name"></div>
29+
</div>'''
30+
// #enddocregion editing-Hero
31+
32+
// #docregion app-component-1
33+
class AppComponent {
34+
String title = 'Tour of Heroes';
35+
Hero hero = 'Windstorm';
36+
}
37+
// #enddocregion app-component-1
38+
39+
// #docregion hero-property-1
40+
Hero hero = new Hero(1, 'Windstorm');
41+
// #enddocregion hero-property-1

‎public/docs/_examples/toh-1/dart/lib/app_component.dart

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
// #docregion pt1
2+
import 'package:angular2/core.dart';
3+
4+
// #docregion hero-class-1
5+
class Hero {
6+
final int id;
7+
String name;
8+
9+
Hero(this.id, this.name);
10+
}
11+
// #enddocregion hero-class-1
12+
13+
@Component(
14+
selector: 'my-app',
15+
template: '''
16+
<h1>{{title}}</h1>
17+
<h2>{{hero.name}} details!</h2>
18+
<div><label>id: </label>{{hero.id}}</div>
19+
<div>
20+
<label>name: </label>
21+
<div><input [(ngModel)]="hero.name" placeholder="name"></div>
22+
</div>'''
23+
)
24+
class AppComponent {
25+
String title = 'Tour of Heroes';
26+
Hero hero = new Hero(1, 'Windstorm');
27+
}
28+
// #enddocregion pt1

‎public/docs/_examples/toh-1/dart/pubspec.yaml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# #docregion
2+
name: angular2_tour_of_heroes
3+
version: 0.0.1
4+
environment:
5+
sdk: '>=1.13.0 <2.0.0'
6+
dependencies:
7+
angular2: 2.0.0-beta.14
8+
browser: ^0.10.0
9+
dart_to_js_script_rewriter: ^1.0.1
10+
transformers:
11+
- angular2:
12+
platform_directives:
13+
- package:angular2/common.dart#COMMON_DIRECTIVES
14+
platform_pipes:
15+
- package:angular2/common.dart#COMMON_PIPES
16+
entry_points: web/main.dart

‎public/docs/_examples/toh-1/dart/web/index.html

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>Angular 2 Tour of Heroes</title>
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<link rel="stylesheet" href="styles.css">
7+
8+
<script defer src="main.dart" type="application/dart"></script>
9+
<script defer src="packages/browser/dart.js"></script>
10+
</head>
11+
<body>
12+
<my-app>Loading...</my-app>
13+
</body>
14+
</html>

‎public/docs/_examples/toh-1/dart/web/main.dart

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// #docregion pt1
2+
import 'package:angular2/bootstrap.dart';
3+
4+
import 'package:angular2_tour_of_heroes/app_component.dart';
5+
6+
main() {
7+
bootstrap(AppComponent);
8+
}
9+
// #enddocregion pt1

‎public/docs/dart/latest/tutorial/_data.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"index": {
33
"title": "Tutorial: Tour of Heroes",
44
"navTitle": "Introduction",
5-
"intro": "The Tour of Heroes tutorial takes us through the steps of creating an Angular application in TypeScript.",
5+
"intro": "The Tour of Heroes tutorial takes us through the steps of creating an Angular application in Dart.",
66
"nextable": true
77
},
88
"toh-pt1": {

‎public/docs/dart/latest/tutorial/index.jade

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,9 @@
11
include ../_util-fns
22

3+
+includeShared('{ts}', 'intro')
4+
35
:marked
4-
We're working on the Dart version of this case study.
5-
In the meantime, please see these resources:
6+
[View the source code](https://github.com/angular/angular.io/tree/master/public/docs/_examples/toh-5/dart)
67

7-
* [Introduction](/docs/ts/latest/tutorial/index.html):
8-
The TypeScript version of this chapter
8+
+includeShared('{ts}', 'main')
99

10-
* [Dart source code](https://github.com/angular/angular.io/tree/master/public/docs/_examples/toh-5/dart):
11-
A preliminary Dart version of the Tour of Heroes app,
12-
featuring the hero editor, master/detail views,
13-
multiple components, services, and routing

‎public/docs/dart/latest/tutorial/toh-pt1.jade

Lines changed: 183 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,189 @@
11
include ../_util-fns
22

33
:marked
4-
We're working on the Dart version of this case study.
5-
In the meantime, please see these resources:
4+
# Once Upon a Time
65

7-
* [The Hero Editor](/docs/ts/latest/tutorial/toh-pt1.html):
8-
The TypeScript version of this chapter
6+
Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
97

10-
* [Dart source code](https://github.com/angular/angular.io/tree/master/public/docs/_examples/toh-5/dart):
11-
A preliminary Dart version of the Tour of Heroes app,
12-
featuring the hero editor, a master/detail page,
13-
multiple components, services, and routing
8+
:marked
9+
Follow the "QuickStart" steps. They provide the prerequisites, the folder structure,
10+
and the core files for our Tour of Heroes.
11+
12+
<!--
13+
TODO: Recommend stagehand?
14+
-->
15+
16+
Copy the "QuickStart" code to a new folder and rename the folder `angular2_tour_of_heroes`.
17+
We should have the following structure:
18+
19+
.filetree
20+
.file angular2_tour_of_heroes
21+
.children
22+
.file lib
23+
.children
24+
.file app_component.dart
25+
.file web
26+
.children
27+
.file index.html
28+
.file main.dart
29+
.file pubspec.yaml
30+
31+
// Add .file styles.css
32+
33+
.p &nbsp;
34+
35+
.callout.is-helpful
36+
header Source code
37+
:marked
38+
The complete source code for the example app in this chapter is
39+
[in GitHub](https://github.com/angular/angular.io/tree/master/public/docs/_examples/toh-1/dart).
40+
41+
:marked
42+
## Keep the app compiling and running
43+
We want to start the Dart compiler, have it watch for changes, and start our server. We'll do this by typing
44+
45+
code-example(format="" language="bash").
46+
pub serve
47+
48+
:marked
49+
This command runs the compiler in watch mode, starts the server,
50+
and keeps the app running while we continue to build the Tour of Heroes.
51+
52+
.l-main-section
53+
:marked
54+
## Show our Hero
55+
We want to display Hero data in our app.
56+
57+
Let's add two properties to our `AppComponent`, a `title` property for the application name and a `hero` property
58+
for a hero named "Windstorm".
59+
60+
+makeExample('toh-1/dart-snippets/app_component_snippets_pt1.dart', 'app-component-1', 'app_component.dart (AppComponent class)')(format=".")
61+
62+
:marked
63+
Now we update the template in the `@Component` annotation with data bindings to these new properties.
64+
65+
+makeExample('toh-1/dart-snippets/app_component_snippets_pt1.dart', 'show-hero')
66+
67+
:marked
68+
The browser should refresh and display our title and hero.
69+
70+
The double curly braces tell our app to read the `title` and `hero` properties from the component and render them.
71+
This is the "interpolation" form of one-way data binding.
72+
.l-sub-section
73+
:marked
74+
Learn more about interpolation in the [Displaying Data chapter](../guide/displaying-data.html).
75+
:marked
76+
### Hero object
77+
78+
At the moment, our hero is just a name. Our hero needs more properties.
79+
Let's convert the `hero` from a literal string to a class.
80+
81+
Create a `Hero` class with `id` and `name` properties.
82+
Keep this near the top of the `app_component.dart` file for now.
83+
84+
+makeExample('toh-1/dart/lib/app_component.dart', 'hero-class-1', 'app_component.dart (Hero class)')(format=".")
85+
86+
:marked
87+
Now that we have a `Hero` class, let’s refactor our component’s `hero` property to be of type `Hero`.
88+
Then initialize it with an id of `1` and the name, "Windstorm".
89+
90+
+makeExample('toh-1/dart-snippets/app_component_snippets_pt1.dart', 'hero-property-1', 'app_component.dart (Hero property)')(format=".")
91+
92+
:marked
93+
Because we changed the hero from a string to an object,
94+
we update the binding in the template to refer to the hero’s `name` property.
95+
96+
+makeExample('toh-1/dart-snippets/app_component_snippets_pt1.dart', 'show-hero-2')
97+
:marked
98+
The browser refreshes and continues to display our hero’s name.
1499

100+
### Adding more HTML
101+
Displaying a name is good, but we want to see all of our hero’s properties.
102+
We’ll add a `<div>` for our hero’s `id` property and another `<div>` for our hero’s `name`.
103+
104+
+makeExample('toh-1/dart-snippets/app_component_snippets_pt1.dart', 'show-hero-properties')
105+
:marked
106+
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.
107+
108+
### Multi-line template strings
109+
110+
We could make a more readable template with string concatenation
111+
but that gets ugly fast, it is harder to read, and
112+
it is easy to make a spelling error. Instead,
113+
let’s take advantage of the template strings feature
114+
in Dart to maintain our sanity.
115+
116+
Change the quotes around the template to triple quotes and
117+
put the `<h1>`, `<h2>` and `<div>` elements on their own lines.
118+
119+
+makeExample('toh-1/dart-snippets/app_component_snippets_pt1.dart', 'multi-line-strings', 'app_component.dart (AppComponent\'s template)')(format=".")
120+
121+
// omit back-tick warning
122+
123+
.l-main-section
124+
:marked
125+
## Editing Our Hero
126+
127+
We want to be able to edit the hero name in a textbox.
128+
129+
Refactor the hero name `<label>` with `<label>` and `<input>` elements as shown below:
130+
131+
+makeExample('toh-1/dart-snippets/app_component_snippets_pt1.dart', 'editing-Hero', 'app_component.dart (input element)')(format=".")
132+
:marked
133+
We see in the browser that the hero’s name does appear in the `<input>` textbox.
134+
But something doesn’t feel right.
135+
When we change the name, we notice that our change
136+
is not reflected in the `<h2>`. We won't get the desired behavior
137+
with a one-way binding to `<input>`.
138+
139+
### Two-Way Binding
140+
141+
We intend to display the name of the hero in the `<input>`, change it,
142+
and see those changes wherever we bind to the hero’s name.
143+
In short, we want two-way data binding.
144+
145+
Let’s update the template to use the **`ngModel`** built-in directive for two-way binding.
146+
147+
.l-sub-section
148+
:marked
149+
Learn more about `ngModel` in the
150+
[Forms](../guide/forms.html#ngModel) and
151+
[Template Syntax](../guide/template-syntax.html#ngModel) chapters.
152+
:marked
153+
Replace the `<input>` with the following HTML
154+
155+
code-example(language="html").
156+
&lt;input [(ngModel)]="hero.name" placeholder="name">
157+
158+
:marked
159+
The browser refreshes. We see our hero again. We can edit the hero’s name and
160+
see the changes reflected immediately in the `<h2>`.
161+
162+
.l-main-section
163+
:marked
164+
## The Road We’ve Travelled
165+
Let’s take stock of what we’ve built.
166+
167+
* Our Tour of Heroes uses the double curly braces of interpolation (a form of one-way data binding)
168+
to display the application title and properties of a `Hero` object.
169+
* We wrote a multi-line template using Dart's template strings to make our template readable.
170+
* We can both display and change the hero’s name after adding a two-way data binding to the `<input>` element
171+
using the built-in `ngModel` directive.
172+
* The `ngModel` directive also propagates changes to every other binding of the `hero.name`.
173+
174+
<!-- TODO:
175+
add [Run the live example for part 1](https://tour-of-heroes.firebaseapp.com/toh1/)
176+
-->
177+
178+
Here's the complete `app_component.dart` as it stands now:
179+
180+
+makeExample('toh-1/dart/lib/app_component.dart', 'pt1', 'app_component.dart')
181+
182+
.l-main-section
183+
:marked
184+
## The Road Ahead
185+
Our Tour of Heroes only displays one hero and we really want to display a list of heroes.
186+
We also want to allow the user to select a hero and display their details.
187+
We’ll learn more about how to retrieve lists, bind them to the
188+
template, and allow a user to select it in the
189+
[next tutorial chapter](./toh-pt2.html).

‎public/docs/ts/latest/tutorial/index.jade

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
include ../_util-fns
22

3+
// #docregion intro
34
:marked
45
# Tour of Heroes: the vision
56

@@ -23,9 +24,11 @@ include ../_util-fns
2324
Angular can do whatever we need it to do.
2425
We'll be covering a lot of ground at an introductory level but we’ll find plenty of links
2526
to chapters with greater depth.
27+
// #enddocregion intro
2628
2729
[Run the live example](/resources/live-examples/tutorial/ts/plnkr.html)
2830
31+
// #docregion main
2932
.l-main-section
3033
:marked
3134
## The End Game
@@ -82,3 +85,4 @@ figure.image-display
8285
And we’ll meet many of the core fundamentals of Angular along the way.
8386

8487
[Let's get started!](./toh-pt1.html)
88+
// #enddocregion main

0 commit comments

Comments
 (0)