honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore(jade): upgrade to use `marked` filter 

The `Transformers.markdown` (`:markdown`) filter is deprecated. This commit updates
the entire docs project to use the `jstransformer-marked` (`:marked') filter.
This commit is contained in:
Peter Bacon Darwin 2015-11-10 18:31:46 +00:00
parent 0f61ea288f
commit e86fde8dc9
31 changed files with 1866 additions and 1865 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
package.json
View File

@ -60,5 +60,8 @@
"q": "^1.4.1",
"typescript": "~1.5.3",
"yargs": "^3.23.0"
},
"dependencies": {
"jstransformer-marked": "^1.0.1"
}
}

58
public/docs/_includes/styleguide/_code-examples.jade
View File

@ -11,7 +11,7 @@ include ../../../_includes/_util-fns
.showcase-content
.l-sub-section
:markdown
:marked
### Including a code example from the `_examples` folder
One of the design goals for this documention was that any code samples that appear within the documentation be 'testable'.
@ -35,7 +35,7 @@ include ../../../_includes/_util-fns
code-example(language="js").
include ../../../../_includes/_util-fns
:markdown
:marked
The syntax for the `makeExample` mixin is:
#### +makeExample(filePath, region, title, stylePattern)
@ -49,14 +49,14 @@ include ../../../_includes/_util-fns
code-example(format="linenums" language="js").
+makeExample('styleguide/js/index.html', null, 'index.html')
:markdown
:marked
This will read the *_examples/styleguide/js/index.html* file and include it
with the heading 'index.html'. Note that the file will be properly escaped and
color coded according to the extension on the file ( html in this case).
+makeExample('styleguide/js/index.html', null, 'index.html')
:markdown
:marked
The second parameter with a value of 'null' will be described later in this document.
There is a similar `makeTabs` mixin that provides the same service but for multiple examples
@ -73,13 +73,13 @@ include ../../../_includes/_util-fns
code-example(format="linenums" language="js").
+makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test')
:markdown
:marked
This will create two tabs, each with its own title and appropriately color coded.
+makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test')
.l-sub-section
:markdown
:marked
### Marking up an example file for use by the `makeExample` and `makeTabs` mixins
At a minimum, marking up an example file simply consists of adding a single comment line to the top of the file
@ -98,7 +98,7 @@ include ../../../_includes/_util-fns
});
});
:markdown
:marked
If a file only has a single `#docregion` then the entire file AFTER the `#docregion` comment is available for inclusion
via mixin. Portions of the file can be indicated by surrounding an area of the file with
`#docregion` and an `#enddocregion` tags. These regions, each with its own name, may be nested to any level and any regions that are not 'ended' explicitly
@ -130,7 +130,7 @@ include ../../../_includes/_util-fns
// #enddocregion
// #enddocregion
:markdown
:marked
Multiple `#docregion` tags may be defined on a single line as shown below. In addition, anytime a file contains multiple
`#docregion` tags with the same name they will automatically be combined. Each of the individually tagged sections of the combined document
will be separated from one another by a comment consisting of '. . .'. This default separator, known
@ -158,7 +158,7 @@ include ../../../_includes/_util-fns
doSomethingInteresting();
// #enddocregion
:markdown
:marked
HTML files can also contain #docregion comments:
code-example(format="linenums" language="html" escape="html").
@ -168,7 +168,7 @@ include ../../../_includes/_util-fns
<script src="app.js"></script>
...
:markdown
:marked
as can CSS files:
code-example(format="linenums" language="css").
@ -179,7 +179,7 @@ include ../../../_includes/_util-fns
}
.l-sub-section
:markdown
:marked
### Including a named #docregion via the makeExample or makeTabs mixins.
In order to include just a portion of an example file that has been marked up with a 'named' `#docregion`
@ -189,14 +189,14 @@ include ../../../_includes/_util-fns
code-example(format="linenums" language="js").
+makeExample('styleguide/js/app.js', 'class-w-annotations', "Extracted region")
:markdown
:marked
is a request to include just the `class-w-annotations` region from the `app.js` file in the `_examples/styleguide`
folder and results in the following:
+makeExample('styleguide/js/app.js', 'class-w-annotations', "Extracted region")
.l-sub-section
:markdown
:marked
### Additional styling
In some cases you may want to add additional styling to an external file after it had been included in the documentation.
@ -215,7 +215,7 @@ include ../../../_includes/_util-fns
code-example(format="linenums" language="js" escape="none").
+makeExample('styleguide/js/index.html', null, 'index.html', {pnk: /script (src=.*&ampquot;)/g})
:markdown
:marked
Which will mark all of the quoted contents of each `script` tag within the index.html file in pink.
.alert.is-important.
@ -224,20 +224,20 @@ include ../../../_includes/_util-fns
+makeExample('styleguide/js/index.html', null, 'index.html', {pnk: /script (src=.*&quot;)/g})
:markdown
:marked
A more complicated example might be:
code-example(format="linenums" language="js").
- var stylePattern = { pnk: /script (src=.*&ampquot;)/g, otl: /(\S*my-app.*$)/m };
+makeExample('styleguide/js/index.html', null, 'index.html', stylePattern )
:markdown
:marked
Which applies multiple styles and uses an intermediate javascript object as opposed to a literal.
- var stylePattern = { pnk: /script (src=.*&quot;)/g, otl: /(\S*my-app.*$)/m };
+makeExample('styleguide/js/index.html', null, 'index.html', stylePattern )
:markdown
:marked
`makeTabs` support for `stylePatterns` is slightly different from the `makeExample` mixin in that you can also
pass in an array of stylePattern objects where each is paired with its corresponding 'tab'. If only a single stylePattern
object is passed in then it is assumed to apply to all of the tabs.
@ -250,7 +250,7 @@ include ../../../_includes/_util-fns
+makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test', stylePatterns)
.l-sub-section
:markdown
:marked
### Including a JSON file or just parts of one
To include an '.json' file from somewhere in the `doc\_examples` folder you can use the `makeJson` mixin. The `makeExample`
@ -277,7 +277,7 @@ include ../../../_includes/_util-fns
+makeJson('styleguide/package.json', null, "Entire package.json file")
:markdown
:marked
A subset of the '.json' file can also be selected.
code-example(format="linenums" language="js").
@ -285,7 +285,7 @@ include ../../../_includes/_util-fns
+makeJson('styleguide/package.json', { paths: 'version, scripts.tsc, scripts.start '}, "Selected parts of the package.json file" )
:markdown
:marked
Styling selected portions of the json is also supported.
code-example(format="linenums" language="js").
@ -293,7 +293,7 @@ include ../../../_includes/_util-fns
+makeJson('styleguide/package.json', {paths: 'dependencies'}, "package.json dependencies", { pnk: [/(\S*traceur.*)/, /(\Sangular2.*)/, /(\Ssystem.*)/ ]})
:markdown
:marked
As well as styling across multiple lines.
code-example(format="linenums" language="js").
@ -304,7 +304,7 @@ include ../../../_includes/_util-fns
+makeJson('styleguide/package.json', {paths: 'name, version, dependencies '}, "Foo", styles )
.l-sub-section
:markdown
:marked
### Inline code and code examples provided directly i.e. not from an example file.
The `makeExample` and `makeTabs` mixins are both both built on top of a custom jade 'style'; `code-example`.
@ -391,7 +391,7 @@ include ../../../_includes/_util-fns
// TAB 2 CONTENT
.l-sub-section
:markdown
:marked
### Combining makeExample, makeTabs mixins with code-example style attributes
As mentioned above the `makeExample` and `makeTabs` mixins are built on top of the `code-example` style. By default
the mixins automatically determine a language based on the example file's extensions and always include line numbers.
@ -403,12 +403,12 @@ include ../../../_includes/_util-fns
code-example().
+makeExample('styleguide/js/app.js', "class-w-annotations")(format="linenums:15")
:markdown
:marked
Starts the numbering of the example at line 15.
+makeExample('styleguide/js/app.js', "class-w-annotations")(format="linenums:15")
:markdown
:marked
Or to suppress line numbering completely you can use
code-example().
@ -417,7 +417,7 @@ include ../../../_includes/_util-fns
+makeExample('styleguide/js/app.js', 'class-w-annotations')(format=".")
.l-sub-section
:markdown
:marked
### Code examples in angular/angular source code
References to embedded example code in the angular/angular source make use of the same mixins as defined above, but with a slightly different
@ -431,7 +431,7 @@ include ../../../_includes/_util-fns
Example files referenced by inline tags are all assumed to be in the 'modules/angular2' folder in the angular/angular repo.
:markdown
:marked
#### @example inline tag parameters
- *filePath:* path to the example file under the '_examples' folder
- *region:* (optional or null) region from the example file to display
@ -452,7 +452,7 @@ include ../../../_includes/_util-fns
* {@example core/directives/ng_if_spec.ts foo title='Foo' }
**/
:markdown
:marked
#### @exampleTabs inline tag parameters
- *filePaths:* a comma delimited string of filePaths to example files under the '_examples' folder
- *regions:* (optional or null) region from the example file to display
@ -469,7 +469,7 @@ include ../../../_includes/_util-fns
**/
.l-sub-section
:markdown
:marked
### Cross references to Developer guide pages in angular/angular source comments.
The '{@linkDevGuide ... }' inline tag is intended to be used to create links from api documentation to dev guide

16
public/docs/dart/latest/quickstart.jade
View File

@ -1,11 +1,11 @@
include ../../../_includes/_util-fns
:markdown
:marked
Let's start from zero and build a super simple Angular 2 application in Dart.
.callout.is-helpful
header Don't want Dart?
:markdown
:marked
Although we're getting started in Dart, you can also write Angular 2 apps
in TypeScript and JavaScript.
Just select either of those languages from the combo-box in the banner.
@ -27,7 +27,7 @@ p.
.l-main-section
h2#section-install-angular Set up a new app directory
:markdown
:marked
Create a new directory,
and put a file named `pubspec.yaml` in it.
@ -73,7 +73,7 @@ p.
+makeExample('quickstart/dart/ex1/web/main.dart', null, 'web/main.dart')
:markdown
:marked
You've just defined an Angular 2 **component**,
one of the most important Angular 2 features.
Components are the primary way to create application views
@ -121,7 +121,7 @@ p.
+makeExample('quickstart/dart/ex1/web/index.html', null, 'web/index.html')
:markdown
:marked
The `<my-app>` tag in the `<body>` is
the custom HTML element defined in the Dart file.
@ -149,7 +149,7 @@ p.
Once the app is running,
you should see <b>My First Angular 2 App</b> in your browser window.
:markdown
:marked
If you don't see that, make sure you've entered all the code correctly
and run `pub get`.
@ -158,14 +158,14 @@ p.
h2#section-angular-run-app Generate JavaScript
:markdown
:marked
Before you can deploy your app, you need to generate JavaScript files.
Pub build makes that easy.
To improve your app's performance, convert the
HTML file to directly include the generated JavaScript;
one way to do that is with dart_to_js_script_rewriter.
:markdown
:marked
Add the dart_to_js_script_rewriter package to your pubspec,
in both the `dependencies` and `transformers` sections.

96
public/docs/js/latest/quickstart.jade
View File

@ -1,54 +1,54 @@
include ../../../_includes/_util-fns
:markdown
:marked
Let's start from zero and build a simple Angular 2 application in JavaScript.
.callout.is-helpful
header Don't want JavaScript?
:markdown
:marked
Although we're getting started in JavaScript, you can also write Angular 2 apps
in TypeScript and Dart by selecting either of those languages from the combo-box in the banner.
:markdown
:marked
We'll do it in six short steps
1. Create a project folder
1. Install essential libraries
1. Write the root component for our application in *app.js*
1. Bootstrap the app
1. Bootstrap the app
1. Create an *index.html*
1. Run it
.l-main-section
:markdown
:marked
## Create a project folder
**Create a new folder** to hold our application project, perhaps like this:
```
mkdir angular2-quickstart
cd angular2-quickstart
```
.l-main-section
:markdown
:marked
## Install essential libraries
We'll use the **npm package manager** to install packages for
the libraries and development tools we need:
the libraries and development tools we need:
>angular2 - the Angular 2 library.
>[live-server](https://www.npmjs.com/package/live-server "Live-server")
>[live-server](https://www.npmjs.com/package/live-server "Live-server")
a static file server that reloads the browser when files change.
We could reference the libraries on the web or download them to our project.
We could reference the libraries on the web or download them to our project.
That isn't a sustainable development process and package loading with npm is really
easy once we have it installed.
.alert.is-helpful
:markdown
.alert.is-helpful
:marked
Don't have npm? [Get it now](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm")
because we're going to use it now and repeatedly throughout this documentation.
:markdown
:marked
**Open** a terminal window and enter these commands:
```
npm init -y
@ -61,24 +61,24 @@ include ../../../_includes/_util-fns
+makeJson('quickstart/js/package.json', { paths: 'name, version, dependencies, devDependencies'})
:markdown
:marked
There is also a `scripts` section. **Find and replace** it with the following:
+makeJson('quickstart/js/package.json', { paths: 'scripts'})
:markdown
:marked
We've just extended our project world with a script command that we'll be running very soon.
.l-main-section
:markdown
:marked
## Our first Angular component
Add a new file called *app.js* and paste the following lines:
+makeExample('quickstart/js/app.js', 'class-w-annotations')
:markdown
We're creating a visual component named **`AppComponent`** by chaining the
:marked
We're creating a visual component named **`AppComponent`** by chaining the
`Component` and `Class` methods that belong to the **global Angular namespace, `ng`**.
```
@ -88,12 +88,12 @@ include ../../../_includes/_util-fns
```
The **`Component`** method takes a configuration object with two
properties. The `selector` property tells Angular that this is a component
controlling a host element named "my-app".
controlling a host element named "my-app".
Angular creates and displays an instance of our `AppComponent`
wherever it encounters a `my-app` element.
The `template` property defines the visual appearance of the component.
We're writing the HTML template inline in this example.
We're writing the HTML template inline in this example.
Later we'll move the HTML to a view template file and
assign the template's filename to the `templateUrl` property.
We'll prefer that practice for all but the most trivial templates.
@ -101,24 +101,24 @@ include ../../../_includes/_util-fns
The **`Class`** method is where we implement the component itself,
giving it properties and methods that bind to the view and whatever
behavior is appropriate for this part of the UI.
This component class has the bare minimum implementation:
a *no-op* constructor function that does nothing because there is nothing to do.
We'll see more interesting component classes in future examples.
.l-main-section
:markdown
:marked
## Bootstrap the app
We need to do something to put our application in motion.
Add the following to the bottom of the `app.js` file:
+makeExample('quickstart/js/app.js', 'bootstrap')
:markdown
:marked
We'll wait for the browser to tell us that it has finished loading
all content and then we'll call the Angular `bootstrap` method.
The `bootstrap` method tells Angular to start the application with our
The `bootstrap` method tells Angular to start the application with our
`AppComponent` at the application root.
We'd be correct to guess that someday our application will
consist of more components arising in tree-like fashion from this root.
@ -126,22 +126,22 @@ include ../../../_includes/_util-fns
### Wrapped in an IIFE
We don't want to pollute the global namespace.
We don't need an application namespace yet.
So we'll surround the code in a simple IIFE
("Immediately Invoked Function Execution")
So we'll surround the code in a simple IIFE
("Immediately Invoked Function Execution")
wrapper.
Here is the entire file:
+makeExample('quickstart/js/app.js', 'dsl')
.l-main-section
:markdown
:marked
## Create an *index.html*
**Add a new `index.html`** file to the project folder and enter the following HTML
+makeExample('quickstart/js/index.html', null, 'index.html')(format="")
.l-sub-section
:markdown
:marked
Our app loads two script files in the `<head>` element:
>***angular2.sfx.dev.js***, the Angular 2 development library that puts
@ -149,15 +149,15 @@ include ../../../_includes/_util-fns
>***app.js***, the application JavaScript we just wrote.
In the `<body>`, there's an element called `<my-app>`.
In the `<body>`, there's an element called `<my-app>`.
This is the placeholder for the *root* of the
application. Angular displays our application here.
.l-main-section
:markdown
:marked
## Run it!
We need a file server to serve the static assets of our application
We need a file server to serve the static assets of our application
(*index.html* and *app.js*).
For this example we'll use the **live-server** that we installed with `npm`
@ -170,27 +170,27 @@ include ../../../_includes/_util-fns
code npm start
.alert.is-helpful
:markdown
:marked
That's the `npm` command we added earlier to the `scripts` section of `package.json`
:markdown
:marked
**live-server** loads the browser for us and refreshes the page as we make
changes to the application.
In a few moments, a browser tab should open and display
figure.image-display
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")
:markdown
:marked
### Make some changes
The `live-server` detects changes to our files and refreshes the browser page for us automatically.
Try changing the message to "My SECOND Angular 2 app".
Try changing the message to "My SECOND Angular 2 app".
The `live-server` sees that change and reloads the browser.
Keep `live-server` running in this terminal window and keep trying changes.
Keep `live-server` running in this terminal window and keep trying changes.
You can stop it anytime with `Ctrl-C`.
**Congratulations! We are in business** ... and ready to take
our app to the next level.

422
public/docs/ts/latest/guide/dependency-injection.jade
View File

@ -1,26 +1,26 @@
include ../../../../_includes/_util-fns
:markdown
:marked
Dependency Injection is an important application design pattern.
Angular has its own Dependency Injection framework and
Angular has its own Dependency Injection framework and
we really can't build an Angular application without it.
In this chapter we'll learn what Dependency Injection is, why we want it, and how to use it.
<a name="why-di"></a>
.l-main-section
:markdown
:marked
## Why Dependency Injection?
Let's start with the following code.
Let's start with the following code.
```
class Engine {}
class Tires {}
class Car {
private engine: Engine;
private tires: Tires;
constructor() {
this.engine = new Engine();
this.tires = new Tires();
@ -29,49 +29,49 @@ include ../../../../_includes/_util-fns
drive() {}
}
```
Our `Car` creates everything it needs inside its constructor.
What's the problem?
Our `Car` creates everything it needs inside its constructor.
What's the problem?
The problem is that our `Car` class is brittle, inflexible, and hard to test.
Our `Car` needs an engine and tires. Instead of asking for them,
the `Car` constructor creates its own copies by "new-ing" them from
the very specific classes, `Engine` and `Tires`.
What if the `Engine` class evolves and its constructor requires a parameter?
Our `Car` is broken and stays broken until we rewrite it along the lines of
`this.engine = new Engine(theNewParameter)`.
Our `Car` is broken and stays broken until we rewrite it along the lines of
`this.engine = new Engine(theNewParameter)`.
We didn't care about `Engine` constructor parameters when we first wrote `Car`.
We don't really care about them now.
But we'll *have* to start caring because
We don't really care about them now.
But we'll *have* to start caring because
when the definion of `Engine` changes, our `Car` class must change.
That makes `Car` brittle.
What if we want to put a different brand of tires on our `Car`. Too bad.
What if we want to put a different brand of tires on our `Car`. Too bad.
We're locked into whatever brand the `Tires` class creates. That makes our `Car` inflexible.
Right now each new car gets its own engine. It can't share an engine with other cars.
While that makes sense for an automobile engine,
Right now each new car gets its own engine. It can't share an engine with other cars.
While that makes sense for an automobile engine,
we can think of other dependencies that should be shared ... like the onboard
wireless connection to the manufacturer's service center. Our `Car` lacks the flexibility
to share services that have been created previously for other consumers.
When we write tests for our `Car` we're at the mercy of its hidden dependencies.
Is it even possible to create a new `Engine` in a test environment?
Is it even possible to create a new `Engine` in a test environment?
What does `Engine`itself depend upon? What does that dependency depend on?
Will a new instance of `Engine` make an asynchronous call to the server?
Will a new instance of `Engine` make an asynchronous call to the server?
We certainly don't want that going on during our tests.
What if our `Car` should flash a warning signal when tire pressure is low.
How do we confirm that if actually does flash a warning
if we can't swap in low-pressure tires during the test?
We have no control over the car's hidden dependencies.
We have no control over the car's hidden dependencies.
When we can't control the dependencies, a class become difficult to test.
How can we make `Car` more robust, more flexible, and more testable?
How can we make `Car` more robust, more flexible, and more testable?
That's super easy. We probably already know what to do. We change our `Car` constructor to this:
<a name="ctor-injection"></a>
```
@ -80,50 +80,50 @@ include ../../../../_includes/_util-fns
this.tires = tires;
}
```
See what happened? We moved the definition of the dependencies to the constructor.
See what happened? We moved the definition of the dependencies to the constructor.
Our `Car` class no longer creates an engine or tires.
It just consumes them.
Now we create a car by passing the engine and tires to the constructor.
Now we create a car by passing the engine and tires to the constructor.
```
var car = new Car(new Engine(), new Tires());
```
How cool is that?
How cool is that?
The definition of the engine and tire dependencies are decoupled from the `Car` class itself.
We can pass in any kind of engine or tires we like, as long as they
conform to the general API requirements of an engine or tires.
If someone extends the `Engine` class, that is not `Car`'s problem.
.l-sub-section
:markdown
:marked
The consumer of `Car` has the problem. The consumer must update the car creation code to
something like:
```
var car = new Car(new Engine(theNewParameter), new Tires());
```
The critical point is this: `Car` itself did not have to change.
The critical point is this: `Car` itself did not have to change.
We'll take care of the consumer's problem soon enough.
:markdown
The `Car` class is much easier to test because we are in complete control
:marked
The `Car` class is much easier to test because we are in complete control
of its dependencies.
We can pass mocks to the constructor that do exactly what we want them to do
during each test:
```
var car = new Car(new MockEngine(), new MockLowPressureTires());
```
**We just learned what Dependency Injection is**.
**We just learned what Dependency Injection is**.
It's a coding pattern in which a class receives its dependencies from external
sources rather than creating them itself.
Cool! But what about that poor consumer?
Anyone who wants a `Car` must now
create all three parts: the `Car`, `Engine`, and `Tires`.
The `Car` class shed its problems at the consumer's expense.
We need something that takes care of assembling these parts for us.
We could write a giant class to do that:
```
class SuperFactory {
@ -136,14 +136,14 @@ include ../../../../_includes/_util-fns
But maintaining it will be hairy as the application grows.
This `SuperFactory` is going to become a huge spider web of
interdependent factory methods!
Wouldn't it be nice if we could simply list the things we want to build without
Wouldn't it be nice if we could simply list the things we want to build without
having to define which dependency gets injected into what?
This is where the Dependency Injection Framework comes into play.
Imagine the framework had something called an `Injector`.
Imagine the framework had something called an `Injector`.
We register some classes with this `Injector` and it figures out how to create them.
When we need a `Car`, we simply ask the `Injector` to get it for us and we're good to go.
```
function main() {
@ -153,103 +153,103 @@ include ../../../../_includes/_util-fns
}
```
Everyone wins. The `Car` knows nothing about creating an `Engine` or `Tires`.
The consumer knows nothing about creating a `Car`.
The consumer knows nothing about creating a `Car`.
We don't have a gigantic factory class to maintain.
Both `Car` and consumer simply ask for what they need and the `Injector` delivers.
This is what a **Dependency InjectionFramework** is all about.
This is what a **Dependency InjectionFramework** is all about.
Now that we know what Dependency Injection is and appreciate its benefits,
Now that we know what Dependency Injection is and appreciate its benefits,
let's see how it is implemented in Angular.
.l-main-section
:markdown
:marked
## Angular Dependency Injection
Angular ships with its own Dependency Injection framework. This framework can also be used
as a standalone module by other applications and frameworks.
as a standalone module by other applications and frameworks.
That sounds nice. What does it do for us when building components in Angular?
Let's see, one step at a time.
We'll begin with a simplified version of the `HeroesComponent`
Let's see, one step at a time.
We'll begin with a simplified version of the `HeroesComponent`
that we built in the [The Tour of Heroes](../tutorial/).
```
import {Component} from 'angular2/angular2';
import {Hero} from './hero';
import {HEROES} from './mock-heroes';
@Component({
selector: 'my-heroes'
templateUrl: 'app/heroes.component.html'
})
export class HeroesComponent {
heroes: Hero[] = HEROES;
}
```
It assigns a list of mocked heroes to its `heroes` property for binding within the template.
Pretty straight forward.
Those heroes are currently a fixed, in-memory collection, defined in another file and imported by the component.
Pretty straight forward.
Those heroes are currently a fixed, in-memory collection, defined in another file and imported by the component.
That works in the early stages of development but it's far from ideal.
As soon as we try to test this component or want to get our heroes data from a remote server,
we'll have to change this component's implementation of `heroes` and
As soon as we try to test this component or want to get our heroes data from a remote server,
we'll have to change this component's implementation of `heroes` and
fix every other use of the `HEROES` mock data.
Let's make a service that hides how we get Hero data.
.l-sub-section
:markdown
:marked
Write this service in its own file. See [this note](#forward-ref) to understand why.
:markdown
:marked
```
import {Hero} from './hero';
import {HEROES} from './mock-heroes';
class HeroService {
heroes: Hero[];
constructor() {
this.heroes = HEROES;
}
getHeroes() {
return this.heroes;
}
}
```
Our `HeroService` exposes a `getHeroes()` method that returns
the same mock data as before but none of its consumers need to know that.
A service is nothing more than a class in Angular 2.
Our `HeroService` exposes a `getHeroes()` method that returns
the same mock data as before but none of its consumers need to know that.
A service is nothing more than a class in Angular 2.
It remains nothing more than a class until we register it with
the Angular injector.
### Configuring the Injector
We don't have to create the injector.
<a name="bootstrap"></a>
Angular creates an application-wide injector for us during the bootstrap process.
```
bootstrap(HeroesComponent);
```
Let’s configure the injector at the same time that we bootstrap by adding
our `HeroService` to an array in the second argument.
```
Let’s configure the injector at the same time that we bootstrap by adding
our `HeroService` to an array in the second argument.
We'll explain that array when we talk about [providers](#providers) later in this chapter.
```
bootstrap(AppComponent, [HeroService]);
```
```
That’s it! The injector now knows about the `HeroService` which is available for injection across our entire application.
### Preparing the `HeroesComponent` for injection
The `HeroesComponent` should get its heroes from this service.
Per the dependency injection pattern, the component must "ask for" the service in its constructor [as we explained
earlier](#ctor-injection)".
```
constructor(heroService: HeroService) {
this.heroes = heroService.getHeroes();
@ -257,19 +257,19 @@ include ../../../../_includes/_util-fns
```
<a name="di-metadata"></a>
.l-sub-section
:markdown
:marked
Adding a parameter to the constructor isn't all that's happening here.
We are writing the app in TypeScript and have followed the parameter name with a type notation, `:HeroService`.
The class is also decorated with the `@Component` decorator (scroll up to confirm that fact).
When the TypeScript compiler evaluates this class, it sees the decorator and adds class metadata
into the generated JavaScript code. Within that metadata lurks the information that
associates the `heroService` parameter with the `HeroService` class.
associates the `heroService` parameter with the `HeroService` class.
That's how the Angular injector will know to inject an instance of the `HeroService` when it
creates a new `HeroesComponent`.
:markdown
:marked
### Creating the `HeroesComponent` with the injector (implicitly)
When we introduced the idea of an injector above, we showed how to create
a new `Car` with that injector.
@ -281,24 +281,24 @@ include ../../../../_includes/_util-fns
var hc = injector.get(HeroesComponent);
```
We *could* write code like that if we wanted to. We just don't have to.
Angular does that for us when it renders a `HeroesComponent`
Angular does that for us when it renders a `HeroesComponent`
whether we ask for it in an HTML template ...
```
<my-heroes></heroes>
```
... or navigate to a `HeroesComponent` view with the [router](./router.html).
### Singleton services
We might wonder what happens when we inject the `HeroService` into other components.
### Singleton services
We might wonder what happens when we inject the `HeroService` into other components.
Do we get the same instance every time?
Yes we do. Dependencies are singletons.
We’ll discuss that later in our chapter about
Yes we do. Dependencies are singletons.
We’ll discuss that later in our chapter about
[Hierarchical Injectors](./hierarchical-dependency-injection.html).
### Testing the component
We emphasized earlier that designing a class for dependency injection makes it easier to test.
Mission accomplished! We don't even need the Angular Dependency Injection system to test the `HeroesComponent`.
We simply create a bew `HeroesComponent` with a mock service and poke at it:
```
@ -307,28 +307,28 @@ include ../../../../_includes/_util-fns
expect(hc.heroes.length).toEqual(mockService.getHeroes().length);
})
```
### When the service needs a service
Our `HeroService` is very simple. It doesn't have any dependencies of its own.
### When the service needs a service
Our `HeroService` is very simple. It doesn't have any dependencies of its own.
What if it had a dependency? What if it reported its activities through a logging service?
We'd apply the same "constructor injection" pattern.
We'd apply the same "constructor injection" pattern.
Here's a rewrite of `HeroService` with a new constructor that takes a `logger` parameter.
```
import {Hero} from './hero';
import {HEROES} from './mock-heroes';
import {Logger} from './logger';
@Injectable()
class HeroService {
heroes: Hero[];
constructor(private logger: Logger) {
this.heroes = HEROES;
}
getHeroes() {
this.logger.log('Getting heroes ...')
return this.heroes;
@ -337,74 +337,74 @@ include ../../../../_includes/_util-fns
```
The constructor now asks for an injected instance of a `Logger` and stores it in a private property called `logger`.
We call that property within our `getHeroes()` method when anyone asks for heroes.
**The `@Injectable()` decoration catches our eye!**
.alert.is-critical
:markdown
**Always include the parentheses!** Always call `@Injectable()`. It's easy to forget the parentheses.
:marked
**Always include the parentheses!** Always call `@Injectable()`. It's easy to forget the parentheses.
Our application will fail mysteriously if we do. It bears repeating: **always include the parentheses.**
:markdown
We haven't seen `@Injectable()` before.
:marked
We haven't seen `@Injectable()` before.
As it happens, we could have added it to `HeroService`. We didn't bother because we didn't need it then.
We need it now ... now that our service has an injected dependency.
We need it because Angular requires constructor parameter metadata in order to inject a `Logger`.
We need it now ... now that our service has an injected dependency.
We need it because Angular requires constructor parameter metadata in order to inject a `Logger`.
As [we mentioned earlier](#di-metadata), TypeScript *only generates metadata for classes that have a decorator*. .
The `HeroesComponent` has an injected dependency too. Why don't we add `@Injectable()` to the `HeroesComponent`?
The `HeroesComponent` has an injected dependency too. Why don't we add `@Injectable()` to the `HeroesComponent`?
We *can* add it if we really want to. It isn't necessary because the `HeroesComponent` is already decorated with `@Component`.
TypeScript generates metadata for *any* class with a decorator and *any* decorator will do.
.l-main-section
:markdown
:marked
<a name="providers"></a>
## Injector Providers
Remember when we added the `HeroService` to an array in the [bootstrap](#bootstrap) process?
Remember when we added the `HeroService` to an array in the [bootstrap](#bootstrap) process?
```
bootstrap(AppComponent, [HeroService]);
```
That list of classes is actually a list of **providers**.
That list of classes is actually a list of **providers**.
"Providers" create the instances of the things that we ask the injector to inject.
There are many ways ways to "provide" a thing that has the necessary shape and behavior to serve as a `HeroService`.
A class is a natural provider - it's meant to be created. But it's not the only way
to produce something injectable. We could hand the injector an object to return. We could give it a factory function to call.
Any of these approaches might be a good choice under the right circumstances.
to produce something injectable. We could hand the injector an object to return. We could give it a factory function to call.
Any of these approaches might be a good choice under the right circumstances.
What matters is that the injector knows what to do when something asks for a `HeroService`.
### The Provider Class
When we wrote ...
```
[HeroService];
```
we used a short-hand expression for provider registration.
we used a short-hand expression for provider registration.
Angular expanded that short-hand into a call to the Angular `provide` method
```
[provide(HeroService, {useClass:HeroService})];
[provide(HeroService, {useClass:HeroService})];
```
and the `provide` method in turn creates a new instance of the Angular
and the `provide` method in turn creates a new instance of the Angular
[Provider class](http://localhost:3000/docs/ts/latest/api/core/Provider-class.html):
```
[new Provider(HeroService, {useClass:HeroService})]
```
This provider instance associates a `HeroService` *token*
This provider instance associates a `HeroService` *token*
with code that can create an *instance* of a `HeroService`.
The first parameter is the [token](#token) that serves as the key for both locating a dependency value
and registering the provider.
and registering the provider.
The second parameter is a provider definition object
which we think of as a "recipe" for creating the dependency value.
which we think of as a "recipe" for creating the dependency value.
There are many ways to create dependency values ... and many ways to write a recipe.
### Alternative Class Providers
Occasionally we'll ask a different class to provide the service.
We do that regularly when testing a component that we're creating with dependency injection.
In this example, we tell the injector
to return a `MockHeroService` when something asks for the `HeroService`.
@ -414,42 +414,42 @@ include ../../../../_includes/_util-fns
]);
```
### Value Providers
Sometimes it's easier to provide a ready-made object rather than ask the injector to create it from a class.
We do that a lot when we write tests. We might write the following test setup
for tests that explore how the `HeroComponent` behaves when the `HeroService`
for tests that explore how the `HeroComponent` behaves when the `HeroService`
returns an empty hero list.
```
beforeEachProviders(() => {
let emptyHeroService = { getHeroes: () => [] };
return [ provide(HeroService, {useValue: emptyHeroService}) ];
});
```
Notice we defined the recipe with `useValue` instead of `useClass`.
### Factory Providers
Sometimes the best choice for a provider is neither a class nor a value.
Suppose our HeroService has some cool new feature that we're only offering to "special" users.
The HeroService shouldn't know about users and
The HeroService shouldn't know about users and
we won't know if the current user is special until runtime anyway.
We decide to extend our `HeroService` constructor to accept a `useCoolFeature` flag
We decide to extend our `HeroService` constructor to accept a `useCoolFeature` flag
that toggles the feature on or off.
We rewrite the `HeroService` again as follows.
```
@Injectable()
class HeroService {
heroes: Hero[];
constructor(private logger: Logger, private useCoolFeature: boolean) {
this.heroes = HEROES;
}
getHeroes() {
let msg = this.useCoolFeature ? 'the cool new way' : 'the old way';
this.logger.log('Getting heroes ...' + msg)
@ -457,9 +457,9 @@ include ../../../../_includes/_util-fns
}
}
```
The feature flag is a simple boolean value. We'd like to inject the flag but it seems silly to write an entire class for a
The feature flag is a simple boolean value. We'd like to inject the flag but it seems silly to write an entire class for a
simple flag.
We can replace the `HeroService` provider with a factory function that creates a properly configured `HeroService` for the current user.
We'll' build up to that result, beginning with our definition of the factory function:
```
@ -468,59 +468,59 @@ include ../../../../_includes/_util-fns
}
```
.l-sub-section
:markdown
The factory takes two parameters: the logger service and a user service.
:marked
The factory takes two parameters: the logger service and a user service.
The logger we pass straight to the constructor as we did before.
We'll know to use the cool new feature if the `userService.user.isSpecial` flag is true,
We'll know to use the cool new feature if the `userService.user.isSpecial` flag is true,
a fact we can't know until runtime.
:markdown
We use dependency injection everywhere so of course the factory function depends on
two injected services: `Logger` and `UserService`.
:marked
We use dependency injection everywhere so of course the factory function depends on
two injected services: `Logger` and `UserService`.
We declare those requirements in our provider definition object:
```
let heroServiceDefinition = {
useFactory: heroServiceFactory,
useFactory: heroServiceFactory,
deps: [Logger, UserService]
};
```
.l-sub-section
:markdown
:marked
The `useFactory` field tells Angular that the provider is a factory function and that its implementation is the `heroServiceFactory`.
The `deps` property is an array of [provider tokens](#token).
The `deps` property is an array of [provider tokens](#token).
The `Logger` and `UserService` classes serve as tokens for their own class providers.
:markdown
Finally, we create the provider and adjust the bootstrapping to include that provider
:marked
Finally, we create the provider and adjust the bootstrapping to include that provider
among its provider registrations.
```
let heroServiceProvider = provide(HeroService, heroServiceDefinition);
bootstrap(AppComponent, [heroServiceProvider, Logger, UserService]);
```
### String tokens
Sometimes we have an object dependency rather than a class dependency.
Applications often define configuration objects with lots of small facts like the title of the application or the address of a web api endpoint.
These configuration objects aren't always instances of a class. They're just objects ... like this one:
```
let config = {
apiEndpoint: 'api.heroes.com',
title: 'The Hero Employment Agency'
};
};
```
We'd like to make this `config` object available for injection.
We'd like to make this `config` object available for injection.
We know we can register an object with a "Value Provider". But what do we use for the token?
<a id="token"></a>
Until now, we've always asked the class to play the token role
Until now, we've always asked the class to play the token role
whether we wrote a provider with a class, value, or factory recipe.
This time we don't have a class to serve as a token. There is no `Config` class.
Fortunately, the token can be a string, a class type, or an
[OpaqueToken](http://localhost:3000/docs/ts/latest/api/core/OpaqueToken-class.html).
Fortunately, the token can be a string, a class type, or an
[OpaqueToken](http://localhost:3000/docs/ts/latest/api/core/OpaqueToken-class.html).
Internally, the `Provider` turns the string and class parameter into an `OpaqueToken`;
the injector locates dependency values and providers by this token.
@ -532,7 +532,7 @@ include ../../../../_includes/_util-fns
]);
```
Let's apply what we've learned and update the `HeroesComponent` constructor so it can display the configured title.
Let's apply what we've learned and update the `HeroesComponent` constructor so it can display the configured title.
Right now the constructor signature is
```
constructor(heroService: HeroService)
@ -546,38 +546,38 @@ include ../../../../_includes/_util-fns
We'll need a little help from another Angular decorator called `@Inject`.
```
import {Inject} from 'angular2/angular2'
constructor(heroService: HeroService, @Inject('app.config') config)
```
.l-main-section
:markdown
:marked
# Next Steps
We learned the basics of Angular Dependency Injection in this chapter.
The Angular Dependency Injection is more capable than we've described.
The Angular Dependency Injection is more capable than we've described.
We can learn more about its advanced features, beginning with its support for
a hierarchy of nested injectors in the next
a hierarchy of nested injectors in the next
[Dependency Injection chapter](./hierarchical-dependency-injection.html)
.l-main-section
<a name="forward-ref"></a>
:markdown
:marked
### Appendix: Why we recommend one class per file
Developers expect one class per file. Multiple classes per file is confusing and is best avoided.
Developers expect one class per file. Multiple classes per file is confusing and is best avoided.
If we define every class in its own file, there is nothing in this note to worry about.
Move along!
If we scorn this advice
and we add our `HeroService` class to the `HeroesComponent` file anyway,
**define the `HeroesComponent` last!**
and we add our `HeroService` class to the `HeroesComponent` file anyway,
**define the `HeroesComponent` last!**
If we put it define component before the service,
we'll get a runtime null reference error.
To understand why, paste the following incorrect, ultra-simplified rendition of these two
classes into the [TypeScript playground](http://www.typescriptlang.org/Playground).
```
class HeroesComponent {
static $providers=[HeroService]
@ -588,18 +588,18 @@ include ../../../../_includes/_util-fns
alert(HeroesComponent.$providers)
```
.l-sub-section
:markdown
:marked
The `HeroService` is incorrectly defined below the `HeroComponent`.
The `$providers` static property represents the metadata about the injected `HeroService`
that TypeScript compiler would add to the component class.
The `alert` simulates the action of the Dependency Injector at runtime
The `alert` simulates the action of the Dependency Injector at runtime
when it attempts to create a `HeroesComponent`.
:markdown
Run it. The alert appears but displays nothing.
:marked
Run it. The alert appears but displays nothing.
This is the equivalent of the null reference error thrown at runtime.
We understand why when we review the generated JavaScript which looks like this:
```
var HeroesComponent = (function () {
@ -608,28 +608,28 @@ include ../../../../_includes/_util-fns
HeroesComponent.$providers = [HeroService];
return HeroesComponent;
})();
var HeroService = (function () {
function HeroService() {
}
return HeroService;
})();
alert(HeroesComponent.$providers);
```
Notice that the TypeScript compiler turns classes into function expressions
Notice that the TypeScript compiler turns classes into function expressions
assigned to variables. The value of the captured `HeroService` variable is undefined
when the `$providers` array is assigned. The `HeroService` variable gets its value too late
to be captured.
Reverse the order of class definition so that the `HeroService`
appears before the `HeroesComponent` that requires it.
Run again. This time the alert displays the `HeroService` function definition.
If we insist on defining the `HeroService` in the same file and insist on
defining the component first, Angular offers a way to make that work.
The `forwardRef()` method let's us reference a class
before it has been defined.
The `forwardRef()` method let's us reference a class
before it has been defined.
Learn more about this problem and the `forwardRef()`
in this [blog post](http://blog.thoughtram.io/angular/2015/09/03/forward-references-in-angular-2.html).

74
public/docs/ts/latest/guide/displaying-data.jade
View File

@ -2,7 +2,7 @@ include ../../../../_includes/_util-fns
<!-- http://plnkr.co/edit/x9JYbC -->
:markdown
:marked
## Displaying Component Properties
We typically display data in Angular by binding controls in an HTML template
@ -17,7 +17,7 @@ figure.image-display
img(src="/resources/images/devguide/displaying-data/final.png" alt="Final UI")
.l-main-section
:markdown
:marked
## Showing component properties with interpolation
The easiest way to display a component property
is to bind the property name through interpolation.
@ -32,7 +32,7 @@ figure.image-display
+makeExample('displaying-data/ts/src/app/app.1.ts')
:markdown
: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
@ -40,24 +40,24 @@ figure.image-display
+makeExample('displaying-data/ts/src/app/app.1.ts', 'template')
.l-sub-section
:markdown
: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.
:markdown
: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
when these properties change.
.l-sub-section
:markdown
:marked
More precisely, the re-display occurs after some kind of asynchronous event related to
the view such as a keystroke, a timer completion, or an asynch `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.
:markdown
:marked
Notice that we haven't called **new** to create an instance of the `AppComponent` class.
Angular is creating an instance for us. How?
@ -65,7 +65,7 @@ figure.image-display
Remember back in QuickStart that we added the `<my-app>` element to the body of our `index.html`
+makeExample('displaying-data/ts/src/index.html', 'my-app')
:markdown
:marked
When we bootstrap with the `AppComponent` class (see the bottom of `app.ts`), Angular looks for a `<my-app>`
in the `index.html`, finds it, instantiates an instance of `AppComponent`, and renders it
inside the `<my-app>` tag.
@ -90,40 +90,40 @@ figure.image-display
Some folks prefer to declare the properties and initialize them within a constructor like this:
+makeExample('displaying-data/ts/src/app/app-ctor.ts', 'app-ctor')
:markdown
:marked
That's fine too. The choice between them 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.
.l-main-section
:markdown
:marked
## 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.
+makeExample('displaying-data/ts/src/app/app.2.ts', 'mock-heroes')
:markdown
:marked
Now we use the Angular `NgFor` "repeater" Directive in the template to display
each item in the `heroes` list.
+makeExample('displaying-data/ts/src/app/app.2.ts', 'template')
:markdown
:marked
Our presentation is the familiar HTML unordered list with `<ul>` and `<li>` tags. Let's focus on the `<li>` tag.
+makeExample('displaying-data/ts/src/app/app.2.ts', 'li-repeater')
:markdown
:marked
We added a somewhat mysterious `*ng-for` 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".
.alert.is-important
:markdown
:marked
Don't forget the leading asterisk (\*) in front of `*ng-for`. It is an essential part of the syntax.
Learn more about this and `NgFor` in the [Template Syntax](./template-syntax.html#ng-for) chapter.
:markdown
: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`.
@ -133,11 +133,11 @@ figure.image-display
context for the interpolation in the double curly braces.
.l-sub-section
:markdown
:marked
We happened to give `NgFor` an array to display.
In fact, `NgFor` can repeat items for any [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)
object.
:markdown
:marked
## Register the NgFor Directive
Angular doesn't know that this template uses the `NgFor` directive.
@ -149,20 +149,20 @@ figure.image-display
Look for it in the following:
+makeExample('displaying-data/ts/src/app/app.2.ts', 'imports')
:markdown
:marked
Second, we register `NgFor` as a directive accessible to the template by updating the
`@Component` decorator with a `directives` array property whose only item is `NgFor`:
+makeExample('displaying-data/ts/src/app/app.2.ts', 'directives')
:markdown
:marked
Now the heroes will appear in the view as an unordered list.
figure.image-display
img(src="/resources/images/devguide/displaying-data/hero-names-list.png" alt="After ngfor")
.l-main-section
:markdown
:marked
## Creating a class for the data
We are defining our data directly inside our component.
@ -177,7 +177,7 @@ figure.image-display
Create a new file called `hero.ts` and add the following short snippet to it.
+makeExample('displaying-data/ts/src/app/hero.ts')
:markdown
: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
@ -186,30 +186,30 @@ figure.image-display
Consider the first parameter:
+makeExample('displaying-data/ts/src/app/hero.ts', 'id-parameter')
:markdown
:marked
That brief syntax simultaneously
* 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.
.l-main-section
:markdown
:marked
## Use the Hero class
Let's redefine the heroes property in our component to return an array of these Heroes
and also set the `myHero` property with the first of these mock heroes.
+makeExample('displaying-data/ts/src/app/app.3.ts', 'heroes')
:markdown
: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
+makeExample('displaying-data/ts/src/app/app.3.ts', 'template')
:markdown
:marked
Our display looks the same but we know how much better it is under the hood.
.l-main-section
:markdown
:marked
## Conditional display with NgIf
Sometimes the app should display a view or a portion of a view only under prescribed circumstances.
@ -220,38 +220,38 @@ figure.image-display
We can see it in action by adding the following paragraph at the bottom of the template:
+makeExample('displaying-data/ts/src/app/app.final.ts', 'message')
.alert.is-important
:markdown
:marked
Don't forget the leading asterisk (\*) in front of `*ng-if`. It is an essential part of the syntax.
Learn more about this and `NgIf` in the [Template Syntax](./template-syntax.html#ng-if) chapter.
:markdown
:marked
The [template expression](./template-syntax.html#template-expressions) inside the double quotes
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 the paragraph and there is no message.
.alert.is-helpful
:markdown
:marked
Angular isn't showing and hiding the message. It is adding and removing the paragraph element from the DOM.
That hardly matters here. It would matter a great deal from a performance perspective if
we were conditionally including or excluding a big chunk of HTML with many data bindings.
:markdown
:marked
As with the `NgFor`, we must add the `NgIf` directive to the component's metadata.
We should extend our `import` statement as before ...
+makeExample('displaying-data/ts/src/app/app.3.ts', 'import-ng-if')
:markdown
:marked
... and add it to the directives array:
+makeExample('displaying-data/ts/src/app/app.3.ts', 'directives')
:markdown
:marked
Try it out. We have four items in the array so the message should appear.
Delete one of the elements from the array, refresh the browser, and the message should no longer appear.
.l-main-section
:markdown
:marked
## Use the CORE_DIRECTIVES Constant
There are other core Angular directives, such as `NgClass` and `NgSwitch`,
@ -266,15 +266,15 @@ figure.image-display
We'll revise our `import` statement one last time.
+makeExample('displaying-data/ts/src/app/app.final.ts', 'imports')
:markdown
:marked
and update the `directives` metadata
+makeExample('displaying-data/ts/src/app/app.final.ts', 'directives')
:markdown
:marked
Pro tip: we register this constant in almost every template we write.
.l-main-section
:markdown
:marked
## Summary
Now we know how to
- use **interpolation** with the double curly braces to display a component property,
@ -291,7 +291,7 @@ figure.image-display
'app.ts, hero.ts')
.l-main-section
:markdown
: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.

458
public/docs/ts/latest/guide/forms.jade
View File

@ -1,205 +1,205 @@
include ../../../../_includes/_util-fns
<!-- http://plnkr.co/edit/wg154K -->
:markdown
:marked
We’ve all used a form to login, submit a help request, place an order, book a flight,
schedule a meeting and perform countless other data entry tasks.
schedule a meeting and perform countless other data entry tasks.
Forms are the mainstay of business applications.
Any seasoned web developer can slap together an HTML form with all the right tags.
It's more challenging to create a cohesive data entry experience that guides the
user efficiently and effectively through the workflow behind the form.
*That* takes design skills that are, to be frank, well out of scope for this chapter.
It also takes framework support for
It also takes framework support for
**two-way data binding, change tracking, validation, and error handling**
... which we shall cover in this chapter on Angular forms.
We will build a simple form from scratch, one step at a time. Along the way we'll learn
- how to build an Angular form with a component and template
- the `ng-model` two-way data binding syntax for reading and writing values to input controls
- the `ng-control` directive to track the change state and validity of form controls
- the special CSS classes that `ng-control` adds to form controls and how we can use them to provide strong visual feedback
- how to display validation errors to users and enable/disable form controls
- how to share information across controls with template local variables
- how to share information across controls with template local variables
.l-main-section
:markdown
:marked
## Template-Driven Forms
Many of us will build forms by writing templates in the Angular [template syntax](./template-syntax.html) with
Many of us will build forms by writing templates in the Angular [template syntax](./template-syntax.html) with
the form-specific Directives and techniques described in this chapter.
.l-sub-section
:markdown
:marked
That's not the only way to create a form but it's the way we'll cover in this chapter.
:markdown
We can build almost any form we need with an Angular template ... login forms, contact forms ... pretty much any business forms.
We can lay out the controls creatively, bind them to data, specify validation rules and display validation errors,
:marked
We can build almost any form we need with an Angular template ... login forms, contact forms ... pretty much any business forms.
We can lay out the controls creatively, bind them to data, specify validation rules and display validation errors,
conditionally enable or disable specific controls, trigger built-in visual feedback, and much more.
It will be pretty easy because Angular handles many of the repeative, boiler plate tasks we'd
otherwise wrestle with ourselves.
We'll discuss and learn to build the following template-driven form:
figure.image-display
img(src="/resources/images/devguide/forms/hf-1.png" alt="Clean Form")
:markdown
:marked
Here at the *Hero Employment Agency* we use this form to maintain personal information about the
heroes in our stable. Every hero needs a job. It's our company mission to match the right hero with the right crisis!
Two of the three fields on this form are required. Required fields have a green bar on the left to make them easy to spot.
If we delete the hero name, the form displays a validation error in an attention grabbing style:
figure.image-display
img(src="/resources/images/devguide/forms/hf-2.png" alt="Invalid, Name Required")
:markdown
:marked
Note that the submit button is disabled and the "required" bar to the left of the input control changed from green to red.
.l-sub-section
p We'll' customize the colors and location of the "required" bar with standard CSS.
:markdown
.l-sub-section
p We'll' customize the colors and location of the "required" bar with standard CSS.
:marked
We will build this form in the following sequence of small steps
1. Create the `Hero` model class
1. Create the component that controls the form
1. Create a template with the initial form layout
1. Add the **ng-model** directive to each form input control
1. Add the **ng-model** directive to each form input control
1. Add the **ng-control** directive to each form input control
1. Add custom CSS to provide visual feedback
1. Show and hide validation error messages
1. Handle form submission with **ng-submit**
1. Disable the form’s submit button until the form is valid
1. Handle form submission with **ng-submit**
1. Disable the form’s submit button until the form is valid
:markdown
:marked
## Setup
Create a new project folder (`angular2-forms`) and follow the steps in the [QuickStart](../quickstart.html).
## Create the Hero Model Class
As users enter form data, we capture their changes and update an instance of a model.
## Create the Hero Model Class
As users enter form data, we capture their changes and update an instance of a model.
We can't layout the form until we know what the model looks like.
A model can be as simple as a "property bag" that holds facts about a thing of application importance.
That describes well our `Hero` class with its three required fields (`id`, `name`, `power`)
and one optional field (`alterEgo`).
Create a new file called `hero.ts` and give it the following class definition:
Create a new file called `hero.ts` and give it the following class definition:
+makeExample('forms/ts/src/app/hero.ts')
:markdown
:marked
It's an anemic model with few requirements and no behavior. Perfect for our demo.
The TypeScript compiler generates a public field for each `public` constructor parameter and
The TypeScript compiler generates a public field for each `public` constructor parameter and
assigns the parameter’s value to that field automatically when we create new heroes like this:
```
let myHero = new Hero(42, 'SkyDog', 'Fetch any object at any distance', 'Leslie Rollover');
console.log('My hero is called ' + myHero.name); // "My hero is called SkyDog"
```
The `alterEgo` is optional and the constructor lets us omit it; note the (?) in `alterEgo?`.
```
The `alterEgo` is optional and the constructor lets us omit it; note the (?) in `alterEgo?`.
.l-main-section
:markdown
:marked
## Create a Form component
An Angular form has two parts: an HTML-based template and a code-based Component to handle data and user interactions.
We begin with the Component because it states, in brief, what the Hero editor can do.
An Angular form has two parts: an HTML-based template and a code-based Component to handle data and user interactions.
We begin with the Component because it states, in brief, what the Hero editor can do.
Create a new file called `hero-form.component.ts` and give it the following definition:
+makeExample('forms/ts/src/app/hero-form.component.ts', 'first')
:markdown
There’s nothing special about this component, nothing to distinguish it from any component we've written before,
:marked
There’s nothing special about this component, nothing to distinguish it from any component we've written before,
nothing form-specific about it ... except, perhaps, the tell-tale `FORM_DIRECTIVES` import.
Understanding this component requires only the Angular 2 concepts we’ve learned in previous chapters
1. We import a standard set of symbols from the Angular library.
1. We import a standard set of symbols from the Angular library.
We don't have a template yet but we usually import `CORE_DIRECTIVES` and it doesn't surprise us to
import something called `FORM_DIRECTIVES`, given that we'll be writing a form
1. The `@Component` selector value of "hero-form" means we can drop this form in a parent template with a `<hero-form>` tag.
1. The `templateUrl` property points to a separate file for template HTML called `hero-form.component.html`.
1. We defined dummy data for `model` and `powers` as befits a demo.
1. We defined dummy data for `model` and `powers` as befits a demo.
Down the road, we can inject a data service to get and save real data
or perhaps expose these properties as [inputs and outputs](./template-syntax.html#inputs-outputs) for binding to a
or perhaps expose these properties as [inputs and outputs](./template-syntax.html#inputs-outputs) for binding to a
parent component. None of this concerns us now and these future changes won't affect our form.
1. We threw in a `diagnostic` property at the end to return a JSON representation of our model.
It'll help us see what we're doing during our development; we've left ourselves a cleanup note to discard it later.
It'll help us see what we're doing during our development; we've left ourselves a cleanup note to discard it later.
We may wonder why we aren't writing the template inline in the component file as we have often done
elsewhere in the Developer Guide.
There is no “right” answer for all occasions. We kind of like inline templates when they are short.
There is no “right” answer for all occasions. We kind of like inline templates when they are short.
Most form templates won't be short. TypeScript and JavaScript files generally aren't the best place to
write (or read) large stretches of HTML and few editors are much help with files that have a mix of HTML and code.
We also like short files with a clear and obvious purpose like this one.
We made a good choice to put the HTML template elsewhere. Let's write it.
.l-main-section
:markdown
:marked
## Revise the *app.ts*
`app.ts` is the application's root component. It will host our new `HeroFormComponent`.
Replace the contents of the "QuickStart" version with the following:
+makeExample('forms/ts/src/app/app.ts')
:markdown
:marked
.l-sub-section
:markdown
:marked
There are only three changes:
1. We import the new `HeroFormComponent`.
1. The `template` is simply the new element tag identified by the component's `select` property.
1. The `directives` array tells Angular that our templated depends upon the `HeroFormComponent`
which is itself a Directive (as are all Components).
.l-main-section
:markdown
:marked
## Create an initial HTML Form Template
Create a new template file called `hero-form.component.html` and give it the following definition:
+makeExample('forms/ts/src/app/hero-form.component.html', 'start')
:markdown
:marked
That is plain old HTML 5. We're presenting two of the `Hero` fields, `name` and `alterEgo`, and
opening them up for user input in input boxes.
The "Name" `<input>` control has the HTML5 `required` attribute;
the "Alter Ego" `<input>` control does not because `alterEgo` is optional.
We've got a "Submit" button at the bottom with some classes on it.
**We are not using Angular yet**. There are no bindings. No extra directives. Just layout.
The `container`,`form-group`, `form-control`, and `btn` classes are CSS Bootstrap. Purely cosmetic.
The `container`,`form-group`, `form-control`, and `btn` classes are CSS Bootstrap. Purely cosmetic.
We're using Bootstrap to gussy up our form.
Hey, what's a form without a little style!
Hey, what's a form without a little style!
.l-sub-section
:markdown
:marked
Since we're using [CSS Boostrap](http://getbootstrap.com/css/).
now might be a good time to install it into our project.
We can do that with npm.
@ -207,275 +207,275 @@ figure.image-display
Open a terminal window and enter the command:
code-example(language="html" escape="html").
npm install bootstrap
:markdown
:marked
<br>Open the `index.html` and add the following line wherever we like to put our CSS
+makeExample('forms/ts/src/index.html', 'bootstrap')(format=".")
.callout.is-important
header Angular Forms Does Not Require A Style Library
:markdown
Angular makes no use of the `container`, `form-group`, `form-control`, and `btn` classes or
:marked
Angular makes no use of the `container`, `form-group`, `form-control`, and `btn` classes or
the styles of any external library. We are welcome to use the CSS library we choose
... or none at all.
.l-main-section
:markdown
:marked
## Add Powers with ***ng-for**
Our hero may choose one super power from a fixed list of Agency-approved powers.
We maintain that list internally (in `HeroFormComponent`).
We maintain that list internally (in `HeroFormComponent`).
We'll add a `select` to our
form and bind the options to the `powers` list using `NgFor`,
a technique we might have seen before in the ["Displaying Data"](./displaying-data.html) chapter.
Add the following HTML *immediately below* the "Alter Ego" group.
+makeExample('forms/ts/src/app/hero-form.component.html', 'powers')
:markdown
:marked
We are repeating the `<options>` tag for each power in the list of Powers.
The `#p` local template variable is a different power in each iteration;
we display its name using the interpolation syntax with the double-curly-braces.
.l-main-section
:markdown
:marked
## Two-way data binding with ***ng-model**
We might be disappointed if we ran the app right now.
figure.image-display
img(src="/resources/images/devguide/forms/hf-3.png" alt="Early form with no binding")
:markdown
We quickly realize that we are not binding to the `Hero` yet.
We know how to do that from earlier chapters.
:marked
We quickly realize that we are not binding to the `Hero` yet.
We know how to do that from earlier chapters.
We learned show data on screen with a Property Binding in "[Displaying Data](./displaying-data.html)".
We learned to listen for DOM events with an
Event Binding and how to extract values from the screen
in "[User Input](./user-input.html)".
Now we need to display, listen, and extract at the same time.
We could use those techniques again in our form.
Instead we'll introduce something new, the `NgModel` directive, that
Now we need to display, listen, and extract at the same time.
We could use those techniques again in our form.
Instead we'll introduce something new, the `NgModel` directive, that
makes binding our form to the model super-easy.
Find the `<input>` tag for the "Name" and update it like this
+makeExample('forms/ts/src/app/hero-form.component.html', 'ng-model-1')
.l-sub-section
:markdown
:marked
We appended a diagnostic interpolation after the input tag
so we can see what we're doing.
so we can see what we're doing.
We left ourselves a note to throw it way when we're done.
:markdown
Focus on the binding syntax: `[(ng-model)]="..."`.
:marked
Focus on the binding syntax: `[(ng-model)]="..."`.
If we ran the app right now and started typing in the "Name" input box,
adding and deleting characters, we'd see them appearing and disappearing
adding and deleting characters, we'd see them appearing and disappearing
from the interpolated text.
At some point it might look like this.
figure.image-display
img(src="/resources/images/devguide/forms/ng-model-in-action.png" alt="ng-model in action")
:markdown
:marked
The diagnostic is evidence that we really are flowing values from the input box to the model and
back again. **That's two-way data binding!**
Let's add similar `[(ng-model)]` bindings to "Alter Ego" and "Hero Power".
Let's add similar `[(ng-model)]` bindings to "Alter Ego" and "Hero Power".
We'll ditch the input box binding message
and add a new binding at the top to the component's `diagnostic` property.
Then we can confirm that we are in fact two-way data binding *to the entire Hero model*.
After revision the core of our form should have three `[(ng-model)]` bindings that
After revision the core of our form should have three `[(ng-model)]` bindings that
look much like this:
+makeExample('forms/ts/src/app/hero-form.component.html', 'ng-model-2')
:markdown
:marked
If we ran the app right now and made a bunch of changes at some point it might look like this.
figure.image-display
img(src="/resources/images/devguide/forms/ng-model-in-action-2.png" alt="ng-model in super action")
:markdown
:marked
We've changed every Hero model property and the diagnostic near the top of the form
confirms that our changes are reflected in the model.
** We're done with the diagnostic binding. Delete it now.**
.alert.is-helpful
:markdown
:marked
Although `NgModel` is officially a "Forms" directive we can use `[(ng-model)]` and two-way binding outside of forms too.
:markdown
:marked
## Inside [(ng-model)]
Do we *really want* to know? If we're just happy that it works, move on to the next topic in this chapter.
Otherwise, stick around for this note.
.l-sub-section
:markdown
:marked
The punctuation in the binding syntax, <span style="font-family:courier"><b>[()]</b></span>, is a good clue to what's going on.
We write a Property Binding to flow data from the model to a target property on screen.
We identify that target property by surrounding its name in brackets, <span style="font-family:courier"><b>[]</b></span>.
This is a one-way data binding **from the model to the view**.
We write an Event Binding to flow data from the target property on screen to the model.
We identify that target property by surrounding its name in parentheses, <span style="font-family:courier"><b>()</b></span>.
This is a one-way data binding in the opposite direction **from the view to the model**.
No wonder Angular chose to combine the punctuation as <span style="font-family:courier"><b>[()]</b></span>
No wonder Angular chose to combine the punctuation as <span style="font-family:courier"><b>[()]</b></span>
to signify a two-way data binding and a **flow of data in both directions**.
In fact, we can break the `NgModel` binding into its two separate modes
In fact, we can break the `NgModel` binding into its two separate modes
as we do in this re-write of the "Name" `<input>` binding:
+makeExample('forms/ts/src/app/hero-form.component.html', 'ng-model-3')
:markdown
:marked
<br>The Property Binding should feel familiar. The Event Binding might seem strange.
The name `ng-model-change` is not an event we recognize.
It is a real event property ... of the `NgModel` directive.
When Angular sees a binding target in the form <span style="font-family:courier">[(abc)]</span>,
The name `ng-model-change` is not an event we recognize.
It is a real event property ... of the `NgModel` directive.
When Angular sees a binding target in the form <span style="font-family:courier">[(abc)]</span>,
it expects the `abc` directive to have an `abc` input property and an `abc-change` output property.
The other oddity is the template expression, `model.name = $event`.
We're used to seeing an `$event` object coming from a DOM event.
The `ng-model-change` property doesn't produce a DOM event; it's an Angular `EventEmitter`
We're used to seeing an `$event` object coming from a DOM event.
The `ng-model-change` property doesn't produce a DOM event; it's an Angular `EventEmitter`
property that returns the input box value when it fires ... which is precisely what
we should assign to the model's `name' property.
Nice to know but is it practical? We'd always prefer the `[(ng-model)]`.
We might split the binding if we had to do something special in
the event handling such as debounce or throttle the key strokes.
Learn more about `NgModel` and other template syntax in the
Learn more about `NgModel` and other template syntax in the
[Template Syntax](./template-syntax.html) chapter.
.l-main-section
:markdown
:marked
## Track change-state and validity with **ng-control**
A form isn't just about data binding. We'd also like to know the state of the controls on our form.
The `NgControl` directive keeps track of control state for us.
.callout.is-helpful
header NgControl requires Form
:markdown
:marked
The `NgControl` is one of a family of `NgForm` directives that can only be applied to
a control within a `<form`> tag.
:markdown
:marked
Our application can ask an `NgControl` instance if
* the user touched the control (`ng-touched` | `ng-untouched`)
* the value changed (`ng-pristine` | `ng-dirty`)
* is the value is valid (`ng-valid` | `ng-invalid`)
`NgControl` doesn't just track state; it updates the control with special
Angular CSS classes from the set we listed above.
Angular CSS classes from the set we listed above.
We can leverage those class names to change the appearance of the
control and make messages appear or disappear.
We'll explore those effects soon. Right now
we should **add `ng-control`to all three of our form controls**,
starting with the "Name" input box
+makeExample('forms/ts/src/app/hero-form.component.html', 'ng-control-1')
:markdown
:marked
Be sure to assign a unique name to each `ng-control` directive.
.l-sub-section
:markdown
:marked
Angular registers controls under their `ng-control` names
with the `NgForm`.
We didn't add the `NgForm` directive explicitly but it's here
and we'll talk it [later in this chapter](#ng-form).
.l-main-section
:markdown
.l-main-section
:marked
## Add Custom CSS for Visual Feedback
`NgControl` doesn't just track state. It updates the control with three classes, one
each from the following pairs of Angular form CSS classes.
* control visited: (`ng-touched` | `ng-untouched`)
* value changed: (`ng-pristine` | `ng-dirty`)
* validity: (`ng-valid` | `ng-invalid`)
Let's add a temporary [local template variable](./template-syntax.html#local-vars) named **spy**
to the "Name" `<input>` tag and use the spy to display those classes with an interpolation binding.
+makeExample('forms/ts/src/app/hero-form.component.html', 'ng-control-2')
:markdown
:marked
If we ran the app, focused our attention on the "Name" input box, and followed the next four steps *precisely*
1. Look but don't touched
1. Click in the input box, then click outside the text input box
1. Add slashes to the end of the name
1. Erase the name
... we would see the following four sets of class names and their transitions:
... we would see the following four sets of class names and their transitions:
figure.image-display
img(src="/resources/images/devguide/forms/ng-control-class-changes.png" alt="Invalid Form")
:markdown
:marked
The (`ng-valid` | `ng-invalid`) pair are most interesting to us. We want to send a
strong visual signal when the data are invalid and we want to mark required fields.
We realize we can do both at the same time with a colored bar on the left of the input box:
We realize we can do both at the same time with a colored bar on the left of the input box:
figure.image-display
img(src="/resources/images/devguide/forms/validity-required-indicator.png" alt="Invalid Form")
:markdown
We achieve this effect by adding two styles to a new `styles.css` file
:marked
We achieve this effect by adding two styles to a new `styles.css` file
that we add to our project as a sibling to `index.html`.
+makeExample('forms/ts/src/styles.css')
:markdown
:marked
These styles select for the two Angular validity classes and the HTML 5 "required" attribute.
We update the `<head>` of the `index.html` to include this style sheet.
+makeExample('forms/ts/src/index.html', 'styles')(format=".")
:markdown
:marked
## Show and Hide Validation Error messages
We can do better.
The "Name" input box is required. Clearing it turns the bar red. That says *something* is wrong but we
don't know *what* is wrong or what to do about it.
don't know *what* is wrong or what to do about it.
We can leverage the `ng-invalid` class to reveal a helpful message.
Here's the way it should look when the user deletes the name:
figure.image-display
img(src="/resources/images/devguide/forms/name-required-error.png" alt="Name required")
:markdown
To achieve this effect we extend the `<input>` tag with
1. a [local template variable](./template-syntax.html#local-vars)
:marked
To achieve this effect we extend the `<input>` tag with
1. a [local template variable](./template-syntax.html#local-vars)
1. the "*is required*" message in a nearby `<div>` which we'll display only if the control is invalid.
Here's how we do it for the "name" input box:
+makeExample('forms/ts/src/app/hero-form.component.html', 'name-with-error-msg')
:markdown
We initialized the template local variable with the word "form" (`#name="form"`)
:marked
We initialized the template local variable with the word "form" (`#name="form"`)
Angular recognizes that syntax and sets the `name` varable
to the `Control` object identified by the `ng-control` directive which,
not coincidentally, we called "name".
We bind the `Control` object's `valid` property to the element's `hidden` property.
While the control is valid, the message is hidden;
We bind the `Control` object's `valid` property to the element's `hidden` property.
While the control is valid, the message is hidden;
if it becomes invalid, the message is revealed.
<a id="ng-form"></a>
<a id="ng-form"></a>
.l-sub-section
:markdown
Recall from the previous section that `ng-control` registered this input box with the
:marked
Recall from the previous section that `ng-control` registered this input box with the
`NgForm` directive as "name".
We didn't add the **[`NgForm`](../api/core/NgForm-class.html) directive** explicitly.
Angular added it surreptiously, wrapping it around the `<form>` element when we
Angular added it surreptiously, wrapping it around the `<form>` element when we
told the `HeroFormComponent` to use the `FORM_DIRECTIVES` like this
+makeExample('forms/ts/src/app/hero-form.component.ts', 'directives')
<br>
:markdown
The `NgForm` directive supplements the the `form` element with additional features.
:marked
The `NgForm` directive supplements the the `form` element with additional features.
It collects `Controls` (elements identified by an `ng-control` directive)
and monitors their properties including their validity.
It has its own `valid` property which is true only if every contained
@ -483,121 +483,121 @@ figure.image-display
In this example, we are pulling the "name" control out of its `controls` collection
and assigning it to the template local variable so that we can
access the control's properties ... such as the control's own `valid` property.
:markdown
access the control's properties ... such as the control's own `valid` property.
:marked
The "AlterEgo" is optional so we can leave that be.
"Power" selection is required.
We can add the same kind of error handling to the `<select>` if we want
We can add the same kind of error handling to the `<select>` if we want
but it's not imperative because the selection box already constrains the
power to valid value.
.l-main-section
:markdown
:marked
## Submit the form with **ng-submit**
The user should be able to submit this form after filling it in.
The "Submit" button at the bottom of the form
The "Submit" button at the bottom of the form
does nothing on its own but it will
trigger a form submit because of its type (`type="submit"`).
A "form submit" is meaningless at the moment.
A "form submit" is meaningless at the moment.
We'll update the `<form>` tag with another Angular directive, `NgSubmit`,
and bind it to our `HeroFormComponent.submit()` method with an EventBinding
+makeExample('forms/ts/src/app/hero-form.component.html', 'ng-submit')
:markdown
:marked
We slipped in something extra there at the end! We defined a
template local variable, **`#hf`**, and initialized it with the value, "form".
The variable `hf` is now a handle to the `NgForm` as we [discussed earlier](#ng-form)
with respect to `ng-control` although this time we have a reference to the form
rather than a control.
We'll bind the Form's over-all validity via
the `hf` variable to the button's `disabled` property
using an Event Binding. Here's the code:
+makeExample('forms/ts/src/app/hero-form.component.html', 'submit-button')
:markdown
If we run the application now, we find that the button is enabled.
+makeExample('forms/ts/src/app/hero-form.component.html', 'submit-button')
:marked
If we run the application now, we find that the button is enabled.
It doesn't do anything useful yet but it's alive.
Now if we delete the "Name", we violate the "required" rule which
Now if we delete the "Name", we violate the "required" rule which
is duely noted in our error message.
Check the "Submit" button. It should be disabled.
Not impressed? Think about it for a moment. What would we have to do to
wire the button's enable/disabled state to the form's validity without Angular's help?
For us, it was as simple as
1. Define a template local variable on the (enhanced) form element
2. Reference that variable in a button some 50 lines away.
.l-main-section
:markdown
:marked
## Toggle two form regions (Extra Credit)
Submitting the form isn't terribly dramatic at the moment.
.l-sub-section
:markdown
:marked
An unsurprising observation for a demo. To be honest,
jazzing it up won't teach us anything new about forms.
jazzing it up won't teach us anything new about forms.
But this is an opportunity to exercise some of our newly won
binding skills.
If we're not interested, we can skip to the chapter's conclusion
and not miss a thing.
:markdown
Let's do something more strikingly visual.
:marked
Let's do something more strikingly visual.
Let's hide the data entry area and display something else.
Start by wrapping the form in a `<div>` and binding
its `hidden` property to the `HeroFormComponent.submitted` property.
+makeExample('forms/ts/src/app/hero-form.component.html', 'edit-div')
:markdown
The main form is visible from the start because the
the `submitted` property is false until we submit the form
:marked
The main form is visible from the start because the
the `submitted` property is false until we submit the form
... as this fragment from the `HeroFormComponent` reminds us:
+makeExample('forms/ts/src/app/hero-form.component.ts', 'submitted')
:markdown
:marked
When we click the "Submit" button, the `submitted` flag becomes true and the form disappears
as planned.
Now we need to show something else while the form is in the submitted state.
Add the following block of HTML below the `<div>` wrapper we just wrote:
+makeExample('forms/ts/src/app/hero-form.component.html', 'submitted')
:markdown
:marked
There's our hero again, displayed read-only with interpolation bindings.
This slug of HTML only appears while the component is in the submitted state.
There's an "Edit" button whose click event we bound to an expression
that clears the `submitted` flag.
that clears the `submitted` flag.
Click it and this block disappears and the editable form reappears.
That's as much drama as we can muster for now.
.l-main-section
:markdown
:marked
## Conclusion
The Angular 2 form discussed in this chapter takes advantage of the following framework features to provide support for data modification, validation and more:
- An Angular HTML form template.
- A form component class with a `Component` decorator.
- The `ng-submit` directive for handling the form submission.
- Template local variables such as `#hf`, `#name`, `#alter-ego` and `#power`.
- The `ng-model` directive for two-way data binding.
- The `ng-model` directive for two-way data binding.
- The `ng-control` for validation and form element change tracking.
- The local variable’s `valid` property on input controls to check if a control is valid and show/hide error messages.
- Property Binding to disable the submit button when the form is invalid.
- Custom CSS classes that provide visual feedback to users about required invalid controls.
Here’s the final version of the application includes all of these framework features:
+makeTabs(
`forms/ts/src/app/hero-form.component.html,
forms/ts/src/app/hero-form.component.ts,
@ -605,14 +605,14 @@ figure.image-display
forms/ts/src/app/app.ts,
forms/ts/src/index.html,
forms/ts/src/styles.css`,
'final, final,,,,',
`hero-form.component.html,
hero-form.component.ts,
'final, final,,,,',
`hero-form.component.html,
hero-form.component.ts,
hero.ts,
app.ts,
index.html,
styles.css`)
:markdown
:marked
Our final project folder structure should look like this:
```
angular2-forms
@ -624,7 +624,7 @@ figure.image-display
│ | ├── hero-form.component.html
│ | └── hero-form.component.ts
│ ├── index.html
│ ├── styles.css
│ ├── styles.css
│ └── tsconfig.json
└── package.json
```

382
public/docs/ts/latest/guide/glossary.jade
View File

@ -1,4 +1,4 @@
:markdown
:marked
# Angular 2 Glossary
#sg-tables.showcase.shadow-1
header.showcase-header
@ -7,131 +7,131 @@
and the almost right word is the difference between
lightning and a lightning bug.</i> - Mark Twain
:markdown
:marked
Angular 2 has a vocabulary of its own.
Most Angular 2 terms are everyday English words
Most Angular 2 terms are everyday English words
with a specific meaning within the Angular system.
We have gathered here the most prominent terms
and a few less familiar ones that have unusual or
unexpected definitions.
.l-main-section
:markdown
:marked
## Annotation
.l-sub-section
:markdown
:marked
In practice a synonym for [Decoration](#decoration).
:markdown
:marked
## Attribute Directive
.l-sub-section
:markdown
:marked
A category of [Directive](#directive) that can listen to and modify the behavior of
other HTML elements, attributes, properties, and components. They are usually represented
as HTML attributes, hence the name.
The `ng-class` directive for adding and removing CSS class names is a good example of
an Attribute Directive.
.l-main-section
:markdown
:marked
## Binding
.l-sub-section
:markdown
:marked
Almost always refers to [Data Binding](#data-binding) and the act of
binding an HTML object property to a data object property.
May refer to a [Dependency Injection](#dependency-injection) binding
between a "token" or "key" and a dependency [provider](#provider).
This more rare usage should be clear in context.
:markdown
:marked
## Bootstrap
.l-sub-section
:markdown
:marked
We launch an Angular application by "bootstrapping" it with the `bootstrap` method.
The `bootstrap` method identifies an application's top level "root" [Component](#component)
and optionally registers service [providers](#provider) with the
[dependency injection system](#dependency-injection).
and optionally registers service [providers](#provider) with the
[dependency injection system](#dependency-injection).
One can bootstrap multiple apps in the same `index.html`, each with its own top level root.
.l-main-section
:markdown
:marked
## Component
.l-sub-section
:markdown
An Angular class responsible for exposing data
to a [View](#view) and handling most of the view’s display
and user-interaction logic.
:marked
An Angular class responsible for exposing data
to a [View](#view) and handling most of the view’s display
and user-interaction logic.
The Component is one of the most important building blocks in the Angular system.
It is, in fact, an Angular [Directive](directive) with a companion [Template](#template).
The developer applies the `@Component` [decorator](decorator) to
the component class, thereby attaching to the class the essential component metadata
the component class, thereby attaching to the class the essential component metadata
that Angular needs to create a component instance and render it with its template
as a view.
Those familiar with "MVC" and "MVVM" patterns will recognize
the Component in the role of "Controller" or "View Model".
.l-main-section
:markdown
:marked
## Data Binding
.l-sub-section
:markdown
:marked
Applications display data values to a user and respond to user
actions (clicks, touches, keystrokes).
We could push application data values into HTML, attach
event listeners, pull changed values from the screen, and
update application data values ... all by hand.
Or we could declare the relationship between an HTML widget
and an application data source ... and let a data binding
framework handle the details.
Data Binding is that second approach. Angular has a rich
data binding framework with a variety of data binding
operations and supporting declaration syntax.
The many forms of binding include:
* [Interpolation](./template-syntax.html#interpolation)
* [Property Binding](./template-syntax.html#property-binding)
* [Event Binding](./template-syntax.html#event-binding)
* [Attribute Binding](./template-syntax.html#attribute-binding)
* [Class Binding](./template-syntax.html#class-binding)
* [Style Binding](./template-syntax.html#style-binding)
* [Event Binding](./template-syntax.html#event-binding)
* [Attribute Binding](./template-syntax.html#attribute-binding)
* [Class Binding](./template-syntax.html#class-binding)
* [Style Binding](./template-syntax.html#style-binding)
* [Two-way data binding with ng-model](./template-syntax.html#ng-model)
Learn more about data binding in the
Learn more about data binding in the
[Template Syntax](./template-syntax.html#data-binding) chapter.
:markdown
:marked
<a id="decorator"></a> <a id="decoration"></a>
## Decorator | Decoration
.l-sub-section
:markdown
A Decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments.
:marked
A Decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments.
Decorators are a JavaScript language [feature](https://github.com/wycats/javascript-decorators), implemented in TypeScript and proposed for ES2016 (AKA ES7).
We apply a decorator by positioning it
immediately above or to the left of the thing it decorates.
Angular has its own set of decorators to help it interoperate with our application parts.
Here is an example of a `@Component` decorator that identifies a
class as an Angular [Component](#component) and an `@Input` decorator applied to a property
of that component.
of that component.
The elided object argument to the `@Component` decorator would contain the pertinent component metadata.
```
@Component({...})
export class AppComponent {
constructor(@Inject('SpecialFoo') public foo:Foo) {}
@Input()
@Input()
name:string;
}
```
@ -140,328 +140,328 @@
classes appearing below it in the file.
.alert.is-important
:markdown
Always include the parentheses `()` when applying a decorator.
:marked
Always include the parentheses `()` when applying a decorator.
A decorator is a **function** that must be called when applied.
:markdown
:marked
## Dependency Injection
.l-sub-section
:markdown
:marked
Dependency Injection is both a design pattern and a mechanism
for creating and delivering parts of an application to other
parts of an application that request them.
Angular developers prefer to build applications by defining many simple parts
that each do one thing well and then wire them together at runtime.
Angular developers prefer to build applications by defining many simple parts
that each do one thing well and then wire them together at runtime.
These parts often rely on other parts. An Angular [Component](#component)
part might rely on a service part to get data or perform a calculation. When a
part "A" relies on another part "B", we say that "A" depends on "B" and
that "B" is a dependency of "A".
We can ask a "Dependency Injection System" to create "A"
for us and handle all the dependencies.
We can ask a "Dependency Injection System" to create "A"
for us and handle all the dependencies.
If "A" needs "B" and "B" needs "C", the system resolves that chain of dependencies
and returns a fully prepared instance of "A".
Angular provides and relies upon its own sophisticated
[Dependency Injection](./dependency-injection.html) system
Angular provides and relies upon its own sophisticated
[Dependency Injection](./dependency-injection.html) system
to assemble and run applications by "injecting" application parts
into other application parts where and when needed.
At the core is an [`Injector`](#injector) that returns dependency values on request.
At the core is an [`Injector`](#injector) that returns dependency values on request.
The expression `injector.get(token)` returns the value associated with the given token.
A token is an Angular type (`OpaqueToken`). We rarely deal with tokens directly; most
methods accept a class name (`Foo`) or a string ("foo") and Angular converts it
to a token. When we write `injector.get(Foo)`, the injector returns
the value associated with the token for the `Foo` class, typically an instance of `Foo` itself.
Angular makes similar requests internally during many of its operations
as when it creates a [`Component`](#AppComponent) for display.
The `Injector` maintains an internal map of tokens to dependency values.
If the `Injector` can't find a value for a given token, it creates
a new value using a `Provider` for that token.
a new value using a `Provider` for that token.
A [Provider](#provider) is a recipe for
creating new instances of a dependency value associated with a particular token.
An injector can only create a value for a given token if it has
a `Provider` for that token in its internal provider registry.
a `Provider` for that token in its internal provider registry.
Registering providers is a critical preparatory step.
Angular registers some of its own providers with every injector.
We can register our own providers. Quite often the best time to register a `Provider`
We can register our own providers. Quite often the best time to register a `Provider`
is when we [bootstrap](#bootstrap) the application.
There are other opportunities to register as well.
Learn more in the [Dependency Injection](./dependency-injection.html) chapter.
:markdown
:marked
## Directive
.l-sub-section
:markdown
:marked
An Angular class responsible for creating, re-shaping, and interacting with HTML elements
in the browser DOM. Directives are Angular's most fundamental feature.
A Directive is almost always associated with an HTML element or attribute.
We often refer to such an element or attribute as the directive itself.
When Angular finds a directive in an HTML template,
it creates the matching directive class instance
We often refer to such an element or attribute as the directive itself.
When Angular finds a directive in an HTML template,
it creates the matching directive class instance
and gives that instance control over that portion of the browser DOM.
Developers can invent custom HTML markup (e.g., `<my-directive>`) to
associate with their custom directives. They add this custom markup to HTML templates
as if they were writing native HTML. In this way, directives become extensions of
HTML itself.
as if they were writing native HTML. In this way, directives become extensions of
HTML itself.
Directives fall into one of three categories:
1. [Components](#component) that combine application logic with an HTML template to
render application [views]. Components are usually represented as HTML elements.
They are the building blocks of an Angular application and the
developer can expect to write a lot of them.
render application [views]. Components are usually represented as HTML elements.
They are the building blocks of an Angular application and the
developer can expect to write a lot of them.
1. [Attribute Directives](attribute-directive) that can listen to and modify the behavior of
other HTML elements, attributes, properties, and components. They are usually represented
as HTML attributes, hence the name.
1. [Structural Directives](#structural-directive), a directive responsible for
1. [Structural Directives](#structural-directive), a directive responsible for
shaping or re-shaping HTML layout, typically by adding, removing, or manipulating
elements and their children.
.l-main-section
:markdown
:marked
## ECMAScript
.l-sub-section
:markdown
:marked
The [official JavaScript language specification](https://en.wikipedia.org/wiki/ECMAScript).
The latest approved version of JavaScript is
The latest approved version of JavaScript is
[ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/)
(AKA "ES2015" or "ES6") and many Angular 2 developers will write their applications
either in this version of the language or a dialect that strives to be
(AKA "ES2015" or "ES6") and many Angular 2 developers will write their applications
either in this version of the language or a dialect that strives to be
compatible with it such as [TypeScript](#typesScript).
Most modern browsers today only support the prior "ECMAScript 5" (AKA ES5) standard.
Applications written in ES2015 or one of its dialects must be "[transpiled](transpile)"
to ES5 JavaScript.
Angular 2 developers may choose to write in ES5 directly.
:markdown
:marked
## ECMAScript 2015
.l-sub-section
:markdown
The lastest released version of JavaScript,
:marked
The lastest released version of JavaScript,
[ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/)
(AKA "ES2015" or "ES6")
:markdown
(AKA "ES2015" or "ES6")
:marked
## ES2015
.l-sub-section
:markdown
Short hand for "[ECMAScript 2015](#ecmascript=2015)".
:markdown
:marked
Short hand for "[ECMAScript 2015](#ecmascript=2015)".
:marked
## ES6
.l-sub-section
:markdown
Short hand for "[ECMAScript 2015](#ecmascript=2015)".
:markdown
:marked
Short hand for "[ECMAScript 2015](#ecmascript=2015)".
:marked
## ES5
.l-sub-section
:markdown
:marked
Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers.
See [ECMAScript](#ecmascript).
.l-main-section
:markdown
:marked
## Injector
.l-sub-section
:markdown
An object in the Angular [dependency injection system](#dependency-injection)
:marked
An object in the Angular [dependency injection system](#dependency-injection)
that can find a named "dependency" in its cache or create such a thing
with a registered [provider](#provider).
:markdown
:marked
## Input
.l-sub-section
:markdown
A directive property that can be the ***target*** of a
:marked
A directive property that can be the ***target*** of a
[Property Binding](./template-syntax.html#property-binding).
Data values flow *into* this property from the data source identified
in the template expression to the right of the equal sign.
See the [Template Syntax](./template-syntax.html#inputs-outputs) chapter.
:markdown
:marked
## Interpolation
.l-sub-section
:markdown
A form of [Property Data Binding](#data-binding) in which a
:marked
A form of [Property Data Binding](#data-binding) in which a
[template expression](#template-expression) between double-curly braces
renders as text. That text may be concatenated with neighboring text
before it is assigned to an element property
or displayed between element tags as in this example.
code-example(language="html" escape="html").
<label>My current hero is {{hero.name}}</label>
:markdown
Learn more about interpolation in the
:marked
Learn more about interpolation in the
[Template Syntax](./template-syntax.html#interpolation) chapter.
.l-main-section
:markdown
:marked
## Output
.l-sub-section
:markdown
A directive property that can be the ***target*** of an
:marked
A directive property that can be the ***target*** of an
[Event Binding](./template-syntax.html#property-binding).
Events stream *out* of this property to the receiver identified
in the template expression to the right of the equal sign.
See the [Template Syntax](./template-syntax.html#inputs-outputs) chapter.
.l-main-section
:markdown
:marked
## Pipe
.l-sub-section
:markdown
:marked
An Angular pipe is a function that transforms input values to output values for
display in a [view](#view). We use the `@Pipe` [decorator](decorator)
to associate the pipe function with a name. We then can use that
name in our HTML to declaratively transform values on screen.
Here's an example that uses the built-in `currency` pipe to display
a numeric value in the local currency.
a numeric value in the local currency.
code-example(language="html" escape="html").
<label>Price: </label>{{product.price | currency}}
:markdown
:marked
Learn more in the chapter on [pipes](./pipes.html) .
:markdown
:marked
## Provider
.l-sub-section
:markdown
:marked
A Provider creates a new instance of a dependency for the Dependency Injection system.
It relates a lookup token to code - sometimes called a "recipe" - that can create a dependency value.
For example, `new Provider(Foo, {useClass: Foo})` creates a `Provider`
that relates the `Foo` token to a function that creates a new instance of the `Foo` class.
There are other ways to create tokens and recipes.
There are other ways to create tokens and recipes.
See [Dependency Injection](#dependency-injection) chapter to learn more.
.l-main-section
:markdown
:marked
## Router
.l-sub-section
:markdown
:marked
Most applications consist of many screens or [views](#view).
The user navigates among them by clicking links and buttons
and taking other similar actions that cause the application to
replace one view with another.
The [Angular router](./router.html) is a richly featured mechanism for configuring
and managing the entire navigation process including the creation and destruction
of views.
.l-main-section
:markdown
:marked
## Structural Directive
.l-sub-section
:markdown
A category of [Directive](#directive) that can
:marked
A category of [Directive](#directive) that can
shape or re-shape HTML layout, typically by adding, removing, or manipulating
elements and their children.
The `ng-if` "conditional element" directive and the `ng-for` "repeater" directive are
good examples in this category.
.l-main-section
:markdown
:marked
## Template
.l-sub-section
:markdown
:marked
A template is a chunk of HTML that Angular uses to render a [view](#view) with
the support and continuing guidance of an Angular [Directive](#directive),
most notably a [Component](#component).
We write templates in a special [Template Syntax](./template-syntax.html).
:markdown
:marked
## Template Expression
.l-sub-section
:markdown
:marked
An expression in a JavaScript-like syntax that Angular evaluates within
a [data binding](#data-binding). Learn how to write template expressions
in the [Template Syntax](./template-syntax.html#template-expressions) chapter.
:markdown
:marked
## Transpile
.l-sub-section
:markdown
:marked
The process of transforming code written in one form of JavaScript
(e.g., TypeScript) into another form of JavaScript (e.g., [ES5](#es5)).
:markdown
(e.g., TypeScript) into another form of JavaScript (e.g., [ES5](#es5)).
:marked
## TypeScript
.l-sub-section
:markdown
:marked
A version of JavaScript that supports most [ECMAScript 2015](#ecmascript=2015)
language features and many features that may arrive in future versions
of JavaScript such as [Decorators](#decorator).
TypeScript is also noteable for its optional typing system which gives
us compile-time type-checking and strong tooling support (e.g. "intellisense",
code completion, refactoring, and intelligent search). Many code editors
and IDEs support TypeScript either natively or with plugins.
TypeScript is the preferred language for Angular 2 development although
we are welcome to write in other JavaScript dialects such as [ES5](#es5).
Angular 2 itself is written in TypeScript.
Learn more about TypeScript on its [website](http://www.typescriptlang.org/).
.l-main-section
:markdown
:marked
## View
.l-sub-section
:markdown
:marked
A view is a portion of the screen that displays information and responds
to user actions such as clicks, mouse moves, and keystrokes.
Angular renders a view under the control of one or more [Directives](#directive),
especially [Component](#component) directives and their companion [Templates](#template).
The Component plays such a prominent role that we often
Angular renders a view under the control of one or more [Directives](#directive),
especially [Component](#component) directives and their companion [Templates](#template).
The Component plays such a prominent role that we often
find it convenient to refer to a component as a view.
Views often contain other views and any view might be loaded and unloaded
dynamically as the user navigates through the application, typically
under the control of a [router](#rounter).
.l-main-section
:markdown
:marked
## Zone
.l-sub-section
:markdown
:marked
Zones are a mechanism for encapsulating and intercepting
a JavaScript application's asynchronous activity.
The browser DOM and JavaScript have a limited number
The browser DOM and JavaScript have a limited number
of asynchronous activities, activities such as DOM events (e.g., clicks),
[promises](#promise), and
[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
[promises](#promise), and
[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
calls to remote servers.
Zones intercept all of these activities and give a "zone client" the opportunity
to take action before and after the asynch activity completes.
Angular runs our application in a zone where it can respond to
asynchronous events by checking for data changes and updating
the information it displays via [data binding](#data-binding).
Learn more about zones in this
Learn more about zones in this
[Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U).

212
public/docs/ts/latest/guide/hierarchical-dependency-injection.jade
View File

@ -1,115 +1,115 @@
include ../../../../_includes/_util-fns
:markdown
We learned the basics of Angular Dependency injection in an
:marked
We learned the basics of Angular Dependency injection in an
[earlier chapter](./dependency-injection.html).
In this chapter we learn that Angular has an
Hierarchical Dependency Injection system that supports trees of injectors.
In practice, there is a tree of injectors that parallel an application's component tree.
We can re-configure the injectors at any level of that component tree with
interesting and useful results.
.l-main-section
:markdown
.l-main-section
:marked
## The Injector Tree
In an [earlier chapter](./dependency-injection.html)
we learned how to configure a dependency injector in different ways and how to retrieve dependencies where we need them.
What if we told you there is no such thing as ***the*** injector?
we learned how to configure a dependency injector in different ways and how to retrieve dependencies where we need them.
What if we told you there is no such thing as ***the*** injector?
In fact, each application has multiple injectors!
We may have heard that an Angular application is a tree of components.
We may have heard that an Angular application is a tree of components.
It may surprise us to learn that there is a corresponding tree of injectors
and each component instance in that tree has its own injector!
.l-sub-section
:markdown
:marked
That isn't literally true. Angular is more efficient than that. What is true is that each component instance
has an injector and that components at different levels in the tree have different injectors.
It is helpful for our purposes to pretend that every component has its own injector.
:markdown
Consider a simple variation on the Tour of Heroes application consisting of three different components:
`HeroesApp`, `HeroesListComponent` and `HeroesCardComponent`.
The `HeroesApp` holds a single instance of `HeroesListComponent`.
:marked
Consider a simple variation on the Tour of Heroes application consisting of three different components:
`HeroesApp`, `HeroesListComponent` and `HeroesCardComponent`.
The `HeroesApp` holds a single instance of `HeroesListComponent`.
The new twist is that the `HeroesListComponent` may hold and manage multiple instances of the `HeroesCardComponent`.
The following diagram represents the state of the component tree when there are three instances of `HeroesCardComponent`
open simultaneously.
figure.image-display
img(src="/resources/images/devguide/dependency-injection/component-hierarchy.png" alt="injector tree")
:markdown
:marked
Each component instance gets its own injector and an injector at one level is a child injector of the injector above it in the tree.
When a component at the bottom requests a dependency, Angular tries to satisfy that dependency with a provider registered in that component's own injector.
If the component's injector lacks the provider, it passes the request up to its parent component's injector.
If that injector can't satisfy the request, it passes it along to *its* parent component's injector.
When a component at the bottom requests a dependency, Angular tries to satisfy that dependency with a provider registered in that component's own injector.
If the component's injector lacks the provider, it passes the request up to its parent component's injector.
If that injector can't satisfy the request, it passes it along to *its* parent component's injector.
The requests keep bubbling up until we find an injector that can handle the request or run out of component ancestors.
If we run out of ancestors, Angular throws an error.
.l-sub-section
:markdown
There's a third possibililty. An intermediate component can declare that it is the "host" component.
:marked
There's a third possibililty. An intermediate component can declare that it is the "host" component.
The hunt for providers will climb no higher than the injector for this host component.
We'll reserve discussion of this option for another day.
:markdown
:marked
Such a proliferation of injectors makes little sense until we consider the possiblity that injectors at different levels can be
configured with different providers. We don't *have* to re-configure providers at every level. But we *can*.
If we don't re-configure, the tree of injectors appears to be flat. All requests bubble up to the root injector that we
configured with the `bootstrap` method.
The ability to configure one or more providers at different levels opens up interesting and useful possibilities.
Let’s return to our Car example.
Suppose configured the root injector (marked as A) with providers for `Car`, `Engine` and `Tires`.
The ability to configure one or more providers at different levels opens up interesting and useful possibilities.
Let’s return to our Car example.
Suppose configured the root injector (marked as A) with providers for `Car`, `Engine` and `Tires`.
We create a child component (B) that defines its own providers for `Car` and `Engine`
This child is the parent of another component (C) that defines its own provider for `Car`.
This child is the parent of another component (C) that defines its own provider for `Car`.
Behind the scenes each component sets up its own injector with one or more providers defined for that component itself.
When we resolve an instance of `Car` at the deepest component (C),
it's injector produces an instance of `Car` resolved by injector (C) with an `Engine` resolved by injector (B) and
it's injector produces an instance of `Car` resolved by injector (C) with an `Engine` resolved by injector (B) and
`Tires` resolved by the root injector (A).
figure.image-display
img(src="/resources/images/devguide/dependency-injection/injector-tree.png" alt="injector tree")
.l-main-section
:markdown
.l-main-section
:marked
## Component Injectors
In the previous section, we talked about injectors and how they are organized like a tree. Lookups follow the injector tree upwards until they found the requested thing to inject. But when do we actually want to provide bindings on the root injector and when do we want to provide them on a child injector?
Consider you are building a component to show a list of super heroes that displays each super hero in a card with it’s name and superpower. There should also be an edit button that opens up an editor to change the name and superpower of our hero.
One important aspect of the editing functionality is that we want to allow multiple heroes to be in edit mode at the same time and that one can always either commit or cancel the proposed changes.
Let’s take a look at the `HeroesListComponent` which is the root component for this example.
Consider you are building a component to show a list of super heroes that displays each super hero in a card with it’s name and superpower. There should also be an edit button that opens up an editor to change the name and superpower of our hero.
One important aspect of the editing functionality is that we want to allow multiple heroes to be in edit mode at the same time and that one can always either commit or cancel the proposed changes.
Let’s take a look at the `HeroesListComponent` which is the root component for this example.
```
import {Component, bootstrap, CORE_DIRECTIVES} from 'angular2/angular2';
import {HeroService} from './hero.service';
import {HeroCardComponent} from './hero-card.component';
import {HeroEditorComponent} from './hero-editor.component';
import {Hero} from './hero';
@Component({
selector: 'heroes-list-component',
template: `
<div>
<ul>
<li *ng-for="#editItem of heroes">
<hero-card-component
<hero-card-component
[hidden]="editItem.editing"
[hero]="editItem.item">
</hero-card-component>
<button
[hidden]="editItem.editing"
<button
[hidden]="editItem.editing"
(click)="editItem.editing = true">
edit
</button>
@ -130,43 +130,43 @@ figure.image-display
this.heroes = HeroService.getHeroes()
.map(item => new EditItem(item));
}
onSaved (editItem: EditItem<Hero>, updatedHero: Hero) {
editItem.item = updatedHero;
editItem.editing = false;
}
onCanceled (editItem: EditItem<Hero>) {
editItem.editing = false;
}
}
class EditItem<T> {
item: T;
editing: boolean
constructor (public item T) {}
}
bootstrap(HeroesListComponent, [HeroService]);
```
Notice that it imports the `HeroService` that we’ve used before so we can skip its declaration. The only difference is that we’ve used a more formal approach for our `Hero`model and defined it upfront as such.
```
export class Hero {
name: string;
power: string;
}
```
Our `HeroesListComponent` defines a template that creates a list of `HeroCardComponents` and `HeroEditorComponents`, each bound to an instance of hero that is returned from the `HeroService`. Ok, that’s not entirely true. It actually binds to an `EditItem<Hero>` which is a simple generic datatype that can wrap any type and indicate if the item being wrapped is currently being edited or not.
But how is `HeroCardComponent` implemented? Let’s take a look.
```
import {Component, bootstrap, CORE_DIRECTIVES} from 'angular2/angular2';
import {Hero} from './hero';
@Component({
selector: 'hero-card.component',
properties: ['hero'],
@ -181,16 +181,16 @@ figure.image-display
hero: Hero;
}
```
The `HeroCardComponent` is basically a component that defines a template to render a hero. Nothing more.
Let’s get to the interesting part and take a look at the `HeroEditComponent`
The `HeroCardComponent` is basically a component that defines a template to render a hero. Nothing more.
Let’s get to the interesting part and take a look at the `HeroEditComponent`
```
import {Component, FORM_DIRECTIVES, EventEmitter, bootstrap, CORE_DIRECTIVES} from 'angular2/angular2';
import {RestoreService} from './restore.service';
import {Hero} from './hero';
@Component({
selector: 'hero-editor-component',
events: ['canceled', 'saved'],
@ -210,98 +210,98 @@ figure.image-display
export class HeroEditorComponent {
canceled = new EventEmitter();
saved = new EventEmitter();
constructor(private restoreService: RestoreService<Hero>) {}
set hero (hero: Hero) {
this.restoreService.setItem(hero);
}
get hero () {
return this.restoreService.getItem();
}
onSaved () {
this.saved.next(this.restoreService.getItem());
}
onCanceled () {
this.hero = this.restoreService.restoreItem();
this.canceled.next(this.hero);
}
}
```
Now here it’s getting interesting. The `HeroEditComponent`defines a template with an input to change the name of the hero and a `cancel` and a `save` button. Remember that we said we want to have the flexibility to cancel our editing and restore the old value? This means we need to maintain two copies of our `Hero` that we want to edit. Thinking ahead this is a perfect use case to abstract it into it’s own generic service since we have probably more cases like this in our app.
And this is where the `RestoreService` enters the stage.
```
export class RestoreService<T> {
originalItem: T;
currentItem: T;
setItem (item: T) {
this.originalItem = item;
this.currentItem = this.clone(item);
}
getItem () :T {
return this.currentItem;
}
restoreItem () :T {
this.currentItem = this.originalItem;
return this.getItem();
}
clone (item: T) :T {
// super poor clone implementation
return JSON.parse(JSON.stringify(item));
}
}
```
All this tiny service does is define an API to set a value of any type which can be altered, retrieved or set back to it’s initial value. That’s exactly what we need to implement the desired functionality.
Our `HeroEditComponent` uses this services under the hood for it’s `hero` property. It intercepts the `get` and `set` method to delegate the actual work to our `RestoreService` which in turn makes sure that we won’t work on the original item but on a copy instead.
At this point we may be scratching our heads asking what this has to do with component injectors? If we look closely at our `HeroEditComponent` we’ll notice this piece of code
```
…
providers: [RestoreService]
…
```
This creates a binding for the `RestoreService` in the injector of the `HeroEditComponent`. But couldn’t we simply alter our bootstrap call to this?
```
bootstrap(HeroesListComponent, [HeroService, RestoreService]);
```
Technically we could, but our component wouldn’t quite behave the way it is supposed to. Remember that each injector treats the services that it provides as singletons. However, in order to be able to have multiple instances of `HeroEditComponent` edit multiple heroes at the same time we need to have multiple instances of the `RestoreService`. More specifically each instance of `HeroEditComponent` needs to be bound to it’s own instance of the `RestoreService`.
By configuring a binding for the `RestoreService` on the `HeroEditComponent`, we get exactly one instance of the `RestoreService`per `HeroEditComponent`.
Does that mean that services aren’t singletons anymore in Angular 2? Yes and no.
While there’s only one instance per binding per injector there may be multiple instances of the same type across
the entire application due to the fact that we can create multiple bindings for the same type on different components.
If we had only defined a binding for `RestoreService` on the root component,
By configuring a binding for the `RestoreService` on the `HeroEditComponent`, we get exactly one instance of the `RestoreService`per `HeroEditComponent`.
Does that mean that services aren’t singletons anymore in Angular 2? Yes and no.
While there’s only one instance per binding per injector there may be multiple instances of the same type across
the entire application due to the fact that we can create multiple bindings for the same type on different components.
If we had only defined a binding for `RestoreService` on the root component,
we would have exactly one instance of the across the entire applicatoin. That’s clearly not what we want in this scenario.
We don’t want to share an instance. We want each component to have its own instance of the `RestoreService`.
<!--
<!--
## Advanced Dependency Injection in Angular 2
Restrict Dependency Lookups
[TODO] (@Host) This has been postponed for now until we come up with a decent use case
.l-main-section
:markdown
:marked
## Dependency Visibility
[TODO] (bindings vs viewBindings) This has been postponed for now until come up with a decent use case
-->

170
public/docs/ts/latest/guide/pipes.jade
View File

@ -1,110 +1,110 @@
include ../../../../_includes/_util-fns
:markdown
:marked
Every application starts out with what seems like a simple task: get data, transform them, and show them to users.
Getting data could be as simple as creating a local variable or as complex as streaming data over a Websocket.
Once data arrive, we could push their raw `toString` values directly to screen.
That rarely makes for a good user experience.
Almost everyone prefers a simple birthday date
(<span style="font-family:courier">April 15, 1988</span>) to the original raw string format
( <span style="font-family:courier">Fri Apr 15 1988 00:00:00 GMT-0700 (Pacific Daylight Time)</span> ).
Getting data could be as simple as creating a local variable or as complex as streaming data over a Websocket.
Once data arrive, we could push their raw `toString` values directly to screen.
That rarely makes for a good user experience.
Almost everyone prefers a simple birthday date
(<span style="font-family:courier">April 15, 1988</span>) to the original raw string format
( <span style="font-family:courier">Fri Apr 15 1988 00:00:00 GMT-0700 (Pacific Daylight Time)</span> ).
Clearly some values benefit from a bit of massage. We soon discover that we
desire many of the same transformations repeatedly, both within and across many applications.
We almost think of them as styles.
We almost think of them as styles.
In fact, we'd like to apply them in our HTML templates as we do styles.
Welcome, Angular pipes, the simple display-value transformations that we can declare in our HTML!
Welcome, Angular pipes, the simple display-value transformations that we can declare in our HTML!
.l-main-section
:markdown
:marked
## Using Pipes
A pipe takes in data as input and transforms it to a desired output.
We'll illustrate by transforming a component's birthday property into
a human-friendly date.
A pipe takes in data as input and transforms it to a desired output.
We'll illustrate by transforming a component's birthday property into
a human-friendly date.
Here's a complete mini-app with a `DatePipe`:
<!--
All date samples are in my plunker
http://plnkr.co/edit/RDlOma?p=preview
-->
+makeExample('pipes/ts/src/app/app.ts', 'hero-birthday')
:markdown
Focus on the component's template to see how we applied the built-in `DatePipe`
while binding the `birthday` property.
:marked
Focus on the component's template to see how we applied the built-in `DatePipe`
while binding the `birthday` property.
+makeExample('pipes/ts/src/app/app.html', 'hero-birthday-template')(format=".")
:markdown
:marked
Angular [template syntax](./template-syntax.html#pipe) includes a pipe operator ( | ) which we're
using to flow the birthday value on the left through to the `Date` pipe function on the right.
All pipes work this way.
.l-main-section
:markdown
:marked
## Built-in pipes
Angular comes with a stock set of pipes such as
Angular comes with a stock set of pipes such as
`DatePipe`, `UpperCasePipe`, `LowerCasePipe`, `CurrencyPipe`, and `PercentPipe`.
They are all immediately available for use in any template.
.l-sub-section
:markdown
Learn more about these and many other built-in pipes in the the [API Reference](../api/);
filter for entries that include the word "pipe".
:marked
Learn more about these and many other built-in pipes in the the [API Reference](../api/);
filter for entries that include the word "pipe".
.l-main-section
:markdown
:marked
## Parameterizing a Pipe
A pipe may accept any number of optional parameters to fine-tune its output.
We add parameters to a pipe by following the pipe name with a colon ( : ) and then the parameter value
(e.g., `currency:'EUR'`). If our pipe accepts multiple parameters, we separate the values with colons (e.g. `slice:1:5`)
We'll modify our birthday example to give the date pipe a format parameter.
The formatted date should display as **<span style="font-family:courier">04/15/88</span>**.
+makeExample('pipes/ts/src/app/app.html', 'format-birthday')(format=".")
:markdown
:marked
The parameter value can be any valid
[template expression](./template-expression.html#template-expressions)
[template expression](./template-expression.html#template-expressions)
such as a string literal or a component property.
Let's revise our example to bind the pipe's format parameter
to the component's `format` property.
+makeExample('pipes/ts/src/app/hero-birthday.2.ts', 'hero-birthday2')
+makeExample('pipes/ts/src/app/hero-birthday.2.ts', 'hero-birthday2')
:markdown
:marked
We also added a button to the template and bound its click event to the component's `toggleFormat` method.
That method toggles the component's `format` property between a short form
('shortDate') and a longer form ('fullDate').
As we click the button, the displayed date alternates between
"**<span style="font-family:courier">04/15/1988</span>**" and
"**<span style="font-family:courier">Friday, April 15, 1988</span>**".
figure.image-display
img(src='/resources/images/devguide/pipes/date-format-toggle-anim.gif' alt="Date Format Toggle")
:markdown
:marked
.l-sub-section
:markdown
:marked
Learn more about the `DatePipes` format options in the [API Docs](../api/core/DatePipe-class.html).
:markdown
:marked
## Chaining pipes
We can chain pipes together in potentially useful combinations.
We can chain pipes together in potentially useful combinations.
In the following example, we chain the birthday to the `DatePipe` and on to the `UpperCasePipe`
so we can display the birthday in uppercase. The following birthday displays as
so we can display the birthday in uppercase. The following birthday displays as
**<span style="font-family:courier">APR 15, 1988</span>**
+makeExample('pipes/ts/src/app/app.html', 'chained-birthday')
:markdown
:marked
If we pass a parameter to a filter, we have to add parentheses
to help the template compiler with the evaluation order.
The following example displays
**<span style="font-family:courier">FRIDAY, APRIL 15, 1988</span>**
**<span style="font-family:courier">FRIDAY, APRIL 15, 1988</span>**
+makeExample('pipes/ts/src/app/app.html', 'chained-parameter-birthday')
@ -112,14 +112,14 @@ figure.image-display
p Future improvements in the template compiler may eliminate the need for parentheses.
.l-main-section
:markdown
:marked
## Custom Pipes
We can write our own custom pipes.
Let's make a custom pipe named `ExponentialStrengthPipe`
that can boost a hero's powers.
Create a new file, `exponential-strength-pipe.ts`, and enter the following:
<!--
The exponential pipe samples are in my plunker
@ -127,16 +127,16 @@ figure.image-display
-->
+makeExample('pipes/ts/src/app/exponential-strength-pipe.ts')
:markdown
:marked
This pipe definition reveals several few key points
* We import the `Pipe` decorator from the Angular library (while getting the usual symbols)
* A pipe is a class
* We decorate the class with the `@Pipe` decorator function.
* We decorate the class with the `@Pipe` decorator function.
* The `@Pipe` decorator takes an object with a name property whose value is the
pipe name that we'll use within a template expression. It must be a valid JavaScript identier.
Our pipe's name is `exponenentialStrength`.
* The pipe class implements a `transform` method
* `transform` takes a value and an optional array of strings.
Our pipe's name is `exponenentialStrength`.
* The pipe class implements a `transform` method
* `transform` takes a value and an optional array of strings.
The value can be of any type but the arguments array must be an array of strings.
* There will be one item in the array for each parameter passed to the pipe
* `transform` returns a modified value that Angular converts to a string.
@ -146,24 +146,24 @@ figure.image-display
figure.image-display
img(src='/resources/images/devguide/pipes/power-booster.png' alt="Power Booster")
:markdown
:marked
Two things to note:
1. We use the pipe in the template expression exactly as we described in the pipe's comments.
1. We use the pipe in the template expression exactly as we described in the pipe's comments.
We pass the value to transform from the left and give our pipe an exponent parameter of `10`.
1. We must list our pipe in the @Component decorator's `pipes` array.
.callout.is-critical
header Remember the pipes array!
:markdown
Angular reports an error if we neglect to list our custom pipe.
:marked
Angular reports an error if we neglect to list our custom pipe.
We didn't list the `DatePipe` in our previous example because all
Angular built-in pipes are pre-registered.
Angular built-in pipes are pre-registered.
Custom pipes must be registered manually.
:markdown
:marked
If we are inclined to try this in a live-coding tool (such a [plunker](http://plnkr.co/)),
we can probe its behavior by changing the value and the optional exponent in the template.
## Power Boost Calculator (extra-credit)
It's not much fun updating the template to test our custom pipe.
We could upgrade the example to a "Power Boost Calculator" that combines
@ -173,56 +173,56 @@ figure.image-display
figure.image-display
img(src='/resources/images/devguide/pipes/power-boost-calculator.png' alt="Power Boost Calculator")
:markdown
:marked
.l-main-section
:markdown
:marked
## Stateful Pipes
There are two categories of pipes, stateless and stateful.
Stateless pipes are pure functions that flow input data
There are two categories of pipes, stateless and stateful.
Stateless pipes are pure functions that flow input data
through without remembering anything or causing detectable side-effects.
Most pipes are stateless. The `DatePipe` in our first example is a stateless pipe. So is our custom `ExponentialStrengthPipe`.
Stateful pipes are conceptually similar to classes in object-oriented programming. They can manage the data they transform. A pipe that creates an HTTP request, stores the response and displays the output, is a stateful pipe.
Pipes that retrieve or request data should be used cautiously, since working with network data tends to introduce error conditions that are better handled in JavaScript than in a template.
Stateful pipes are conceptually similar to classes in object-oriented programming. They can manage the data they transform. A pipe that creates an HTTP request, stores the response and displays the output, is a stateful pipe.
Pipes that retrieve or request data should be used cautiously, since working with network data tends to introduce error conditions that are better handled in JavaScript than in a template.
We can mitigate this risk by creating a custom pipe for a particular backend and bake-in the essential error-handling.
## The stateful `AsyncPipe`
The Angular Async pipe is a remarkable example of a stateful pipe.
The Async pipe can receive a Promise or Observable as input
and subscribe to the input automatically, eventually returning the emitted value(s).
The Angular Async pipe is a remarkable example of a stateful pipe.
The Async pipe can receive a Promise or Observable as input
and subscribe to the input automatically, eventually returning the emitted value(s).
It is stateful because the pipe maintains a subscription to the input and its returned values depend on that subscription.
In the next example, we bind a simple promise to a view with the async pipe.
+makeExample('pipes/ts/src/app/app.ts', 'async-message')
:markdown
:marked
The Async pipe saves boilerplate in the component code.
The component doesn't have to subscribe to the async data source,
it doesn't extract the resolved values and expose them for binding,
and (in the case of Obsevable stream sources like `EventEmitter`)
the component doesn't have to unsubscribe when it is destroyed
(a potent source of memory leaks).
### Implementing a Stateful Pipe
Pipes are stateless by default.
We must declare a pipe to be stateful
Pipes are stateless by default.
We must declare a pipe to be stateful
by setting the `pure` property of the `@Pipe` decorator to `false`.
This setting tells Angular’s change detection system to
This setting tells Angular’s change detection system to
check the output of this pipe each cycle, whether its input has changed or not.
Here's how we'll decorate our new stateful `FetchJsonPipe` that
Here's how we'll decorate our new stateful `FetchJsonPipe` that
makes an HTTP `fetch` request and (eventually) displays the data in the server's response:
+makeExample('pipes/ts/src/app/fetch-json-pipe.ts', 'pipe-metadata')
:markdown
Immediately below we have the finished pipe. Its input value is an url to an endpoint that returns a JSON file.
:marked
Immediately below we have the finished pipe. Its input value is an url to an endpoint that returns a JSON file.
The pipe makes a one-time async request to the server and eventually receives the JSON response.
+makeExample('pipes/ts/src/app/fetch-json-pipe.ts')
:markdown
:marked
Next we use this pipe in two template bindings where we
1. display hero names in an `ng-for` repeater
1. chain the fetched results to the built-in `JsonPipe` that renders
@ -234,13 +234,13 @@ figure.image-display
img(src='/resources/images/devguide/pipes/hero-list.png' alt="Hero List")
.l-main-section
:markdown
:marked
## Next Steps
Pipes are a great way to encapsulate and share common display-value
transformations. We use them like styles, dropping them
into our templates expressions to enrich the appeal and usability
of our views.
Explore Angular's inventory of built-in pipes in the [API Reference](../api/).
Explore Angular's inventory of built-in pipes in the [API Reference](../api/).
Try writing a custom pipe and perhaps contributing it to the community.

6
public/docs/ts/latest/guide/router.jade
View File

@ -1,9 +1,9 @@
include ../../../../_includes/_util-fns
:markdown
:marked
# App Navigation with the Router
It's coming soon!
.l-main-section
:markdown
:marked
## What's not to love?

894
public/docs/ts/latest/guide/template-syntax.jade
View File

File diff suppressed because it is too large Load Diff

137
public/docs/ts/latest/guide/user-input.jade
View File

@ -1,27 +1,27 @@
include ../../../../_includes/_util-fns
:markdown
:marked
When the user clicks a link, pushes a button, or types on the keyboard
we want to know about it. These user actions all raise DOM events.
In this chapter we learn to bind to those events using the Angular Event Binding syntax.
:markdown
:marked
## Binding to User Input Events
We can listen to [any DOM event](https://developer.mozilla.org/en-US/docs/Web/Events)
We can listen to [any DOM event](https://developer.mozilla.org/en-US/docs/Web/Events)
with an [Angular Event Binding](./template-syntax.html#event-binding).
The syntax is simple. We assign a template expression to the DOM event name, surrounded in parentheses.
The syntax is simple. We assign a template expression to the DOM event name, surrounded in parentheses.
A click Event Binding makes for a quick illustration.
+makeExample('user-input/ts/src/app/app.html', 'click-me-button')(format=".")
:markdown
:marked
The `(click)` to the left of the equal sign identifies the button's click event as the **target of the binding**.
The text within quotes on the right is the "**template expression**" in which we
respond to the click event by calling the component's `onClickMe` method. A [template expression](./template-syntax.html#template-expressions) is a subset
of JavaScript with a few added tricks.
When writing a binding we must be aware of a template expression's **execution context**.
When writing a binding we must be aware of a template expression's **execution context**.
The identifers appearing within an expression belong to a specific context object.
That object is usually the Angular component that controls the template ... which it definitely is
in this case because that snippet of HTML belongs to the following component:
@ -29,112 +29,112 @@ include ../../../../_includes/_util-fns
These sample can be found in http://plnkr.co/edit/mr63T5
-->
+makeExample('user-input/ts/src/app/app.ts', 'click-me-component')
:markdown
The `onClickMe` in the template refers to the `onClickMe` method of the component.
:marked
The `onClickMe` in the template refers to the `onClickMe` method of the component.
When the user clicks the button, Angular calls the component's `onClickMe` method.
.l-main-section
:markdown
:marked
## Get user input from the $event object
We can bind to all kinds of events. Let's bind to the "keyup" event of an input box and replay
what the user types back onto the screen.
This time we'll both listen to an event and grab the user's input.
+makeExample('user-input/ts/src/app/app.ts', 'key-up-component')
:markdown
:marked
Angular makes an event object available in the **`$event`** variable. The user data we want is in that variable somewhere.
The shape of the `$event` object is determined by whatever raises the event.
The `keyup` event comes from the DOM so `$event` must be a [standard DOM event object](https://developer.mozilla.org/en-US/docs/Web/API/Event).
The `$event.target` gives us the
[`HTMLInputElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) which
has a `value` property and that's where we find our user input data.
With had this in mind when we passed `$event` to our `onKey()` component method. That method extracts the user's input and
concatenates it to the previous user data that we're accumulating in the component's' `values` property.
concatenates it to the previous user data that we're accumulating in the component's' `values` property.
We then use [interpolation](./template-syntax.html#interpolation)
to display the `values` property back on screen.
Enter the letters "abc", backspace to remove them, and we should see:
code-example().
a | ab | abc | ab | a | |
figure.image-display
img(src='/resources/images/devguide/user-input/keyup1-anim.gif' alt="key up 1")
:markdown
:marked
.l-main-section
:markdown
:marked
## Get user input from a local template variable
There's another way to get the user data without the `$event` variable.
Angular has syntax feature called [**local template variables**](./template-syntax.html#local-vars).
These variables grant us direct access to an element.
We declare a local template variable by preceding an identifier with a hash/pound character (#).
Let's demonstrate with a clever keystroke loopback in a single line of template HTML.
Let's demonstrate with a clever keystroke loopback in a single line of template HTML.
We don't actually need a dedicated component to do this but we'll make one anyway.
+makeExample('user-input/ts/src/app/app.ts', 'loop-back-component')
:markdown
:marked
We've declared a template local variable named `box` on the `<input>` element.
The `box` variable is a reference to the `<input>` element itself which means we can
grab the input element's `value` and display it
The `box` variable is a reference to the `<input>` element itself which means we can
grab the input element's `value` and display it
with interpolation between `<p>` tags. The display updates as we type. *Voila!*
**This won't work at all unless we bind to an event**. Angular only updates the bindings
(and therefore the screen)
if we do something in response to asynchronous events such as keystrokes.
In this silly example we aren't really interested in the event at all.
In this silly example we aren't really interested in the event at all.
But an Event Binding requires a template expression to evaluate when the event fires.
Many things qualify as expressions, none simpler than a one-character literal
like the number zero. That's all it takes to keep Angular happy. We said it would be clever!
That local template variable is intriguing. It's clearly easer to get to the textbox with that
variable than to go through the `$event` object. Maybe we can re-write our previous
"key-up" example using the variable to acquire the user's' input. Let's give it a try.
+makeExample('user-input/ts/src/app/app.ts', 'key-up2-component')
:markdown
That sure seems easier.
:marked
That sure seems easier.
An especially nice aspect of this approach is that our component code gets clean data values from the view.
It no longer requires knowledge of the `$event` and its structure.
<a id="key-event"></a>
.l-main-section
:markdown
:marked
## Key event filtering (with `key.enter`)
Perhaps we don't care about every keystroke.
Perhaps we don't care about every keystroke.
We're only interested in the input box value when the user hits the "Enter" key. We'd like to ignore all other keys.
When we bind to the `(keyup)` event, our event handling expression hears *every key stroke*.
When we bind to the `(keyup)` event, our event handling expression hears *every key stroke*.
We could filter the keys first, examining every `$event.keyCode`, and update the `values` property only if the key is "Enter".
Angular can filter the key events for us. Angular has a special syntax for keyboard events.
We can listen for just the "Enter" key by binding to Angular's `keyup.enter` pseudo-event.
Only then do we update the component's `values` property ...
inside the event expression rather than in the component ...
Angular can filter the key events for us. Angular has a special syntax for keyboard events.
We can listen for just the "Enter" key by binding to Angular's `keyup.enter` pseudo-event.
Only then do we update the component's `values` property ...
inside the event expression rather than in the component ...
because we can ... even if it is a dubious practice.
+makeExample('user-input/ts/src/app/app.ts', 'key-up3-component')
figure.image-display
img(src='/resources/images/devguide/user-input/keyup3-anim.gif' alt="key up 3")
.l-main-section
:markdown
:marked
## On blur
Our previous example won't transfer the current state of the input box if the user mouses away and clicks
elsewhere on the page. We only update the component's `values` property when the user presses "Enter"
inside the input box.
Let's fix that by listening to the input box's blur event as well.
+makeExample('user-input/ts/src/app/app.ts', 'key-up4-component')
.l-main-section
:markdown
:marked
## Put it all together
We learned how to [display data](./displaying-data.html) in the previous chapter.
We've acquired a small arsenal of event binding techniques in this chapter.
We've acquired a small arsenal of event binding techniques in this chapter.
Let's put it all together in a micro-app
that can display a list of heroes and add new heroes to that list
by typing in the input box and hitting "Enter", clicking "Add", or clicking
@ -142,24 +142,24 @@ figure.image-display
figure.image-display
img(src='/resources/images/devguide/user-input/little-tour-anim.gif' alt="Little Tour of Heroes")
:markdown
Below is the entire "Little Tour of Heroes" micro-app in a single component.
:marked
Below is the entire "Little Tour of Heroes" micro-app in a single component.
We'll call out the highlights after we bask briefly in its minimalist glory.
<!--
This example in http://plnkr.co/edit/JWeIqq
-->
+makeExample('user-input/ts/src/app/app.ts', 'little-tour-of-heroes-app')
:markdown
+makeExample('user-input/ts/src/app/app.ts', 'little-tour-of-heroes-app')
:marked
We've seen almost everything here before. A few things are new or bear repeating.
### **Beware of camelCase variable names**
We enter new hero names in the `<input>` element so we chose `newHero` to be the name of the local template variable.
Unfortunately, we can't use that name when we declare the variable with (#).
Unfortunately, we can't use that name when we declare the variable with (#).
The browser forces all attribute and element names to lowercase, turning what would be `#newHero`
into `#newhero` (all lowercase). We don't want a `newhero` variable name in our template expressions.
The Angular workaround is to spell the declaration in "snake case". Angular translates "#new-hero"
into `#newhero` (all lowercase). We don't want a `newhero` variable name in our template expressions.
The Angular workaround is to spell the declaration in "snake case". Angular translates "#new-hero"
to `newHero` for template expressions ... which is exactly what we want.
### **newHero refers to the `<input>` element**
@ -171,27 +171,26 @@ figure.image-display
Ready access to the `<input>` element also makes it easy for the `addHero` method
to clear the textbox after processing the new hero.
### **The *ng-for repeater**
The `ng-for` directive repeats the template as many times as there are heroes in the `heroes` list.
We must remember to list `NgFor` among the directives used by the component's template
We must remember to list `NgFor` among the directives used by the component's template
by importing the `CORE_DIRECTIVES` constant and adding it to the
@Component decorator's `directives` array.
We learned about `NgFor` in the "[Displaying Data](./displaying-data.html)" chapter.
We learned about `NgFor` in the "[Displaying Data](./displaying-data.html)" chapter.
.l-main-section
:markdown
:marked
## Next Steps
We've mastered the basic primitives for responding to user input and gestures.
As powerful as these primitives are, they are a bit clumsy for handling
large amounts of user input. We're operating down at the low level of events when
we should be writing two-way bindings between data entry fields and model properties.
Angular has a two-way binding called `NgModel` and we learn about it
in the `Forms` chapter.

114
public/docs/ts/latest/quickstart.jade
View File

@ -1,22 +1,22 @@
include ../../../_includes/_util-fns
:markdown
:marked
Let's start from zero and build a super simple Angular 2 application in TypeScript.
.callout.is-helpful
header Don't want TypeScript?
:markdown
:marked
Although we're getting started in TypeScript, you can also write Angular 2 apps
in JavaScript and Dart by selecting either of those languages from the combo-box in the banner.
.l-main-section
:markdown
:marked
## The shortest, quickest ...
Let's put something on the screen in Angular 2 as quickly as we can.
.l-sub-section
:markdown
:marked
While we are about to describe steps to take on your development machine,
you could take these same steps in an interactive, online coding environment
such as [plunker](http://plnkr.co/ "Plunker"). You won't have to
@ -25,21 +25,21 @@ include ../../../_includes/_util-fns
If you like what you see - and we think you will - you can repeat this
exercise on your own machine later.
:markdown
:marked
**Create a new folder** to hold our application project, perhaps like this:
```
mkdir angular2-quickstart
cd angular2-quickstart
```
.l-main-section
:markdown
:marked
## Our first Angular component
**Add a new file** called **`app.ts`** and paste the following lines:
+makeExample('quickstart/ts/src/app/app.ts', null, 'app.ts')
:markdown
:marked
We've just defined an Angular 2 **component**,
one of the most important Angular 2 features.
Components are our primary means of creating application views
@ -52,12 +52,12 @@ include ../../../_includes/_util-fns
Above the class we see the `@Component` decoration.
.l-sub-section
:markdown
:marked
The `@` symbol before the method name identifies `Component` as a decoration.
A "decoration" is a TypeScript language feature
for creating metadata about the class. Angular finds this metadata
in the transpiled JavaScript and responds appropriately.
:markdown
:marked
`@Component` tells Angular that this class *is an Angular component*.
The configuration object passed to the `@Component` method has two
field, a `selector` and a `template`.
@ -81,7 +81,7 @@ include ../../../_includes/_util-fns
We `import` exactly what we need, as we need it, from named file and library resources.
.l-main-section
:markdown
:marked
## Add `index.html`
**Create** an `index.html` file.
@ -90,7 +90,7 @@ include ../../../_includes/_util-fns
+makeExample('quickstart/ts/src/index.1.html', null, 'index.html')
:markdown
:marked
We see three noteworthy sections of HTML:
1. We load JavaScript libraries from the web.
@ -110,17 +110,17 @@ include ../../../_includes/_util-fns
adorning our `AppComponent` class.
.l-main-section
:markdown
:marked
## Run it!
We need a static file server to serve our application to the browser.
.l-sub-section
:markdown
:marked
Don't have a static file server handy? Let's install one of our favorites
called [live-server](https://www.npmjs.com/package/live-server "Live-server")
with the **npm package manager**.
with the **npm package manager**.
Don't have npm?
[Get it now](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm")
because we're going to use it now and repeatedly throughout this documentation.
@ -130,27 +130,27 @@ include ../../../_includes/_util-fns
pre.prettyprint.lang-bash
code npm install -g live-server
:markdown
:marked
Open a terminal window and enter
pre.prettyprint.lang-bash
code live-server
:markdown
:marked
In a few moments, a browser tab should open and display
figure.image-display
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")
:markdown
:marked
Congratulations! We are in business.
.alert.is-helpful
:markdown
If you see `Loading...` displayed instead, see the
:marked
If you see `Loading...` displayed instead, see the
[Browser ES6 support appendix](#es6support).
.l-main-section
:markdown
:marked
## What's wrong with this?
We were up and running in a hurry and we could explore Angular
@ -177,7 +177,7 @@ include ../../../_includes/_util-fns
We have tools and procedures for that.
.l-main-section
:markdown
:marked
## Upping our game
Let's take a few more steps to put our development on a better foundation. We will
@ -189,7 +189,7 @@ include ../../../_includes/_util-fns
Shut down the `live-server` running in the terminal window (Ctrl-C) and proceed as follows.
.l-main-section
:markdown
:marked
## Revise the application project structure
At the moment we're dumping everything into the "angular2-quickstart" **root folder**.
@ -205,13 +205,13 @@ include ../../../_includes/_util-fns
pre.prettyprint.lang-bash
code mkdir src/app
:markdown
:marked
In Windows:
pre.prettyprint.lang-bash
code mkdir src\app
:markdown
:marked
**Move `index.html`** into the **`src`** folder.
**Move `app.ts`** into the **`src/app`** folder.
@ -226,7 +226,7 @@ include ../../../_includes/_util-fns
```
.l-main-section
:markdown
:marked
## Install npm packages locally
We'll replace the web-based scripts in our `index.html` with
@ -261,17 +261,17 @@ include ../../../_includes/_util-fns
+makeJson('quickstart/ts/package.json', { paths: 'name, version, dependencies, devDependencies'})
:markdown
:marked
There is also a `scripts` section. **Find and replace** it with the following:
+makeJson('quickstart/ts/package.json', { paths: 'scripts'})
:markdown
:marked
We've just extended our project world with script commands
that we'll be running very soon.
.l-main-section
:markdown
:marked
## Update `index.html`
**Replace** the library scripts section with references to
@ -279,13 +279,13 @@ include ../../../_includes/_util-fns
+makeExample('quickstart/ts/src/index.html', 'libraries')
:markdown
:marked
**Update** the `System` configuration script as follows.
+makeExample('quickstart/ts/src/index.html', 'systemjs')
.l-sub-section
:markdown
:marked
We won't be transpiling TypeScript in the browser anymore.
We'll do that on our machine and ship the generated JavaScript
files to the server.
@ -297,19 +297,19 @@ include ../../../_includes/_util-fns
pre.prettyprint.lang-bash
code import {Foo} from './app/foo'
:markdown
:marked
`system.js`will know to look for a file named `foo.js` in the `src/app` folder.
That's exactly what we're doing in the last line. We're
importing our main application file `app` (the generated `app.js` to be precise)
from the `src/app/` folder (we moved it there, remember?)
:markdown
:marked
Here's the final version
+makeExample('quickstart/ts/src/index.html', null, 'index.html')
.l-main-section
:markdown
:marked
## Prepare for TypeScript Compilation
### Add the TypeScript configuration file
@ -322,12 +322,12 @@ include ../../../_includes/_util-fns
+makeJson('quickstart/ts/src/tsconfig.json', null, 'tsconfig.json')
.alert.is-helpful
:markdown
:marked
See the [TypeScript configuration appendix](#tsconfig) to learn more about
this file and these settings.
.l-main-section
:markdown
:marked
## Final structure
Our final project folder structure should look like this:
```
@ -342,7 +342,7 @@ include ../../../_includes/_util-fns
```
.l-main-section
:markdown
:marked
## Compile the TypeScript to JavaScript
We no longer transpile TypeScript to JavaScript in the browser.
@ -353,7 +353,7 @@ include ../../../_includes/_util-fns
pre.prettyprint.lang-bash
code npm run tsc
:markdown
:marked
When it's done we should find the generated *app.js* file in the *src* folder and also an *app.map.js* file that
helps debuggers navigate between the JavaScript and the TypeScript source.
@ -366,7 +366,7 @@ include ../../../_includes/_util-fns
You can stop it anytime with `Ctrl-C`.
.l-main-section
:markdown
:marked
## Run the app!
Now we are ready to see our app in action.
@ -378,14 +378,14 @@ include ../../../_includes/_util-fns
pre.prettyprint.lang-bash
code npm start
:markdown
:marked
**live-server** loads the browser for us, serves the HTML and JavaScript files,
and displays our application message once more:
figure.image-display
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")
:markdown
:marked
### Make some changes
**`live-server`** detects changes to our files and refreshes the browser page for us automatically.
@ -397,7 +397,7 @@ include ../../../_includes/_util-fns
Keep `live-server` running in this terminal window. You can stop it anytime with `Ctrl-C`.
.l-main-section
:markdown
:marked
## What have we done?
Our first application doesn't do much. It's basically "Hello, World" for Angular 2.
@ -428,7 +428,7 @@ include ../../../_includes/_util-fns
<!-- Move this to the Style Guide when we have one -->
.l-main-section
:markdown
:marked
<a id="tsconfig"></a>
### Appendix: TypeScript configuration
We added a TypeScript configuration file (`tsconfig.js`) to our project to
@ -463,26 +463,26 @@ include ../../../_includes/_util-fns
```
"suppressImplicitAnyIndexErrors":true
```
.l-main-section
:markdown
:marked
<a id="es6support"></a>
### Appendix: Browser ES6 support
Angular 2 requires ES6 support, such as can be found in most modern
Angular 2 requires ES6 support, such as can be found in most modern
browsers. For older browsers (including IE 11) you can use a shim to get
the needed functionality.
the needed functionality.
After creating `package.json` (halfway through the quickguide), run this
command to add a shim to the project:
code-example(language="sh" format=".").
npm install es6-shim --save
:markdown
:marked
Now you can load the shim in your `index.html` before the other scripts:
code-example(language="html" format=".").
&lt;script src=&quot;../node_modules/es6-shim/es6-shim.js&quot;&gt;&lt;/script&gt;

6
public/docs/ts/latest/testing/application-under-test.jade
View File

@ -1,6 +1,6 @@
include ../../../../_includes/_util-fns
:markdown
:marked
We’ll need an Angular application to test, one as simple as possible while having all the angular features we want to test.
<!-- TODO We have such an app that you can download [here](./#). -->It’s a one-screen variation on the “Tour of Heroes” that should be familiar to you as a reader of this Developers Guide.
@ -11,7 +11,7 @@ figure.image-display
img(src='/resources/images/devguide/application-under-test/bongos-heroes.png'
style="width:400px;" alt="Bongo's Heroes")
:markdown
:marked
At the top is a master list of heroes; at the bottom the detail for the current hero. Click a hero in the list to change the current hero. Change the name in the textbox and that name updates everywhere. The *Update* button modifies the `Hero.name` in an arbitrary way and that change also propagates everywhere on screen. The *Delete* button deletes the hero from the list and a new hero becomes current. *Refresh* clears both the list and detail, then restores the original list of heroes.
<!-- TODO You can see a short video of the app in action [here](./#) -->
@ -33,6 +33,6 @@ figure.image-display
We’ll examine the implementation details as we evolve our tests.
.l-main-section
:markdown
:marked
## What’s Next?
Now that we’re familiar with how the test app works, we’re ready to poke at it with our first application tests written in Jasmine.

62
public/docs/ts/latest/testing/first-app-tests.jade
View File

@ -1,7 +1,7 @@
include ../../../../_includes/_util-fns
:markdown
In this chapter we’ll setup the environment for testing our sample application and write a few easy Jasmine tests of the app’s simplest parts.
:marked
In this chapter we’ll setup the environment for testing our sample application and write a few easy Jasmine tests of the app’s simplest parts.
We'll learn:
- to test one of our application classes
- why we prefer our test files to be next to their corresponding source files
@ -10,7 +10,7 @@ include ../../../../_includes/_util-fns
.callout.is-helpful
header Prior Knowledge
:markdown
:marked
The Unit Testing chapters build upon each other. We recommend reading them in order.
We're also assuming that you're already comfortable with basic Angular 2 concepts and the tools
we introduced in the [QuickStart](../quickstart.html) and
@ -18,7 +18,7 @@ include ../../../../_includes/_util-fns
such as <code>npm</code>, <code>gulp</code>, and <code>live-server</code>.
.l-main-section
:markdown
:marked
## Create the test-runner HTML
Step away from the Jasmine 101 folder and turn to the root folder of the application that we downloaded in the previous chapter.
@ -47,7 +47,7 @@ include ../../../../_includes/_util-fns
We’re picking up right where we left off. All we’ve done is change the title.
.l-main-section
:markdown
:marked
## Update `package.json` for testing
We’ll assume that the application has `package.json` file that looks more or less like
@ -61,7 +61,7 @@ pre.prettyprint.lang-bash
.alert.is-important Be sure to install <code>jasmine-core</code> , not <code>jasmine</code>!
:markdown
:marked
Let’s make one more change to the `package.json` script commands.
**Open the `package.json` ** and scroll to the `scripts` node. Look for the command named `test`. Change it to:
@ -71,7 +71,7 @@ pre.prettyprint.lang-bash
That command will launch `live-server` and open a browser to the `unit-tests.html` page we just wrote.
.l-main-section
:markdown
:marked
## First app tests
Believe it or not … we could start testing *some* of our app right away. For example, we can test the `Hero` class:
@ -135,7 +135,7 @@ pre.prettyprint.lang-bash
The description should be sufficient to identify the tested application part and its source file. Almost any convention will do as long as you and your team follow it consistently and are never confused.
.l-main-section
:markdown
:marked
## Run the tests
Open one terminal window and run the watching compiler command: `npm run tsc`
@ -149,7 +149,7 @@ figure.image-display
.l-main-section
:markdown
:marked
## Critique
Is this `Hero` class even worth testing? It’s essentially a property bag with almost no logic. Maybe we should have tested the cloning feature. Maybe we should have tested id generation. We didn’t bother because there wasn’t much to learn by doing that.
@ -161,7 +161,7 @@ figure.image-display
We need to relocate these tests to a separate file. Let’s do that next.
.l-main-section
:markdown
:marked
## Where do tests go?
Some people like to keep their tests in a `tests` folder parallel to the application source folder.
@ -178,7 +178,7 @@ figure.image-display
You may put your tests elsewhere if you wish. We’re putting ours inside the app, next to the source files that they test.
.l-main-section
:markdown
:marked
## First spec file
**Create** a new file, ** `hero.spec.ts` ** in `src/app` next to `hero.ts`.
@ -187,7 +187,7 @@ figure.image-display
.alert.is-important All of our unit test files follow this .spec naming pattern.
:markdown
:marked
Move the tests we just wrote in`unit-tests.html` to `hero.spec.ts` and convert them from JavaScript into TypeScript:
```
@ -230,26 +230,26 @@ figure.image-display
figure.image-display
img(src='/resources/images/devguide/first-app-tests/Jasmine-not-running-tests.png' style="width:400px;" alt="Jasmine not running any tests")
:markdown
:marked
That’s Jasmine saying “**things are _so_ bad that _I’m not running any tests_.**”
Open the browser’s Developer Tools (F12, Ctrl-Shift-i). There’s an error:
code-example(format="" language="html").
Uncaught ReferenceError: exports is not defined
.l-main-section
:markdown
:marked
## Load tests with systemjs
The immediate cause of the error is the `export` statement in `hero.ts`.
That error was there all along.
The immediate cause of the error is the `export` statement in `hero.ts`.
That error was there all along.
It wasn’t a problem until we tried to `import` the `Hero` class in our tests.
Our test environment lacks support for module loading.
Our test environment lacks support for module loading.
Apparently we can’t simply load our application and test scripts like we do with 3rd party JavaScript libraries.
We are committed to module loading in our application.
We are committed to module loading in our application.
Our app will call `import`. Our tests must do so too.
We add module loading support in four steps:
@ -296,39 +296,39 @@ figure.image-display
.l-main-section
:markdown
:marked
## Observations
### System.config
System.js demands that we specify a default extension for the filenames that correspond to whatever it is asked to import.
System.js demands that we specify a default extension for the filenames that correspond to whatever it is asked to import.
Without that default, it would translate an import statement such as `import {Hero} from ‘./here’` to a request for the file named `hero`.
Not `hero.js`. Just plain `hero`. Our server error with “404 - not found” because it doesn’t have a file of that name.
Once configured with a default extension of ‘js’,&nbsp; Systemjs requests `hero.js` which *does* exist and is promptly returned by our server.
### Asynchronous System.import
The call to `System.import` shouldn’t surprise us but it’s asynchronous nature might.
If we ponder this for a moment, we realize that it must be asynchronous because
The call to `System.import` shouldn’t surprise us but it’s asynchronous nature might.
If we ponder this for a moment, we realize that it must be asynchronous because
System.js may have to fetch the corresponding JavaScript file from the server.
Accordingly, `System.import` returns a promise and we must wait for that promise to resolve.
Accordingly, `System.import` returns a promise and we must wait for that promise to resolve.
Only then can Jasmine start evaluating the imported tests.
### window.onload
Jasmine doesn’t have a `start` method. It wires its own start to the browser window’s `load` event.
That makes sense if we’re loading our tests with script tags.
Jasmine doesn’t have a `start` method. It wires its own start to the browser window’s `load` event.
That makes sense if we’re loading our tests with script tags.
The browser raises the `load` event when it finishes loading all scripts.
But we’re not loading test scripts inline anymore.
We’re using the systemjs module loader and it won’t be done until long after the browser raised the `load` event.
But we’re not loading test scripts inline anymore.
We’re using the systemjs module loader and it won’t be done until long after the browser raised the `load` event.
Meanwhile, Jasmine started and ran to completion … with no tests to evaluate … before the import completed.
So we must wait until the import completes and only then call the window `onLoad` handler.
So we must wait until the import completes and only then call the window `onLoad` handler.
Jasmine re-starts, this time with our imported test queued up.
.l-main-section
:markdown
:marked
## What’s Next?
We are able to test a part of our application with simple Jasmine tests.
We are able to test a part of our application with simple Jasmine tests.
The part was a stand-alone class that made no mention or use of Angular.
That’s not rare but it’s not typical either. Most of our application parts make some use of the Angular framework.

8
public/docs/ts/latest/testing/index.jade
View File

@ -1,6 +1,6 @@
include ../../../../_includes/_util-fns
:markdown
:marked
We write **unit tests** to explore and confirm the **behavior** of parts of our application.
We like *having* unit tests for many reasons, three of them in particular:
@ -22,7 +22,7 @@ include ../../../../_includes/_util-fns
figure.image-display
img(src='/resources/images/devguide/unit-testing/spectrum.png' alt="Functional Testing Spectrum")
:markdown
:marked
<table style="box-shadow: none">
<tr>
<td style="border-bottom: none">Pure unit test</td>
@ -113,12 +113,12 @@ figure.image-display
.callout.is-helpful
header How to Use This Guide
:markdown
:marked
The Unit Testing chapters build upon each other. We recommend reading them in order.
We're also assuming that you're already comfortable with basic Angular 2 concepts and the tools
we introduced in the [QuickStart](../quickstart.html) and
the [Tour of Heroes](../tutorial/) tutorial
such as <code>npm</code>, <code>gulp</code>, and <code>live-server</code>.
:markdown
:marked
Let’s get started!

50
public/docs/ts/latest/testing/jasmine-testing-101.jade
View File

@ -1,6 +1,6 @@
include ../../../../_includes/_util-fns
:markdown
:marked
We’ll write our tests with the [Jasmine test framework](http://jasmine.github.io/2.3/introduction.html).
We’ll start by getting *some* tests to work - *any* tests at all.
@ -12,7 +12,7 @@ include ../../../../_includes/_util-fns
**Create a new project folder** perhaps called `angular2-unit-testing`.
.l-main-section
:markdown
:marked
## Install npm packages locally
Next follow all of the steps prescribed in “Install npm packages locally” of the
@ -24,19 +24,19 @@ pre.prettyprint.lang-bash
code npm install jasmine-core --save-dev --save-exact
.alert.is-important
:markdown
:marked
Be sure to install `jasmine-core` , not `jasmine`!
:markdown
:marked
**Create a sub-folder `src` ** for our tests and then **cd into it**.
We are going to **display and control our tests in the browser**.
.l-sub-section
:markdown
:marked
The browser is nice during development of a few tests. It’s not the best venue for working with a lot of tests and it won’t do at all for build automation. We’ll switch to the karma test-runner when the time comes. But the browser will do for now.
:markdown
:marked
Create a new file called`unit-tests.html` and enter the following:
```
<html>
@ -70,20 +70,20 @@ pre.prettyprint.lang-bash
figure.image-display
img(src='/resources/images/devguide/jasmine-testing-101/jasmine-1-spec-0-failures.png' style="height:170px;" alt="Jasmine HTML test output")
:markdown
:marked
It doesn’t get much simpler than that!
.l-main-section
:markdown
:marked
## First TypeScript Test
Perhaps too simple. We won’t write our entire test suite inside one HTML file.
Let’s **extract** that line of test code to a **new file in `src` called `1st.spec.ts` ** .
.l-sub-section
:markdown
:marked
Among Jasmine developers, a test is known as a “spec” and test filenames include the word “spec”. We’ll stick with that convention.
:markdown
:marked
The test we wrote is valid TypeScript because any JavaScript is valid TypeScript. But let’s make it more modern with an arrow function:
```
it('true is true', () => expect(true).toEqual(true));
@ -97,7 +97,7 @@ figure.image-display
That’s a reminder that we need to compile our TypeScript test files as we do our TypeScript application files. Do that next.
.l-main-section
:markdown
:marked
## Prepare for TypeScript
As we’ve seen before, we first have to tell the compiler how to compile our TypeScript files with
@ -125,12 +125,12 @@ pre.prettyprint.lang-bash
code npm run tsc
.alert.is-helpful
:markdown
:marked
Our editor and the compiler may complain that they don’t know
what `it` and `expect` are because they lack the typing files that describe Jasmine.
We can ignore those annoying complaints for now as they are harmless.
:markdown
:marked
If we reload the browser, we should see the same Jasmine test-runner output as before.
We’ll be evolving these tests rapidly and it would be nice to have the browser refresh automatically as we make changes and recompile.
@ -140,13 +140,13 @@ pre.prettyprint.lang-bash
pre.prettyprint.lang-bash
code npm start
:markdown
:marked
Now navigate to `1st-tests.html`
We should get the same Jasmine test-runner output as before.
.l-main-section
:markdown
:marked
## Add a describe and another test
We can’t tell what file produced these test results. We only have one file at the moment but soon we’ll write more.
@ -166,7 +166,7 @@ pre.prettyprint.lang-bash
figure.image-display
img(src='/resources/images/devguide/jasmine-testing-101/test-report-1-spec-0-failures.png' style="height:100px;" alt="1 spec, 0 failures")
:markdown
:marked
Let’s add another Jasmine test to `1st.spec.ts`
```
it('null is not the same thing as undefined',
@ -178,23 +178,23 @@ figure.image-display
figure.image-display
img(src='/resources/images/devguide/jasmine-testing-101/test-report-2-specs-0-failures.png' style="height:100px;" alt="refreshed 2 specs, 0 failures")
:markdown
:marked
What does a failing test look like? Remove the `.not`. The browser refreshes and shows:
figure.image-display
img(src='/resources/images/devguide/jasmine-testing-101/test-report-2-specs-1-failure.png' style="height:190px;" alt="failing test 2 specs, 1 failure")
:markdown
:marked
Click the `Spec List` link just below “2 specs, 1 failure” to see the summary again:
figure.image-display
img(src='/resources/images/devguide/jasmine-testing-101/spec-list-2-specs-1-failure.png' style="height:140px;" alt="2 specs, 1 failure")
:markdown
:marked
We can re-run just the failing test by double-clicking it. Try it!
.l-main-section
:markdown
:marked
## Debug the test
Suppose we didn’t know what was going on. We can debug it in the browser.
@ -209,7 +209,7 @@ figure.image-display
figure.image-display
img(src='/resources/images/devguide/jasmine-testing-101/null-to-equal-undefined.png' style="height:500px;" alt="null === undefined")
:markdown
:marked
How about that! They really aren’t equal.
- remove the breakpoint (right-click in the “Breakpoints” section and chose “Remove breakpoint”)
- Click the “play” icon to resume the test (or F8)
@ -222,14 +222,14 @@ figure.image-display
<!-- TODO
.l-main-section
:markdown
:marked
## Learn more
Learn more about basic Jasmine testing here
[Resources TBD](./#)
-->
.l-main-section
:markdown
:marked
## What’s Next?
Now that we’re familiar with Jasmine on its own, we’re ready to test an application.

48
public/docs/ts/latest/testing/testing-an-angular-pipe.jade
View File

@ -1,6 +1,6 @@
include ../../../../_includes/_util-fns
:markdown
:marked
We’ll test an Angular pipe in this chapter
An Angular pipe is a declarative way in HTML to transform some input into some displayable output.
@ -12,7 +12,7 @@ include ../../../../_includes/_util-fns
code-example(format="linenums" language="html" escape="html").
<h2>{{hero.name | initCaps}} is {{userName}}'s current super hero!</h2>
:markdown
:marked
The code for `InitCapsPipe` in `init-caps-pipe.ts` is quite brief:
```
@ -35,36 +35,36 @@ code-example(format="linenums" language="html" escape="html").
.callout.is-helpful
header Prior Knowledge
:markdown
:marked
The Unit Testing chapters build upon each other. We recommend reading them in order.
We're also assuming that you're already comfortable with basic Angular 2 concepts and the tools
we introduced in the [QuickStart](../quickstart.html) and
the [Tour of Heroes](../tutorial/) tutorial
such as <code>npm</code>, <code>gulp</code>, and <code>live-server</code>.
:markdown
:marked
## Add the Angular library
Looking back at `unit-tests.html` we realize that we have not loaded the Angular library.
Looking back at `unit-tests.html` we realize that we have not loaded the Angular library.
Yet we were able to load and test the application’s `Hero` class.
**We were lucky!** The `Hero` class has no dependence on Angular.
**We were lucky!** The `Hero` class has no dependence on Angular.
If it had depended on Angular, we’d still be staring at the Jasmine “big-time fail” screen:
figure.image-display
img(src='/resources/images/devguide/testing-an-angular-pipe/big-time-fail-screen.png'
img(src='/resources/images/devguide/testing-an-angular-pipe/big-time-fail-screen.png'
style="width:400px;" alt="Jasmine's' big time fail screen")
:markdown
If we then opened the browser’s Developer Tools (F12, Ctrl-Shift-I) and looked
in the console window, we would see that SystemJS
:marked
If we then opened the browser’s Developer Tools (F12, Ctrl-Shift-I) and looked
in the console window, we would see that SystemJS
tried to load Angular and couldn't find it.
code-example(format="" language="html" escape="html").
GET http://127.0.0.1:8080/src/angular2/angular2 404 (Not Found)
:markdown
We are writing an Angular application afterall and
we were going to need Angular sooner or later. That time has come.
GET http://127.0.0.1:8080/src/angular2/angular2 404 (Not Found)
:marked
We are writing an Angular application afterall and
we were going to need Angular sooner or later. That time has come.
The `InitCapsPiep` clearly depends on Angular as is clear in the first few lines:
```
import {Pipe} from 'angular2/angular2';
@ -112,11 +112,11 @@ code-example(format="" language="html" escape="html").
});
});
```
Note that each test is short (one line in our case).
Note that each test is short (one line in our case).
It has a clear label that accurately describes the test. And it makes exactly one expectation.
Anyone can read these tests and understand quickly what the test does and what the pipe does.
If one of the tests fails, we know which expected behavior is no longer true.
Anyone can read these tests and understand quickly what the test does and what the pipe does.
If one of the tests fails, we know which expected behavior is no longer true.
We’ll have little trouble maintaining these tests and adding more like them as we encounter new conditions to explore.
That’s the way we like our tests!
@ -129,10 +129,10 @@ code-example(format="" language="html" escape="html").
Hmm. We can’t just add `System.import('app/init-caps-pipe.spec')`.
The first `System.import` returns a promise as does this second import.
The first `System.import` returns a promise as does this second import.
We can’t run any of the Jasmine tests until **both imports are finished**.
Fortunately, we can create a new `Promise` that wraps both import promises and waits
Fortunately, we can create a new `Promise` that wraps both import promises and waits
for both to finish loading.
```
// #3. Import the spec files explicitly
@ -144,13 +144,13 @@ code-example(format="" language="html" escape="html").
Try it. The browser should refresh and show
figure.image-display
img(src='/resources/images/devguide/testing-an-angular-pipe/5-specs-0-failures.png'
img(src='/resources/images/devguide/testing-an-angular-pipe/5-specs-0-failures.png'
style="width:400px;" alt="import promises 5 specs, 0 failures")
:markdown
:marked
We have a pattern for adding new tests.
In future, when we add a new spec, we add another `System.import('app/some.spec')` to
In future, when we add a new spec, we add another `System.import('app/some.spec')` to
the array argument passed to `Promise.all`.
## What’s Next?
@ -159,5 +159,5 @@ figure.image-display
What about testing parts that *are themselves asynchronous*?
In the next chapter we’ll test a service with a public asynchronous method that fetches heroes
In the next chapter we’ll test a service with a public asynchronous method that fetches heroes
from a remote server.

26
public/docs/ts/latest/tutorial/index.jade
View File

@ -1,6 +1,6 @@
include ../../../../_includes/_util-fns
:markdown
:marked
# Tour of Heroes: the vision
Our grand plan is to build an app to help a staffing agency manage its stable of heroes.
@ -23,9 +23,9 @@ include ../../../../_includes/_util-fns
Angular can do whatever we need it to do.
We'll be covering a lot of ground at an introductory level but we’ll find plenty of links
to chapters with greater depth.
.l-main-section
:markdown
:marked
## The End Game
Here's a visual idea of where we're going in this tour, beginning with the "Dashboard"
@ -34,17 +34,17 @@ include ../../../../_includes/_util-fns
figure.image-display
img(src='/resources/images/devguide/toh/heroes-dashboard-1.png' alt="Output of heroes dashboard")
:markdown
:marked
Above the dashboard are two links ("Dashboard" and "Heroes").
We could click them to navigate between this Dashboard and a Heroes view.
Instead we click the dashboard hero named "Magneta" and the router takes us to a "Hero Details" view
of that hero where we can change the hero's name.
figure.image-display
img(src='/resources/images/devguide/toh/hero-details-1.png' alt="Details of hero in app")
:markdown
:marked
Links at the top can take us to either of the main views.
We'll click the "Back" button which sends us to the "Heroes" master list view with
"Magneta" as the selected hero.
@ -52,25 +52,25 @@ figure.image-display
figure.image-display
img(src='/resources/images/devguide/toh/heroes-list-1.png' alt="Output of heroes list app")
:markdown
:marked
We click a different hero and the readonly mini-detail beneath the list reflects our new choice.
We click the "View Details" button to drill into the
editable details of our selected hero.
The following diagram captures all of our navigation options.
figure.image-display
img(src='/resources/images/devguide/toh/nav-diagram.png' alt="View navigations")
:markdown
:marked
Here's our app in action
figure.image-display
img(src='/resources/images/devguide/toh/toh-anim.gif' alt="Tour of Heroes in Action")
.l-main-section
:markdown
:marked
## How We Roll
We’ll build this Tour of Heroes together, step by step.

54
public/docs/ts/latest/tutorial/toh-pt1.jade
View File

@ -1,7 +1,7 @@
include ../../../../_includes/_util-fns
.l-main-section
:markdown
:marked
# Once Upon a Time
Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
@ -22,32 +22,32 @@ include ../../../../_includes/_util-fns
| └── tsconfig.json
└── package.json
:markdown
:marked
### Keep the app running
Start the TypeScript compiler and have it watch for changes in one terminal window by typing
pre.prettyprint.lang-bash
code npm run tsc
:markdown
:marked
Now open another terminal window and start the server by typing
pre.prettyprint.lang-bash
code npm start
:markdown
:marked
This command starts the server, launches the app in a browser,
and keeps the app running while we continue to build the Tour of Heroes.
.l-sub-section
:markdown
:marked
These two steps watch all project files. They recompile TypeScript files and re-run
the app when any file changes.
If the watchers fail to detect renamed or new files,
stop these commands in each terminal by typing `CTRL+C` and then re-run them.
.l-main-section
:markdown
:marked
## Show our Hero
We want to display Hero data in our app
@ -61,12 +61,12 @@ include ../../../../_includes/_util-fns
}
```
:markdown
:marked
Now we update the template in the `@Component` decoration with data bindings to these new properties.
code-example(format="").
template: '&lt;h1>{{title}}&lt/h1>&lth2>{{hero}} details!&lt/h2>'
:markdown
:marked
The browser should refresh and display our title and hero.
The double curly braces tell our app to read the `title` and `hero` properties from the component and render them.
@ -103,7 +103,7 @@ include ../../../../_includes/_util-fns
code-example(format="").
template: '&lt;h1>{{title}}&lt/h1>&lth2>{{hero.name}} details!&lt/h2>'
:markdown
:marked
The browser refreshes and continues to display our hero’s name.
### Adding more HTML
@ -112,7 +112,7 @@ include ../../../../_includes/_util-fns
code-example(format="linenums").
template: '&lt;h1>{{title}}&lt/h1>&lth2>{{hero.name}} details!&lt/h2>&ltdiv>&ltlabel>id: &lt/label>{{hero.id}}&lt/div>&ltdiv>&ltlabel>name: &lt/label>{{hero.name}}&lt/div>'
:markdown
: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.
### Multi-line template strings
@ -136,7 +136,7 @@ include ../../../../_includes/_util-fns
.callout.is-important
header A back-tick is not a single quote
:markdown
: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.
@ -145,7 +145,7 @@ include ../../../../_includes/_util-fns
is part of a single template string.
.l-main-section
:markdown
:marked
## Editing Our Hero
We want to be able to edit the hero name in a textbox.
@ -161,7 +161,7 @@ include ../../../../_includes/_util-fns
&ltdiv>&ltinput value="{{hero.name}}" placeholder="name">&lt/div>
&lt/div>
`
:markdown
: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
@ -175,22 +175,22 @@ include ../../../../_includes/_util-fns
In short, we want two-way data binding.
Let’s update the template to use the **`ng-model`** built-in directive for two-way binding.
.l-sub-section
:markdown
:marked
Learn more about `ng-model` in the [Template Syntax](../guide/template-syntax.html#ng-model)
:markdown
:marked
Replace the `<input>` with the following HTML
code-example(language="html").
&lt;input [(ng-model)]="hero.name" placeholder="name">
:markdown
:marked
Unfortunately, that change broke our application and we're no longer displaying the hero in the browser.
Let’s fix that next.
.l-main-section
:markdown
:marked
## Declaring Template Directives
We added the `ng-model` directive but we didn't tell Angular about it.
@ -217,8 +217,8 @@ include ../../../../_includes/_util-fns
code-example(language="html").
EXCEPTION: No value accessor for ' ' in [null]
:markdown
:marked
Apparently declaring the `NgModel` is not quite enough.
## Declare Multiple Form Directives
@ -234,9 +234,9 @@ include ../../../../_includes/_util-fns
bundled in a convenient array called `FORM_DIRECTIVES`.
<!-- TODO
.alert.is-helpful
:markdown
:marked
Learn more about Angular Forms in the [Forms chapter]()
:markdown
:marked
-->
Let’s forget about importing `NgModel` and import the `FORM_DIRECTIVES` array instead:
```
@ -259,7 +259,7 @@ include ../../../../_includes/_util-fns
and plug that array into the `directives` property.
.l-main-section
:markdown
:marked
## The Road We’ve Travelled
Let’s take stock of what we’ve built.
@ -304,12 +304,12 @@ include ../../../../_includes/_util-fns
}
bootstrap(AppComponent);
.l-main-section
:markdown
: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 it in the
template, and allow a user to select it in the
[next tutorial chapter](./toh-pt2.html).

365
public/docs/ts/latest/tutorial/toh-pt2.jade
View File

@ -1,23 +1,23 @@
include ../../../../_includes/_util-fns
.l-main-section
:markdown
# It Takes Many Heroes
Our story needs more heroes.
We’ll expand our Tour of Heroes app to display a list of heroes,
allow the user to select a hero, and display the hero’s details.
Let’s take stock of what we’ll need to display a list of heroes.
First, we need a list of heroes. We want to display those heroes in the view’s template,
:marked
# It Takes Many Heroes
Our story needs more heroes.
We’ll expand our Tour of Heroes app to display a list of heroes,
allow the user to select a hero, and display the hero’s details.
Let’s take stock of what we’ll need to display a list of heroes.
First, we need a list of heroes. We want to display those heroes in the view’s template,
so we’ll need a way to do that.
.l-main-section
:markdown
:marked
## Where We Left Off
Before we continue with Part 2 of the Tour of Heroes,
Before we continue with Part 2 of the Tour of Heroes,
let’s verify we have the following structure after [Part 1](./toh-pt1.html).
If not, we’ll need to go back to Part 1 and figure out what we missed.
code-example.
angular2-tour-of-heroes
├── node_modules
@ -26,25 +26,25 @@ include ../../../../_includes/_util-fns
| | └── app.ts
| ├── index.html
| └── tsconfig.json
└── package.json
:markdown
└── package.json
:marked
### Keep the app running
Start the TypeScript compiler and have it watch for changes in one terminal window by typing
pre.prettyprint.lang-bash
code npm run tsc
:markdown
:marked
Now open another terminal window and start the server by typing
pre.prettyprint.lang-bash
code npm start
:markdown
:marked
This will keep the application running while we continue to build the Tour of Heroes.
.l-main-section
:markdown
:marked
## Displaying Our Heroes
### Creating heroes
Let’s create an array of ten heroes at the bottom of `app.ts`.
@ -62,11 +62,11 @@ include ../../../../_includes/_util-fns
{ "id": 20, "name": "Tornado" }
];
```
The `HEROES` array is of type `Hero`.
We are taking advantage of the `Hero` class we coded previously to create an array of our heroes.
We aspire to get this list of heroes from a web service, but let’s take small steps
The `HEROES` array is of type `Hero`.
We are taking advantage of the `Hero` class we coded previously to create an array of our heroes.
We aspire to get this list of heroes from a web service, but let’s take small steps
on this road and start by displaying these mock heroes in the browser.
### Exposing heroes
Let’s create a public property in `AppComponent` that exposes the heroes for binding.
```
@ -74,14 +74,14 @@ include ../../../../_includes/_util-fns
```
We did not have to define the `heroes` type. TypeScript can infer it from the `HEROES` array.
.l-sub-section
:markdown
We could have defined the heroes list here in this component class.
But we know that we’ll get the heroes from a data service.
Because we know where we are heading, it makes sense to separate the hero data
:marked
We could have defined the heroes list here in this component class.
But we know that we’ll get the heroes from a data service.
Because we know where we are heading, it makes sense to separate the hero data
from the class implementation from the start.
:markdown
:marked
### Displaying heroes in a template
Our component has`heroes`. Let’s create an unordered list in our template to display them.
Our component has`heroes`. Let’s create an unordered list in our template to display them.
We’ll insert the following chunk of HTML below the title and above the hero details.
```
<h2>My Heroes</h2>
@ -94,79 +94,79 @@ include ../../../../_includes/_util-fns
Now we have a template that we can fill with our heroes.
### Listing heroes with ng-for
We want to bind the array of `heroes` in our component to our template, iterate over them,
and display them individually.
We want to bind the array of `heroes` in our component to our template, iterate over them,
and display them individually.
We’ll need some help from Angular to do this. Let’s do this step by step.
First modify the `<li>` tag by adding the built-in directive `*ng-for`.
First modify the `<li>` tag by adding the built-in directive `*ng-for`.
```
<li *ng-for="#hero of heroes">
```
.alert.is-critical
:markdown
:marked
The leading asterisk (`*`) in front of `ng-for` is a critical part of this syntax.
.l-sub-section
:markdown
:marked
The (`*`) prefix to `ng-for` indicates that the `<li>` element and its children
constitute a master template.
The `ng-for` directive iterates over the `heroes` array returned by the `AppComponent.heroes` property
and stamps out instances of this template.
The quoted text assigned to `ng-for` means
The quoted text assigned to `ng-for` means
“*take each hero in the `heroes` array, store it in the local `hero` variable,
and make it available to the corresponding template instance*”.
The `#` prefix before "hero" identifies the `hero` as a local template variable.
The `#` prefix before "hero" identifies the `hero` as a local template variable.
We can reference this variable within the template to access a hero’s properties.
Learn more about `ng-for` and local template variables in the
Learn more about `ng-for` and local template variables in the
[Template Syntax](../guide/template-syntax.html#ng-for) chapter.
:markdown
With this background in mind, we now insert some content between the `<li>` tags
:marked
With this background in mind, we now insert some content between the `<li>` tags
that uses the `hero` template variable to display the hero’s properties.
code-example(format="linenums" language="html").
&lt;li *ng-for="#hero of heroes">
&lt;span class="badge">{{hero.id}}&lt;/span> {{hero.name}}
&lt;/li>
:markdown
:marked
### Declaring ng-for
When we view the running app in the browser we see nothing … no heroes.
When we view the running app in the browser we see nothing … no heroes.
We open the developer tools and see an error in the console.
code-example(language="html" ).
EXCEPTION:
Can't bind to 'ngForOf' since it isn't a known property of the '&lt;template>' element and
EXCEPTION:
Can't bind to 'ngForOf' since it isn't a known property of the '&lt;template>' element and
there are no matching directives with a corresponding property
:markdown
Thankfully we have a clear error message that indicates where we went wrong.
We used `ng-for` in the template but we didn’t tell the component about it.
From Angular's perspective, `ng-for` is a meaningless attribute.
:marked
Thankfully we have a clear error message that indicates where we went wrong.
We used `ng-for` in the template but we didn’t tell the component about it.
From Angular's perspective, `ng-for` is a meaningless attribute.
When it tries to render the view, it doesn’t recognize `ng-for` and gives up.
We need to say “*hey component, I’m going to use this NgFor directive. OK?*”
To that end, we first import the `NgFor` symbol
```
import {bootstrap, Component, FORM_DIRECTIVES, NgFor} from 'angular2/angular2';
```
and then declare `NgFor` to be one of the view’s directives in the `@Component` decorator.
and then declare `NgFor` to be one of the view’s directives in the `@Component` decorator.
```
directives: [FORM_DIRECTIVES, NgFor]
```
After the browser refreshes, we see a list of heroes!
### Styling our heroes
Our list of heroes looks pretty bland.
We want to make it visually obvious to a user which hero we are hovering over and which hero is selected.
Let’s add some styles to our component by setting the `styles` property on the `@Component` decorator
Let’s add some styles to our component by setting the `styles` property on the `@Component` decorator
to the following CSS classes:
```
styles:[`
@ -187,109 +187,109 @@ include ../../../../_includes/_util-fns
`],
```
Notice that we again use the back-tick notation for multi-line strings.
When we assign styles to a component they are scoped to that specific component.
When we assign styles to a component they are scoped to that specific component.
Our styles will only apply to our `AppComponent` and won't "leak" to the outer HTML.
Our template for displaying the heroes should now look like this:
code-example(format="linenums").
code-example(format="linenums").
&lt;h2>My Heroes&lt;/h2>
&lt;ul class="heroes">
&lt;li *ng-for="#hero of heroes">
&lt;span class="badge">{{hero.id}}&lt;/span> {{hero.name}}
&lt;/li>
&lt;/ul>
:markdown
:marked
Our styled list of heroes should look like this:
figure.image-display
img(src='/resources/images/devguide/toh/heroes-list-2.png' alt="Output of heroes list app (no selection color)")
img(src='/resources/images/devguide/toh/heroes-list-2.png' alt="Output of heroes list app (no selection color)")
.l-main-section
:markdown
:marked
## Selecting a Hero
We have a list of heroes and we have a single hero displayed in our app.
The list and the single hero are not connected in any way.
We want the user to select a hero from our list, and have the selected hero appear in the details view.
This UI pattern is widely known as “master-detail”.
In our case, the master is the heroes list and the detail is the selected hero.
We have a list of heroes and we have a single hero displayed in our app.
The list and the single hero are not connected in any way.
We want the user to select a hero from our list, and have the selected hero appear in the details view.
This UI pattern is widely known as “master-detail”.
In our case, the master is the heroes list and the detail is the selected hero.
Let’s connect the master to the detail through a `selectedHero` component property bound to a click event.
### Click event
We modify the `<li>` by inserting an Angular event binding to its click event.
code-example(format="linenums").
code-example(format="linenums").
&lt;li *ng-for="#hero of heroes" (click)="onSelect(hero)">
&lt;span class="badge">{{hero.id}}&lt;/span> {{hero.name}}
&lt;/li>
:markdown
:marked
Focus on the event binding
pre.prettyprint.lang-bash
code (click)="onSelect(hero)">
:markdown
The parenthesis identify the `<li>` element’s `click` event as the target.
The expression to the right of the equal sign calls the `AppComponent` method, `onSelect()`,
:marked
The parenthesis identify the `<li>` element’s `click` event as the target.
The expression to the right of the equal sign calls the `AppComponent` method, `onSelect()`,
passing the local template variable `hero` as an argument.
That’s the same `hero` variable we defined previously in the `ng-for`.
.l-sub-section
:markdown
:marked
Learn more about Event Binding in the [Templating Syntax](../guide/template-syntax.html#event-binding) chapter.
:markdown
:marked
### Add the click handler
Our event binding refers to an `onSelect` method that doesn’t exist yet.
We’ll add that method to our component now.
Our event binding refers to an `onSelect` method that doesn’t exist yet.
We’ll add that method to our component now.
What should that method do? It should set the component’s selected hero to the hero that the user clicked.
Our component doesn’t have a “selected hero” yet either. We’ll start there.
### Expose the selected hero
### Expose the selected hero
We no longer need the static `hero` property of the `AppComponent`.
**Replace** it with this simple `selectedHero` property:
```
public selectedHero: Hero;
```
We’ve decided that none of the heroes should be selected before the user picks a hero so
we won’t initialize the `selectedHero` as we were doing with `hero`.
We’ve decided that none of the heroes should be selected before the user picks a hero so
we won’t initialize the `selectedHero` as we were doing with `hero`.
Now **add an `onSelect` method** that sets the `selectedHero` property to the `hero` the user clicked.
```
onSelect(hero: Hero) { this.selectedHero = hero; }
```
We will be showing the selected hero's details in our template.
At the moment, it is still referring to the old `hero` property.
We will be showing the selected hero's details in our template.
At the moment, it is still referring to the old `hero` property.
Let’s fix the template to bind to the new `selectedHero` property.
code-example(format="linenums").
code-example(format="linenums").
&lt;h2>{{selectedHero.name}} details!&lt;/h2>
&lt;div>&lt;label>id: &lt;/label>{{selectedHero.id}}&lt;/div>
&lt;div>
&lt;label>name: &lt;/label>
&lt;input [(ng-model)]="selectedHero.name" placeholder="name">&lt;/input>
&lt;/div>
:markdown
:marked
### Hide the empty detail with ng-if
When our app loads we see a list of heroes, but a hero is not selected.
The `selectedHero` is `undefined`.
When our app loads we see a list of heroes, but a hero is not selected.
The `selectedHero` is `undefined`.
That’s why we'll see the following error in the browser’s console:
code-example(language="html").
EXCEPTION: TypeError: Cannot read property 'name' of undefined in [null]
:markdown
Remember that we are displaying `selectedHero.name` in the template.
This name property does not exist because `selectedHero`itself is undefined.
:marked
Remember that we are displaying `selectedHero.name` in the template.
This name property does not exist because `selectedHero`itself is undefined.
We'll address this problem by keeping the hero detail out of the DOM until there is a selected hero.
We wrap the HTML hero detail content of our template with a `<div>`.
We wrap the HTML hero detail content of our template with a `<div>`.
Then we add the `ng-if` built-in directive and set it to the `selectedHero` property of our component.
code-example(format="linenums").
&lt;div *ng-if="selectedHero">
&lt;h2>{{selectedHero.name}} details!&lt;/h2>
@ -300,58 +300,58 @@ include ../../../../_includes/_util-fns
&lt;/div>
&lt;/div>
.alert.is-critical
:markdown
Remember that the leading asterisk (`*`) in front of `ng-if` is
:marked
Remember that the leading asterisk (`*`) in front of `ng-if` is
a critical part of this syntax.
:markdown
When there is no `selectedHero`, the `ng-if` directive removes the hero detail HTML from the DOM.
There will be no hero detail elements and no bindings to worry about.
:marked
When there is no `selectedHero`, the `ng-if` directive removes the hero detail HTML from the DOM.
There will be no hero detail elements and no bindings to worry about.
When the user picks a hero, `selectedHero` becomes "truthy" and
`ng-if` puts the hero detail content into the DOM and evaluates the nested bindings.
`ng-if` puts the hero detail content into the DOM and evaluates the nested bindings.
.l-sub-section
:markdown
`ng-if` and `ng-for` are called “structural directives” because they can change the
structure of portions of the DOM.
:marked
`ng-if` and `ng-for` are called “structural directives” because they can change the
structure of portions of the DOM.
In other words, they give structure to the way Angular displays content in the DOM.
Learn more about `ng-if`, `ng-for` and other structural directives in the
Learn more about `ng-if`, `ng-for` and other structural directives in the
[Template Syntax](../guide/template-syntax.html#directives) chapter
:markdown
We learned previously with `NgFor` that we must declare every directive we use in the component’s `@Component` decorator.
:marked
We learned previously with `NgFor` that we must declare every directive we use in the component’s `@Component` decorator.
Let’s do that again for `NgIf`.
Add the `NgIf` symbol to our imports at the top of our `app.ts` file, keeping them sorted
alphabetically to make them easier to find:
```
import {bootstrap, Component, FORM_DIRECTIVES, NgFor, NgIf} from 'angular2/angular2';
```
:markdown
:marked
Now add `NgIf` to the directives array in the `@Component` decorator:
```
directives: [FORM_DIRECTIVES, NgFor, NgIf]
```
The browser refreshes and we see the list of heroes but not the selected hero detail.
The `ng-if` keeps it out of the DOM as long as the `selectedHero` is undefined.
When we click on a hero in the list, the selected hero displays in the hero details.
The browser refreshes and we see the list of heroes but not the selected hero detail.
The `ng-if` keeps it out of the DOM as long as the `selectedHero` is undefined.
When we click on a hero in the list, the selected hero displays in the hero details.
Everything is working as we expect.
### Styling the selection
We see the selected hero in the details area below but we can’t quickly locate that hero in the list above.
We can fix that by applying the `selected` CSS class to the appropriate `<li>` in the master list.
For example, when we select Magneta from the heroes list,
We see the selected hero in the details area below but we can’t quickly locate that hero in the list above.
We can fix that by applying the `selected` CSS class to the appropriate `<li>` in the master list.
For example, when we select Magneta from the heroes list,
we can make it pop out visually by giving it a subtle background color as shown here.
figure.image-display
img(src='/resources/images/devguide/toh/heroes-list-selected.png' alt="Selected hero")
:markdown
First we’ll add a `getSelectedClass` method to the component that compares the current `selectedHero` to a hero parameter
and returns an object with a single key/value pair.
The key is the name of the CSS class (`selected`). The value is `true` if the two heroes match and `false` otherwise.
We’re saying “*apply the `selected` class if the heroes match, remove it if they don’t*”.
:marked
First we’ll add a `getSelectedClass` method to the component that compares the current `selectedHero` to a hero parameter
and returns an object with a single key/value pair.
The key is the name of the CSS class (`selected`). The value is `true` if the two heroes match and `false` otherwise.
We’re saying “*apply the `selected` class if the heroes match, remove it if they don’t*”.
Here is that method.
```
getSelectedClass(hero: Hero) {
@ -359,62 +359,62 @@ include ../../../../_includes/_util-fns
}
```
What do we do with this method and its peculiar result?
### ng-class
We’ll add the `ng-class`built-in directive to the `<li>` element in our template and bind it to `getSelectedClass`.
It’s no coincidence that the value returned by `getSelectedClass` is exactly what the `ng-class` requires
It’s no coincidence that the value returned by `getSelectedClass` is exactly what the `ng-class` requires
to add or remove the `selected` class to each hero’s display.
code-example(format="linenums").
code-example(format="linenums").
&lt;li *ng-for="#hero of heroes"
[ng-class]="getSelectedClass(hero)"
(click)="onSelect(hero)">
&lt;span class="badge">{{hero.id}}&lt;/span> {{hero.name}}
&lt;/li>
:markdown
Notice in the template that the `ng-class` name is surrounded in square brackets (`[]`).
This is the syntax for a Property Binding, a binding in which data flows one way
from the data source (the `getSelectedClass`) to a property of the `ng-class` directive.
:marked
Notice in the template that the `ng-class` name is surrounded in square brackets (`[]`).
This is the syntax for a Property Binding, a binding in which data flows one way
from the data source (the `getSelectedClass`) to a property of the `ng-class` directive.
.l-sub-section
:markdown
:marked
Learn more about [ng-class](../guide/template-syntax.html#ng-class)
and [Property Binding](../guide/template-syntax.html#property-binding)
and [Property Binding](../guide/template-syntax.html#property-binding)
in the Template Syntax chapter
:markdown
We've added yet another new directive to our template that we have to import and declare
:marked
We've added yet another new directive to our template that we have to import and declare
in the component’s `directives` array as we’ve done twice before.
```
import {bootstrap, Component,
import {bootstrap, Component,
FORM_DIRECTIVES, NgClass, NgFor, NgIf} from 'angular2/angular2';
```
```
```
directives: [FORM_DIRECTIVES, NgClass, NgFor, NgIf]
```
The browser reloads our app.
The browser reloads our app.
We select a hero and the selection is clearly identified by the background color.
figure.image-display
img(src='/resources/images/devguide/toh/heroes-list-1.png' alt="Output of heroes list app")
:markdown
:marked
We select a different hero and the tell-tale color switches to that hero.
## Declaring Built-In Directives
Every time we used a directive, we imported it and declared it in the component.
We only used three directives but we can easily envision a component that uses many more.
The `directives` array grows quickly and the process of importing the directive and adding it to the array is tedious.
Every time we used a directive, we imported it and declared it in the component.
We only used three directives but we can easily envision a component that uses many more.
The `directives` array grows quickly and the process of importing the directive and adding it to the array is tedious.
We can make this easier.
Remember how we imported the `FORM_DIRECTIVES` array to help us apply `ng-model`to our template in the previous chapter?
The `FORM_DIRECTIVES` array held all the directives we needed for `ng-model` (and a few more).
The `FORM_DIRECTIVES` array held all the directives we needed for `ng-model` (and a few more).
We didn’t have to list them. We simply added the `FORM_DIRECTIVES` array to the component’s `directives` array.
The `NgClass`, `NgFor`, and `NgIf` are extremely common directives used by many components in many applications.
Fortunately they are all exported from Angular as part of the `CORE_DIRECTIVES` array.
The `NgClass`, `NgFor`, and `NgIf` are extremely common directives used by many components in many applications.
Fortunately they are all exported from Angular as part of the `CORE_DIRECTIVES` array.
Let’s replace all of those separate import variables with `CORE_DIRECTIVES`:
```
import {bootstrap, Component, CORE_DIRECTIVES, FORM_DIRECTIVES} from 'angular2/angular2';
@ -423,20 +423,19 @@ include ../../../../_includes/_util-fns
```
directives: [CORE_DIRECTIVES, FORM_DIRECTIVES]
```
Everything still works and we have a convenient way to import and declare the most commonly used directives.
Cleaner code for the win!
Everything still works and we have a convenient way to import and declare the most commonly used directives.
Cleaner code for the win!
.l-main-section
:markdown
:marked
## The Road We’ve Travelled
Here’s what we achieved in this chapter:
* Our Tour of Heroes now displays a list of selectable heroes
* Our Tour of Heroes now displays a list of selectable heroes
* We added the ability to select a hero and show the hero’s details
* We learned how to use the built-in directives `ng-if`, `ng-for` and `ng-class` in a component’s template
### The Road Ahead
Our Tour of Heroes has grown, but it’s far from complete.
We want to get data from an asynchronous source using promises, use shared services, and create reusable components.
Our Tour of Heroes has grown, but it’s far from complete.
We want to get data from an asynchronous source using promises, use shared services, and create reusable components.
We’ll learn more about these tasks in the coming tutorial chapters.

4
tools/api-builder/angular.io-package/rendering/indentForMarkdown.js
View File

@ -22,14 +22,14 @@ module.exports = function(encodeCodeBlock) {
newLines.pop();
} else {
// wierd case - first expression in str is an @example
// in this case the :markdown appear above the str passed in,
// in this case the :marked appear above the str passed in,
// so we need to put 'something' into the markdown tag.
newLines.push(sp + "."); // '.' is a dummy char
}
}
newLines.push(spMixin + line);
// after a mixin line we need to reenter markdown.
newLines.push(spMixin + ':markdown');
newLines.push(spMixin + ':marked');
isAfterMarkdownTag = true;
} else {
if ((!isAfterMarkdownTag) || (line.trim().length > 0)) {

6
tools/api-builder/angular.io-package/templates/class.template.html
View File

@ -14,7 +14,7 @@ p.location-badge.
exported from {@link {$ doc.moduleDoc.id $} {$doc.moduleDoc.id $} }
defined in {$ githubViewLink(doc) $}
:markdown
:marked
{%- if doc.notYetDocumented %}
*Not Yet Documented*
{% else %}
@ -43,7 +43,7 @@ p.location-badge.
pre.prettyprint
code.
{$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.parameters) | indent(8, false) | trim $}
:markdown
:marked
{$ doc.constructorDoc.description | indentForMarkdown(6) | replace('## Example', '') | replace('# Example', '') | trimBlankLines $}
{% endif -%}
@ -54,7 +54,7 @@ p.location-badge.
code.
{$ member.name $}{$ paramList(member.parameters) | indent(8, false) | trim $}{$ returnType(member.returnType) $}
:markdown
:marked
{$ member.description | indentForMarkdown(6) | replace('## Example', '') | replace('# Example', '') | trimBlankLines $}
{% endif %}{% endfor %}

4
tools/api-builder/angular.io-package/templates/directive.template.html
View File

@ -17,7 +17,7 @@
code {$ property.bindingName | dashCase $}
| &nbsp;bound to&nbsp;
code {$ property.memberDoc.classDoc.name $}.{$ property.propertyName $}
:markdown
:marked
{$ property.memberDoc.description | indentForMarkdown(2) | trimBlankLines $}{% endfor %}
{% endif %}
@ -29,7 +29,7 @@
code {$ property.bindingName | dashCase $}
| &nbsp;bound to&nbsp;
code {$ property.memberDoc.classDoc.name $}.{$ property.propertyName $}
:markdown
:marked
{$ event.memberDoc.description | indentForMarkdown(2) | trimBlankLines $}
{% endfor %}
{% endif %}

2
tools/api-builder/angular.io-package/templates/function.template.html
View File

@ -14,7 +14,7 @@ include ../../_util-fns
exported from {@link {$ doc.moduleDoc.id $} {$doc.moduleDoc.id $} }
defined in {$ githubViewLink(doc) $}
:markdown
:marked
{$ doc.description | indentForMarkdown(4) | trimBlankLines $}
{% endblock %}

2
tools/api-builder/angular.io-package/templates/var.template.html
View File

@ -14,7 +14,7 @@ include ../../_util-fns
exported from {@link {$ doc.moduleDoc.id $} {$doc.moduleDoc.id $} }
defined in {$ githubViewLink(doc) $}
:markdown
:marked
{%- if doc.notYetDocumented %}
### *Not Yet Documented*
{% else %}

2
tools/api-builder/docs-package/processors/convertBackticksToCodeBlocks.js
View File

@ -49,7 +49,7 @@ module.exports = function convertBackticksToCodeBlocks() {
// modulo op in next line insures that pad is always a multiple of 2 ( jade whitespace).
postPad = postPad.substr(2 + (postPad.length % 2)); // exdent
}
replaceVal = replaceVal + postPad + ':markdown\n';
replaceVal = replaceVal + postPad + ':marked\n';
}
doc.renderedContent = doc.renderedContent.replace(entireBlock, replaceVal);
captures = BACKTICK_CAPTURE.exec(doc.renderedContent);

2
tools/api-builder/docs-package/processors/convertBackticksToCodeBlocks.spec.js
View File

@ -30,7 +30,7 @@ describe('convertBackticksToCodeBlocks', function() {
'export class TypeScriptClass {\n' +
'}\n' +
'\n' +
':markdown\n' +
':marked\n' +
'postamble\n'
);
});

26
tools/doc-shredder/_test/test_jade/guides/setupAlt2.jade
View File

@ -1,7 +1,7 @@
include ../../../../_includes/_util-fns
.l-main-section
:markdown
:marked
## Install Angular2
There are four steps to create any Angular app:
@ -19,33 +19,33 @@ include ../../../../_includes/_util-fns
.callout.is-helpful
header Typescript vs ES5
:markdown
:marked
Although we work through the examples in TypeScript, you can also use
regular ES5. Click the ES5 link in any code box to see the ES5 JavaScript
version. Note that in ES5, you'd want to name your files `.js` rather than
`.ts`.
.l-main-section
:markdown
:marked
## Create an entry point
Create an `index.html` file and add the Angular library tags and a `main.ts` file where
you'll build your first component.
In the `<body>`, add an element called `<my-app>` that will be the root of your
application.
The TypeScript setup includes System.js, a third-party open-source library that adds ES6 module loading functionality to browsers. This step isn't needed for the ES5 version.
+makeTabs('gettingstarted', 'ts/index.html,js/index.html', 'TypeScript, JavaScript')
.callout.is-helpful
header Don't use code.angularjs.org in a live app
:markdown
:marked
This example serves the Angular library from <a href="http://code.angularjs.org">code.angularjs.org</a>. This is
fine for examples, but you'd want to serve it yourself or use a CDN for real deployment.
.l-main-section
:markdown
:marked
## Set up the starting component
In `main.ts`, create a class called `AppComponent`, configure it to bind to the
@ -56,14 +56,14 @@ include ../../../../_includes/_util-fns
.callout.is-helpful
header Annotations vs Decorators
:markdown
:marked
If you are transpiling using a tool that translates the `@` symbols to
annotations (for example Traceur), you will need to import the annotation versions of
Component and View. That can be easily achieved using
`import {ComponentAnnotation as Component, ViewAnnotation as View}`.
.l-main-section
:markdown
:marked
## Run it!
Open `index.html` through your web server and you should see:
@ -72,13 +72,13 @@ include ../../../../_includes/_util-fns
img(src='/resources/images/examples/setup-example1.png' alt="Example of Todo App")
.l-main-section
:markdown
:marked
## Explanations
This basic Angular app contains the structure for any app you'll build.
.l-sub-section
:markdown
:marked
### It's all a tree
You can think of Angular apps as a tree of components. This root component we've been talking about acts as the top
@ -94,7 +94,7 @@ include ../../../../_includes/_util-fns
these in the following pages.
.l-sub-section
:markdown
:marked
### @Component and @View annotations
A component annotation describes details about the component. An annotation can be identified by its at-sign (`@`).
@ -104,7 +104,7 @@ include ../../../../_includes/_util-fns
The `@View` annotation defines the HTML that represents the component. The component you wrote uses an inline template, but you can also have an external template. To use an external template, specify a <code>templateUrl</code> property and give it the path to the HTML file.
.l-sub-section
:markdown
:marked
### import vs. window.angular
The main difference between the ES5 and TypeScript versions is the loading of modules.

22
tools/doc-shredder/_test/test_jade/setupAlt.jade
View File

@ -1,7 +1,7 @@
include ../../../../_includes/_util-fns
.l-main-section
:markdown
:marked
## Install Angular2
There are four steps to create any Angular app:
@ -19,14 +19,14 @@ include ../../../../_includes/_util-fns
.callout.is-helpful
header Typescript vs ES5
:markdown
:marked
Although we work through the examples in TypeScript, you can also use
regular ES5. Click the ES5 link in any code box to see the ES5 JavaScript
version. Note that in ES5, you'd want to name your files `.js` rather than
`.ts`.
.l-main-section
:markdown
:marked
## Create an entry point
Create an `index.html` file and add the Angular library tags and a `main.ts` file where
you'll build your first component.
@ -40,12 +40,12 @@ include ../../../../_includes/_util-fns
.callout.is-helpful
header Don't use code.angularjs.org in a live app
:markdown
:marked
This example serves the Angular library from <a href="http://code.angularjs.org">code.angularjs.org</a>. This is
fine for examples, but you'd want to serve it yourself or use a CDN for real deployment.
.l-main-section
:markdown
:marked
## Set up the starting component
In `main.ts`, create a class called `AppComponent`, configure it to bind to the
@ -56,14 +56,14 @@ include ../../../../_includes/_util-fns
.callout.is-helpful
header Annotations vs Decorators
:markdown
:marked
If you are transpiling using a tool that translates the `@` symbols to
annotations (for example Traceur), you will need to import the annotation versions of
Component and View. That can be easily achieved using
`import {ComponentAnnotation as Component, ViewAnnotation as View}`.
.l-main-section
:markdown
:marked
## Run it!
Open `index.html` through your web server and you should see:
@ -72,13 +72,13 @@ include ../../../../_includes/_util-fns
img(src='/resources/images/examples/setup-example1.png' alt="Example of Todo App")
.l-main-section
:markdown
:marked
## Explanations
This basic Angular app contains the structure for any app you'll build.
.l-sub-section
:markdown
:marked
### It's all a tree
You can think of Angular apps as a tree of components. This root component we've been talking about acts as the top
@ -94,7 +94,7 @@ include ../../../../_includes/_util-fns
these in the following pages.
.l-sub-section
:markdown
:marked
### @Component and @View annotations
A component annotation describes details about the component. An annotation can be identified by its at-sign (`@`).
@ -104,7 +104,7 @@ include ../../../../_includes/_util-fns
The `@View` annotation defines the HTML that represents the component. The component you wrote uses an inline template, but you can also have an external template. To use an external template, specify a <code>templateUrl</code> property and give it the path to the HTML file.
.l-sub-section
:markdown
:marked
### import vs. window.angular
The main difference between the ES5 and TypeScript versions is the loading of modules.