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

Guide & Features edits (#2180) 

* Guide & Features edits

* PR updates & Architecture edits

* a couple we -> you updates

* architecture edits

* copy edits in arch., index, npm-packages

* few copy edits

* some chapter -> page changes
This commit is contained in:
Kapunahele Wong 2016-08-29 11:37:39 -04:00 committed by Kathy Walrath
parent 5fd6ae3099
commit 2ec07472ea
12 changed files with 297 additions and 346 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -71,7 +71,7 @@ If you are only going to work on a specific part of the docs, such as the dev gu
## Code Sample Development
All documentation is supported by sample code and plunkers.
Such code resides in the `public/docs/_examples` directory, under chapter-specific directories, further divided by language track.
Such code resides in the `public/docs/_examples` directory, under page-specific directories, further divided by language track.
For example, the TypeScript QuickStart sample is in `public/docs/_examples/quickstart/ts`.

2
public/docs/js/latest/guide/forms-deprecated.jade
View File

@ -208,7 +208,7 @@ code-example(format="").
**We are not using Angular yet**. There are no bindings. No extra directives. Just layout.
The `container`,`form-group`, `form-control`, and `btn` classes
come from [Twitter Boostrap](http://getbootstrap.com/css/). Purely cosmetic.
come from [Twitter Bootstrap](http://getbootstrap.com/css/). Purely cosmetic.
We're using Bootstrap to gussy up our form.
Hey, what's a form without a little style!

2
public/docs/js/latest/guide/forms.jade
View File

@ -224,7 +224,7 @@ code-example(format="").
**We are not using Angular yet**. There are no bindings. No extra directives. Just layout.
The `container`,`form-group`, `form-control`, and `btn` classes
come from [Twitter Boostrap](http://getbootstrap.com/css/). Purely cosmetic.
come from [Twitter Bootstrap](http://getbootstrap.com/css/). Purely cosmetic.
We're using Bootstrap to gussy up our form.
Hey, what's a form without a little style!

2
public/docs/ts/_cache/glossary.jade
View File

@ -32,7 +32,7 @@ block includes
.l-sub-section
:marked
Angular applications can be compiled by developers at build-time.
By compiling your application using the compiler-cli, `ngc`, you can boostrap directly
By compiling your application using the compiler-cli, `ngc`, you can bootstrap directly
to a Module Factory, meaning you don't need to include the Angular compiler in your javascript bundle.
Ahead of Time compiled applications also benefit from decreased load time and increased performance.

2
public/docs/ts/latest/glossary.jade
View File

@ -32,7 +32,7 @@ block includes
.l-sub-section
:marked
Angular applications can be compiled by developers at build-time.
By compiling your application using the compiler-cli, `ngc`, you can boostrap directly
By compiling your application using the compiler-cli, `ngc`, you can bootstrap directly
to a Module Factory, meaning you don't need to include the Angular compiler in your javascript bundle.
Ahead of Time compiled applications also benefit from decreased load time and increased performance.

2
public/docs/ts/latest/guide/_data.json
View File

@ -115,7 +115,7 @@
"npm-packages": {
"title": "Npm Packages",
"intro": "Details of the recommended npm packages and the different kinds of package dependencies"
"intro": "Recommended npm packages, and how to specify package dependencies"
},
"pipes": {

281
public/docs/ts/latest/guide/architecture.jade
View File

@ -4,25 +4,24 @@ block includes
- var _at_angular = '@angular'
:marked
Angular 2 is a framework to help us build client applications in HTML and
Angular 2 is a framework for building client applications in HTML and
either JavaScript or a language (like Dart or TypeScript) that compiles to JavaScript.
block angular-parts
:marked
The framework consists of several cooperating libraries, some of them core and some optional.
The framework consists of several libraries, some of them core and some optional.
:marked
We write Angular applications by composing HTML *templates* with Angularized-markup,
You write Angular applications by composing HTML *templates* with Angularized markup,
writing *component* classes to manage those templates, adding application logic in *services*,
and boxing components and services in *modules*.
Then we launch the app by *bootstrapping* the top _root module_.
Angular takes over, presenting our application content in a browser and
responding to user interactions according to the instructions we provided.
Then you launch the app by *bootstrapping* the _root module_.
Angular takes over, presenting your application content in a browser and
responding to user interactions according to the instructions you've provided.
Of course there is more to it than this.
We'll learn the details when we dive into the guide chapters.
Let's get the big picture first.
Of course, there is more to it than this.
You'll learn the details in the pages that follow. For now, focus on the big picture.
figure
img(src="/resources/images/devguide/architecture/overview2.png" alt="overview" style="margin-left:-40px;" width="700")
@ -30,19 +29,19 @@ figure
:marked
The architecture diagram identifies the eight main building blocks of an Angular 2 application:
1. [Modules](#modules)
1. [Components](#components)
1. [Templates](#templates)
1. [Metadata](#metadata)
1. [Data binding](#data-binding)
1. [Directives](#directives)
1. [Services](#services)
1. [Dependency injection](#dependency-injection)
* [Modules](#modules)
* [Components](#components)
* [Templates](#templates)
* [Metadata](#metadata)
* [Data binding](#data-binding)
* [Directives](#directives)
* [Services](#services)
* [Dependency injection](#dependency-injection)
Learn these, and we're on our way.
Learn these building blocks, and you're on your way.
.l-sub-section
p The code referenced in this chapter is available as a #[+liveExampleLink2()].
p The code referenced on this page is available as a #[+liveExampleLink2()].
.l-main-section
:marked
@ -50,18 +49,18 @@ figure
figure
img(src="/resources/images/devguide/architecture/module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
:marked
Angular apps are modular and Angular has its own modularity system called _Angular Modules_ or _NgModules_.
Angular apps are modular and Angular has its own modularity system called _Angular modules_ or _NgModules_.
_Angular Modules_ are a big deal.
We can only introduce them here; the [Angular Modules](ngmodule.html) chapter covers modules in depth.
_Angular modules_ are a big deal.
This page introduces modules; the [Angular modules](ngmodule.html) page covers them in depth.
<br clear="all"><br>
:marked
Every Angular app has at least one module, the _root module_, conventionally named `AppModule`.
While the _root_ module may be the only module in a small application, most apps have many more
_feature_ modules, each a cohesive block of code dedicated to an application domain,
a workflow, or a closely-related set of capabilities.
While the _root module_ may be the only module in a small application, most apps have many more
_feature modules_, each a cohesive block of code dedicated to an application domain,
a workflow, or a closely related set of capabilities.
An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator.
.l-sub-section
@ -73,18 +72,18 @@ figure
Learn more</a> about decorators on the web.
:marked
`NgModule` is a decorator function that takes a single metadata object whose properties describe the module.
The most important are
The most important properties are:
* `declarations` - the _view classes_ that belong to this module.
Angular has three kinds of view classes: [components](#components), [directives](#directives) and [pipes](pipes.html).
Angular has three kinds of view classes: [components](#components), [directives](#directives), and [pipes](pipes.html).
* `exports` - subset of declarations that should be visible and usable in the component [templates](#templates) of other modules.
* `exports` - the subset of declarations that should be visible and usable in the component [templates](#templates) of other modules.
* `imports` - other modules whose exported classes are needed by component templates declared in _this_ module.
* `providers` creators of [services](#services) that this module contributes to
* `providers` - creators of [services](#services) that this module contributes to
the global collection of services; they become accessible in all parts of the app.
* `bootstrap` - identifies the main application view, called the _root component_,
* `bootstrap` - the main application view, called the _root component_,
that hosts all other app views. Only the _root module_ should set this `bootstrap` property.
Here's a simple root module:
@ -92,21 +91,17 @@ figure
.l-sub-section
:marked
The `export` of `AppComponent` is just for show.
A root module has no reason to export anything because ... it's the root.
We don't expect other modules to import the root module.
But if one did, it could use the `AppComponent` in its component templates.
The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root module has no reason to _export_ anything because other components don't need to _import_ the root module.
:marked
We launch an application by _bootstrapping_ its root module.
During development we're likely to bootstrap the `AppModule` in a `main.ts` file like this one.
Launch an application by _bootstrapping_ its root module.
During development you're likely to bootstrap the `AppModule` in a `main.ts` file like this one.
+makeExample('app/main.ts', '', 'app/main.ts')(format='.')
:marked
### Angular Modules vs. JavaScript Modules
### Angular modules vs. JavaScript modules
The Angular module &mdash; a class decorated with `@NgModule` &mdash; is a fundamental feature of Angular itself.
The Angular module &mdash; a class decorated with `@NgModule` &mdash; is a fundamental feature of Angular.
JavaScript also has its own module system for managing collections of JavaScript objects.
It's completely different and unrelated to the Angular module system.
@ -122,39 +117,38 @@ figure
:marked
<a href="http://exploringjs.com/es6/ch_modules.html" target="_blank">Learn more about the JavaScript module system on the web.</a>
:marked
These are two different and _complementary_ module systems. We use them both to write our apps.
These are two different and _complementary_ module systems. Use them both to write your apps.
### Angular Libraries
### Angular libraries
figure
img(src="/resources/images/devguide/architecture/library-module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
:marked
Angular itself ships as a collection of JavaScript modules. We can think of them as library modules.
Angular ships as a collection of JavaScript modules. You can think of them as library modules.
Each Angular library name begin with the `!{_at_angular}` prefix.
Each Angular library name begins with the `!{_at_angular}` prefix.
We install them with the **npm** package manager and import parts of them with JavaScript `import` statements.
You install them with the **npm** package manager and import parts of them with JavaScript `import` statements.
<br clear="all"><br>
:marked
For example, we import Angular's `Component` decorator from the `@angular/core` library like this:
For example, import Angular's `Component` decorator from the `@angular/core` library like this:
+makeExample('app/app.component.ts', 'import', '')(format='.')
:marked
We also import Angular _modules_ from Angular _libraries_ using JavaScript import statements:
You also import Angular _modules_ from Angular _libraries_ using JavaScript import statements:
+makeExample('app/mini-app.ts', 'import-browser-module', '')(format='.')
:marked
Our application module needs material from within that `BrowserModule`
so we add it to the `@NgModule` metadata `imports` like this.
In the example of the simple root module above, the application module needs material from within that `BrowserModule`. To access that material, add it to the `@NgModule` metadata `imports` like this.
+makeExample('app/mini-app.ts', 'ngmodule-imports', '')(format='.')
:marked
We're using both the Angular and JavaScript module systems _together_.
In this way you're using both the Angular and JavaScript module systems _together_.
It's easy to confuse the two systems because they share the common vocabulary of "imports" and "exports".
Hang in there. The confusion will yield to clarity with time and experience.
Hang in there. The confusion yields to clarity with time and experience.
.l-sub-section
:marked
Learn more in the [Angular Modules](ngmodule.html) chapter.
Learn more from the [Angular modules](ngmodule.html) page.
.l-hr
@ -165,28 +159,27 @@ figure
img(src="/resources/images/devguide/architecture/hero-component.png" alt="Component" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
:marked
A **component** controls a patch of screen real estate that we could call a *view*.
The shell at the application root with navigation links, a list of heroes, a hero editor ...
they're all views controlled by components.
A _component_ controls a patch of screen called a *view*.
We define a component's application logic &mdash; what it does to support the view &mdash; inside a class.
For example, the following views are controlled by components:
* The app root with the navigation links.
* The list of heroes.
* The hero editor.
You define a component's application logic&mdash;what it does to support the view&mdash;inside a class.
The class interacts with the view through an API of properties and methods.
<a id="component-code"></a>
A `HeroListComponent`, for example, might have a `heroes` property that returns !{_an} !{_array} of heroes
that it acquired from a service.
It might have a `selectHero()` method that sets a `selectedHero` property when the user clicks to choose a hero from that list.
The component might be a class like this:
For example, this `HeroListComponent` has a `heroes` property that returns !{_an} !{_array} of heroes
that it acquires from a service.
`HeroListComponent` also has a `selectHero()` method that sets a `selectedHero` property when the user clicks to choose a hero from that list.
+makeExcerpt('app/hero-list.component.ts', 'class')
:marked
Angular creates, updates, and destroys components as the user moves through the application.
The developer can take action at each moment in this lifecycle through optional [lifecycle hooks](lifecycle-hooks.html), like `ngOnInit()` declared above.
.l-sub-section
:marked
We may wonder who is calling the component's constructor? Who provides the service parameter?
For the moment, have faith that Angular will call the constructor and deliver an
appropriate `HeroService` when we need it.
Your app can take action at each moment in this lifecycle through optional [lifecycle hooks](lifecycle-hooks.html), like `ngOnInit()` declared above.
.l-hr
@ -196,26 +189,21 @@ figure
figure
img(src="/resources/images/devguide/architecture/template.png" alt="Template" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
:marked
We define a component's view with its companion **template**. A template is a form of HTML
You define a component's view with its companion **template**. A template is a form of HTML
that tells Angular how to render the component.
A template looks like regular HTML much of the time ... and then it gets a bit strange. Here is a
A template looks like regular HTML, except for a few differences. Here is a
template for our `HeroListComponent`:
+makeExample('app/hero-list.component.html')
:marked
This template features typical HTML elements like `<h2>` and `<p>`.
But what are `*ngFor`, `{{hero.name}}`, `(click)`, `[hero]`, and `<hero-detail>`?
Although this template uses typical HTML elements like `<h2>` and `<p>`, it also has some differences. Code like `*ngFor`, `{{hero.name}}`, `(click)`, `[hero]`, and `<hero-detail>` uses Angular's [template syntax](template-syntax.html).
These are examples of Angular's [template syntax](template-syntax.html).
We will grow accustomed to that syntax and may even learn to love it.
We'll begin to explain it in a moment.
Before we do, focus attention on the last line.
The `<hero-detail>` tag is a custom element representing the `HeroDetailComponent`.
The `HeroDetailComponent` is a *different* component than the `HeroListComponent` we've been reviewing.
In the last line of the template, the `<hero-detail>` tag is a custom element that represents a new component, `HeroDetailComponent`.
The `HeroDetailComponent` is a *different* component than the `HeroListComponent` you've been reviewing.
The `HeroDetailComponent` (code not shown) presents facts about a particular hero, the
hero that the user selects from the list presented by the `HeroListComponent`.
The `HeroDetailComponent` is a **child** of the `HeroListComponent`.
@ -223,10 +211,8 @@ figure
figure
img(src="/resources/images/devguide/architecture/component-tree.png" alt="Metadata" align="left" style="width:300px; margin-left:-40px;margin-right:10px" )
:marked
Notice how `<hero-detail>` rests comfortably among native HTML elements.
We can and _will_ mix our custom components with native HTML in the same layouts.
Notice how `<hero-detail>` rests comfortably among native HTML elements. Custom components mix seamlessly with native HTML in the same layouts.
In this manner we'll compose complex component trees to build out our richly featured application.
<br clear="all">
.l-hr
@ -241,20 +227,20 @@ figure
<p style="padding-top:10px">Metadata tells Angular how to process a class.</p>
<br clear="all">
:marked
[Looking back at the code](#component-code) for `HeroListComponent`, we see that it's just a class.
[Looking back at the code](#component-code) for `HeroListComponent`, you can see that it's just a class.
There is no evidence of a framework, no "Angular" in it at all.
In fact, it really is *just a class*. It's not a component until we *tell Angular about it*.
In fact, `HeroListComponent` really is *just a class*. It's not a component until you *tell Angular about it*.
We tell Angular that `HeroListComponent` is a component by attaching **metadata** to the class.
To tell Angular that `HeroListComponent` is a component, attach **metadata** to the class.
In !{_Lang}, we attach metadata by using !{_a} **!{_decorator}**.
In !{_Lang}, you attach metadata by using !{_a} **!{_decorator}**.
Here's some metadata for `HeroListComponent`:
+makeExcerpt('app/hero-list.component.ts', 'metadata')
:marked
Here we see the `@Component` !{_decorator} which (no surprise) identifies the class
Here is the `@Component` !{_decorator}, which identifies the class
immediately below it as a component class.
block ts-decorator
@ -270,32 +256,30 @@ block ts-decorator
For example, if an app's HTML contains `<hero-list></hero-list>`, then
Angular inserts an instance of the `HeroListComponent` view between those tags.
- `templateUrl`: address of this component's template, which we showed [above](#templates).
- `templateUrl`: address of this component's HTML template, shown [above](#templates).
- `directives`: !{_array} of the components or directives that *this* template requires.
We saw in the last line of our template that we expect Angular to insert a `HeroDetailComponent`
In the last line of `hero-list.component.html`, Angular inserts a `HeroDetailComponent`
in the space indicated by `<hero-detail>` tags.
Angular will do so only if we mention the `HeroDetailComponent` in this `directives` !{_array}.
Angular does so only if `HeroDetailComponent` is in this `directives` !{_array}.
- `providers`: !{_array} of **dependency injection providers** for services that the component requires.
This is one way to tell Angular that our component's constructor requires a `HeroService`
so it can get the list of heroes to display. We'll get to dependency injection later.
This is one way to tell Angular that the component's constructor requires a `HeroService`
so it can get the list of heroes to display.
figure
img(src="/resources/images/devguide/architecture/template-metadata-component.png" alt="Metadata" align="left" style="height:200px; margin-left:-40px;margin-right:10px" )
:marked
Angular reads the metadata specified by the `@Component`
annotation. That's how Angular learns to do "the right thing".
The metadata in the `@Component` tells Angular where to get the major building blocks you specify for the component.
The template, metadata, and component together describe a view.
We apply other metadata !{_decorator}s in a similar fashion to guide Angular behavior.
`@Injectable`, `@Input`, and `@Output` are a few of the more popular !{_decorator}s
we'll master as our Angular knowledge grows.
Apply other metadata !{_decorator}s in a similar fashion to guide Angular behavior.
`@Injectable`, `@Input`, and `@Output` are a few of the more popular !{_decorator}s.
<br clear="all">
:marked
The architectural takeaway is that we must add metadata to our code
The architectural takeaway is that you must add metadata to your code
so that Angular knows what to do.
.l-hr
@ -303,7 +287,7 @@ figure
.l-main-section
:marked
## Data binding
Without a framework, we would be responsible for pushing data values into the HTML controls and turning user responses
Without a framework, you would be responsible for pushing data values into the HTML controls and turning user responses
into actions and value updates. Writing such push/pull logic by hand is tedious, error-prone, and a nightmare to
read as any experienced jQuery programmer can attest.
figure
@ -311,13 +295,12 @@ figure
:marked
Angular supports **data binding**,
a mechanism for coordinating parts of a template with parts of a component.
We add binding markup to the template HTML to tell Angular how to connect both sides.
Add binding markup to the template HTML to tell Angular how to connect both sides.
There are four forms of data binding syntax. Each form has a direction &mdash; to the DOM, from the DOM, or in both directions &mdash;
as indicated by the arrows in the diagram.
As the diagram shows, there are four forms of data binding syntax. Each form has a direction &mdash; to the DOM, from the DOM, or in both directions.
<br clear="all">
:marked
We saw three forms of data binding in our [example](#templates) template:
The `HeroListComponent` [example](#templates) template has three forms:
+makeExcerpt('app/hero-list.component.1.html', 'binding')
@ -332,8 +315,7 @@ figure
**Two-way data binding** is an important fourth form
that combines property and event binding in a single notation, using the `ngModel` directive.
We didn't have a two-way binding in the `HeroListComponent` template;
here's an example from the `HeroDetailComponent` template:
Here's an example from the `HeroDetailComponent` template:
+makeExcerpt('app/hero-detail.component.html', 'ngModel')
@ -343,13 +325,12 @@ figure
as with event binding.
Angular processes *all* data bindings once per JavaScript event cycle,
from the root of the application component tree down to the leaves.
from the root of the application component tree through all child components.
figure
img(src="/resources/images/devguide/architecture/component-databinding.png" alt="Data Binding" style="float:left; width:300px; margin-left:-40px;margin-right:10px" )
:marked
We don't know all the details yet,
but it's clear from these examples that data binding plays an important role in communication
Data binding plays an important role in communication
between a template and its component.
<br clear="all">
figure
@ -369,18 +350,17 @@ figure
Angular templates are *dynamic*. When Angular renders them, it transforms the DOM
according to the instructions given by **directives**.
A directive is a class with directive metadata. In !{_Lang} we apply the `@Directive` !{_decorator}
A directive is a class with directive metadata. In !{_Lang}, apply the `@Directive` !{_decorator}
to attach metadata to the class.
<br clear="all">
:marked
We already met one form of directive: the component. A component is a *directive-with-a-template*;
A component is a *directive-with-a-template*;
a `@Component` !{_decorator} is actually a `@Directive` !{_decorator} extended with template-oriented features.
.l-sub-section
:marked
While **a component is technically a directive**,
components are so distinctive and central to Angular applications that we chose
to separate components from directives in this architectural overview.
components are so distinctive and central to Angular applications that this architectural overview separates components from directives.
:marked
Two *other* kinds of directives exist: _structural_ and _attribute_ directives.
@ -389,7 +369,7 @@ figure
**Structural** directives alter layout by adding, removing, and replacing elements in DOM.
Our [example](#templates) template uses two built-in structural directives:
The [example template](#templates) uses two built-in structural directives:
+makeExcerpt('app/hero-list.component.1.html', 'structural')
@ -411,12 +391,12 @@ block dart-bool
+makeExcerpt('app/hero-detail.component.html', 'ngModel')
:marked
Angular ships with a small number of other directives that either alter the layout structure
Angular has a few more directives that either alter the layout structure
(for example, [ngSwitch](template-syntax.html#ngSwitch))
or modify aspects of DOM elements and components
(for example, [ngStyle](template-syntax.html#ngStyle) and [ngClass](template-syntax.html#ngClass)).
Of course, we can also write our own directives. Components such as
Of course, you can also write your own directives. Components such as
`HeroListComponent` are one kind of custom directive.
<!-- PENDING: link to where to learn more about other kinds! -->
@ -428,7 +408,7 @@ block dart-bool
figure
img(src="/resources/images/devguide/architecture/service.png" alt="Service" style="float:left; margin-left:-40px;margin-right:10px" )
:marked
_Service_ is a broad category encompassing any value, function, or feature that our application needs.
_Service_ is a broad category encompassing any value, function, or feature that your application needs.
Almost anything can be a service.
A service is typically a class with a narrow, well-defined purpose. It should do something specific and do it well.
@ -441,12 +421,12 @@ figure
* tax calculator
* application configuration
There is nothing specifically _Angular_ about services. Angular itself has no definition of a service.
There is nothing specifically _Angular_ about services. Angular has no definition of a service.
There is no service base class, and no place to register a service.
Yet services are fundamental to any Angular application. Our components are big consumers of services.
Yet services are fundamental to any Angular application. Components are big consumers of services.
Here's an example of a service class that logs to the browser console
Here's an example of a service class that logs to the browser console:
+makeExcerpt('app/logger.service.ts', 'class')
@ -459,8 +439,8 @@ figure
:marked
Services are everywhere.
We prefer our component classes lean. Our components don't fetch data from the server,
they don't validate user input, and they don't log directly to the console.
Component classes should be lean. They don't fetch data from the server,
validate user input, or log directly to the console.
They delegate such tasks to services.
A component's job is to enable the user experience and nothing more. It mediates between the view (rendered by the template)
@ -469,9 +449,9 @@ figure
It delegates everything nontrivial to services.
Angular doesn't *enforce* these principles.
It won't complain if we write a "kitchen sink" component with 3000 lines.
It won't complain if you write a "kitchen sink" component with 3000 lines.
Angular does help us *follow* these principles by making it easy to factor our
Angular does help you *follow* these principles by making it easy to factor your
application logic into services and make those services available to components through *dependency injection*.
.l-hr
@ -488,7 +468,7 @@ figure
<br clear="all">
:marked
Angular can tell which services a component needs by looking at the types of its constructor parameters.
For example, the constructor of our `HeroListComponent` needs a `HeroService`:
For example, the constructor of your `HeroListComponent` needs a `HeroService`:
+makeExcerpt('app/hero-list.component.ts (constructor)', 'ctor')
@ -501,7 +481,7 @@ figure
before returning the service to Angular.
When all requested services have been resolved and returned,
Angular can call the component's constructor with those services as arguments.
This is what we mean by *dependency injection*.
This is *dependency injection*.
The process of `HeroService` injection looks a bit like this:
figure
@ -509,27 +489,27 @@ figure
:marked
If the injector doesn't have a `HeroService`, how does it know how to make one?
In brief, we must have previously registered a **provider** of the `HeroService` with the injector.
In brief, you must have previously registered a **provider** of the `HeroService` with the injector.
A provider is something that can create or return a service, typically the service class itself.
We can register providers in modules or in components.
You can register providers in modules or in components.
We often add providers to the [root module](#module) so that
In general, add providers to the [root module](#module) so that
the same instance of a service is available everywhere.
+makeExample('app/app.module.ts', 'providers', 'app/app.module.ts (module providers)')(format='.')
:marked
Alternatively, we might register at a component level in the `providers` property of the `@Component` metadata:
Alternatively, register at a component level in the `providers` property of the `@Component` metadata:
+makeExample('app/hero-list.component.ts', 'providers', 'app/hero-list.component.ts (component providers)')(format='.')
:marked
Registering at a component level means we get a new instance of the
Registering at a component level means you get a new instance of the
service with each new instance of that component.
<!-- We've vastly oversimplified dependency injection for this overview.
The full story is in the [Dependency Injection](dependency-injection.html) chapter. -->
The full story is in the [dependency injection](dependency-injection.html) page. -->
Points to remember about dependency injection:
@ -541,7 +521,7 @@ figure
* A *provider* is a recipe for creating a service.
* We register *providers* with injectors.
* Register *providers* with injectors.
.l-hr
@ -549,44 +529,41 @@ figure
:marked
## Wrap up
We've learned just a bit about the eight main building blocks of an Angular application:
You've learned the basics about the eight main building blocks of an Angular application:
1. [Modules](#modules)
1. [Components](#components)
1. [Templates](#templates)
1. [Metadata](#metadata)
1. [Data binding](#data-binding)
1. [Directives](#directives)
1. [Services](#services)
1. [Dependency injection](#dependency-injection)
* [Modules](#modules)
* [Components](#components)
* [Templates](#templates)
* [Metadata](#metadata)
* [Data binding](#data-binding)
* [Directives](#directives)
* [Services](#services)
* [Dependency injection](#dependency-injection)
That's a foundation for everything else in an Angular application,
and it's more than enough to get going.
But it doesn't include everything we'll need or want to know.
But it doesn't include everything you need to know.
Here is a brief, alphabetical list of other important Angular features and services.
Most of them are covered in this Developers Guide (or soon will be).
Most of them are covered in this documentation (or soon will be).
> [**Animations**](animations.html): The animation library makes it easy for developers to animate component behavior
without deep knowledge of animation techniques or CSS.
> [**Animations**](animations.html): Animate component behavior
without deep knowledge of animation techniques or CSS with Angular's animation library.
> **Change detection**: Learn how Angular decides that a component property value has changed and
when to update the screen.
Learn how it uses **zones** to intercept asynchronous activity and run its change detection strategies.
> **Change detection**: The change detection documentation will cover how Angular decides that a component property value has changed,
when to update the screen, and how it uses **zones** to intercept asynchronous activity and run its change detection strategies.
> **Events**: The DOM raises events. So can components and services. Angular offers mechanisms for
> **Events**: The events documentation will cover how to use components and services to raise events with mechanisms for
publishing and subscribing to events.
> [**Forms**](forms.html): Support complex data entry scenarios with HTML-based validation and dirty checking.
> [**HTTP**](server-communication.html): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client.
> [**Lifecycle hooks**](lifecycle-hooks.html): We can tap into key moments in the lifetime of a component, from its creation to its destruction,
> [**Lifecycle hooks**](lifecycle-hooks.html): Tap into key moments in the lifetime of a component, from its creation to its destruction,
by implementing the lifecycle hook interfaces.
> [**Pipes**](pipes.html): Services that transform values for display.
We can put pipes in our templates to improve the user experience. Consider
this `currency` pipe expression:
> [**Pipes**](pipes.html): Use pipes in your templates to improve the user experience by transforming values for display. Consider this `currency` pipe expression:
<div style="margin-left:40px">
code-example().
price | currency:'USD':true
@ -597,6 +574,6 @@ code-example().
> [**Router**](router.html): Navigate from page to page within the client
application and never leave the browser.
> [**Testing**](testing.html): Angular provides a
> [**Testing**](testing.html): Run unit tests with Angular's
[testing library](https://pub.dartlang.org/packages/angular2_testing)
to run unit tests on our application parts as they interact with the Angular framework.
on your application parts as they interact with the Angular framework.

57
public/docs/ts/latest/guide/index.jade
View File

@ -9,8 +9,6 @@ figure
This is a practical guide to Angular for experienced programmers who
are building client applications in HTML and #{langName}.
We are on a journey together to understand how Angular works and, more importantly,
how to make it work for us. This overview begins the journey.
<br clear="all">
// #enddocregion intro
@ -20,7 +18,7 @@ figure
# Organization
The documentation is divided into major thematic sections, each
a collection of chapters devoted to that theme.
a collection of pages devoted to that theme.
// #enddocregion how-to-read-1
// #docregion how-to-read-2
- var top="vertical-align:top"
@ -31,7 +29,7 @@ table(width="100%")
td <b>QuickStart</b>
td
:marked
The foundation for every chapter and sample in this documentation.
The foundation for every page and sample in this documentation.
tr(style=top)
td <b>Tutorial</b>
td
@ -60,55 +58,50 @@ table(width="100%")
Authoritative details about each member of the Angular libraries.
:marked
# Learning path
We don't have to read the guide straight through. Most chapters stand on their own.
You don't have to read the guide straight through. Most pages stand on their own.
We recommend a learning path for those new to Angular.
Most of that path runs through the *Basics* section:
For those new to Angular, the recommended learning path runs through the *Basics* section:
1. Read the [Architecture](architecture.html) overview to get the big picture.
1. For the big picture, read the [Architecture](architecture.html) overview.
1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2.
It shows us how to set up the libraries and tools we'll need to write *any* Angular app.
1. Try [QuickStart](../quickstart.html). QuickStart is the "Hello, World" of Angular 2.
It shows you how to set up the libraries and tools you'll need to write *any* Angular app.
1. Take the *Tour of Heroes* [Tutorial](../tutorial), which picks up from where the QuickStart leaves off
and builds a simple data-driven app.
Simple, yes, but with the essential characteristics we'd expect of a professional application:
1. Take the *Tour of Heroes* [tutorial](../tutorial), which picks up where QuickStart leaves off,
and builds a simple data-driven app. The app demonstrates the essential characteristics of a professional application:
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
Return to the *Basics* section and continue in the suggested order:
1. [Displaying Data](displaying-data.html) explains how to display information on the screen.
1. [Displaying Data](displaying-data.html) explains how to get information on to the screen.
1. [User Input](user-input.html) covers how Angular responds to user behavior.
1. [User Input](user-input.html) covers the basics of responding to user behavior.
1. [Forms](forms.html) handles user data entry and validation within the UI.
1. [Forms](forms.html) handle user data entry and validation within the UI.
1. [Dependency Injection](dependency-injection.html) is the way we build large, maintainable applications
1. [Dependency Injection](dependency-injection.html) is the way to build large, maintainable applications
from small, single-purpose parts.
1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
With this foundation, we can read and understand any chapter in the guide.
After reading the above sections, you can skip to any other pages on this site.
// #enddocregion how-to-read-2
// #docregion the-rest
:marked
# Code samples
Every chapter includes code snippets that we can reuse in our own applications.
These snippets are excerpts from a sample application that accompanies the chapter.
Each page includes code snippets that you can reuse in your applications.
These snippets are excerpts from a sample application that accompanies the page.
block example-links
:marked
Look for a link to a running version of that sample near the top of each page,
such as this <live-example name="architecture"></live-example> from the [Architecture](architecture.html) chapter.
such as this <live-example name="architecture"></live-example> from the [Architecture](architecture.html) page.
The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
The link launches a browser-based code editor where you can inspect, modify, save, and download the code.
:marked
A few early chapters are written as tutorials and are clearly marked as such.
Most chapters are *not* tutorials.
They highlight key points in code rather than explain each step necessary to build the sample.
We can always get the full source by way of the #{_liveLink}.
A few early pages are written as tutorials and are clearly marked as such.
The rest of the pages highlight key points in code rather than explain each step necessary to build the sample.
You can always get the full source through the #{_liveLink}.
# Reference pages
@ -120,10 +113,10 @@ block example-links
# Feedback
We welcome feedback! Leave a comment by clicking the icon in upper right corner of the banner.
We welcome feedback!
Post *documentation* issues and pull requests on the
[angular.io](https://github.com/angular/angular.io) github repository.
Use the [angular.io Github repo](https://github.com/angular/angular.io) for **documentation** issues and pull requests.
Post issues with *Angular 2 itself* to the [angular](https://github.com/angular/angular) github repository.
Use the [Angular Github repo](https://github.com/angular/angular) to report issues with **Angular 2** itself.
// #enddocregion the-rest

22
public/docs/ts/latest/guide/ngmodule.jade
View File

@ -14,7 +14,7 @@ block includes
It may add service providers to the application dependency injectors.
And there are more options covered here.
This chapter explains how to **create** `NgModule` classes and how to load them,
This page explains how to **create** `NgModule` classes and how to load them,
either immediately when the application launches or later, as needed, via the [Router](router.html).
## Contents
@ -34,7 +34,7 @@ block includes
* [NgModule metadata properties](#ngmodule-properties "A technical summary of the @NgModule metadata properties")
### Live examples
This chapter explains Angular Modules through a progression of improvements to a sample with a "Tour of Heroes" theme.
This page explains Angular Modules through a progression of improvements to a sample with a "Tour of Heroes" theme.
Here's an index to live examples at key moments in the evolution of that sample:
* <live-example plnkr="minimal.0">A minimal NgModule app</live-example>
@ -45,11 +45,11 @@ block includes
### Frequently Asked Questions (FAQs)
This chapter covers Angular Module concepts in a tutorial fashion.
This page covers Angular Module concepts in a tutorial fashion.
The companion [Angular Module FAQs](../cookbook/ngmodule-faq.html "Angular Module FAQs") cookbook
offers ready answers to specific design and implementation questions.
Read this chapter first before hopping over to those FAQs.
Read this page first before hopping over to those FAQs.
.l-hr
@ -92,7 +92,7 @@ a#angular-modularity
that represent collections of related functionality.
We then import these modules into the _root module_.
We'll see how later in the chapter. Let's start with the _root module_.
We'll see how later in the page. Let's start with the _root module_.
a#root_module
.l-main-section
@ -131,7 +131,7 @@ a#bootstrap
We launch the application by bootstrapping the `AppModule` in the `main.ts` file.
Angular offers a variety of bootstrapping options, targeting multiple platforms.
In this chapter we consider two options, both targeting the browser.
In this page we consider two options, both targeting the browser.
### Dynamic bootstrapping with the Just-In-Time (JIT) compiler
In the first, _dynamic_ option, the [Angular compiler](../cookbook/ngmodule-faq.html#q-angular-compiler "About the Angular Compiler")
@ -139,7 +139,7 @@ a#bootstrap
+makeExample('ngmodule/ts/app/main.ts', '', 'app/main.ts (dynamic)')(format=".")
:marked
The samples in this chapter demonstrate the dynamic bootstrapping approach.
The samples in this page demonstrate the dynamic bootstrapping approach.
<live-example embedded plnkr="minimal.0" img="devguide/ngmodule/minimal-plunker.png">Try the live example.</live-example>
@ -219,7 +219,7 @@ a#providers
Modules are a great way to provide services for all of the module's components.
The [Dependency Injection](dependency-injection.html) chapter describes
The [Dependency Injection](dependency-injection.html) page describes
the Angular hierarchical dependency injection system and how to configure that system
with [providers](dependency-injection.html#providers) at different levels of the
application's component tree.
@ -668,7 +668,7 @@ a#lazy-load
### App routing
+makeExample('ngmodule/ts/app/app.routing.ts', '', 'app/app.routing.ts')(format='.')
:marked
The router is the subject of [its own chapter](router.html) so we'll skip lightly over the details and
The router is the subject of [its own page](router.html) so we'll skip lightly over the details and
concentrate on the intersection of Angular modules and routing.
This file defines three routes.
@ -768,7 +768,7 @@ a#hero-module
.file hero.service.ts
.file highlight.directive.ts
:marked
This is the child routing scenario familiar to readers of [Router](router.html#child-routing-component) chapter.
This is the child routing scenario familiar to readers of the [Router](router.html#child-routing-component) page.
The `HeroComponent` is the feature's top component and routing host.
Its template has a `<router-outlet>` that displays either a list of heroes (`HeroList`)
or an editor of a selected hero (`HeroDetail`).
@ -880,7 +880,7 @@ a#core-module
.l-sub-section
:marked
We're importing some extra symbols from the Angular core library that we're not using yet.
They'll become relevant later in this chapter.
They'll become relevant later in this page.
:marked
The `@NgModule` metadata should be familiar.
We declare the `TitleComponent` because this module _owns_ it and we export it

154
public/docs/ts/latest/guide/npm-packages.jade
View File

@ -1,20 +1,20 @@
include ../_util-fns
:marked
Angular applications and Angular itself depend upon features and functionality provided by a variety of third-party packages (including Angular itself).
Angular applications and Angular itself depend upon features and functionality provided by a variety of third-party packages.
These packages are maintained and installed with the Node Package Manager (<a href="https://docs.npmjs.com/" target="_blank">npm</a>).
.l-sub-section
:marked
Node.js and npm are essential to Angular 2 development.
<a href="https://docs.npmjs.com/getting-started/installing-node" target="_blank" title="Installing Node.js and updating npm">
Get it now</a> if it's not already installed on your machine.
Get them now</a> if they're not already installed on your machine.
**Verify that you are running at least node `v4.x.x` and npm `3.x.x`**
by running `node -v` and `npm -v` in a terminal/console window.
**Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher**
by running the commands `node -v` and `npm -v` in a terminal/console window.
Older versions produce errors.
We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm.
We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm. You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that use other versions of node and npm.
:marked
We recommend a comprehensive starter-set of packages as specified in the `dependencies` and `devDependencies`
@ -22,30 +22,27 @@ include ../_util-fns
<a href="https://docs.npmjs.com/files/package.json" target="_blank">package.json</a> file:
+makeJson('quickstart/ts/package.1.json',{ paths: 'dependencies, devDependencies'}, 'package.json (dependencies)')(format=".")
:marked
There are other possible package choices and you're likely to add and subtract to meet your application needs.
We're recommending *this particular set* because (a) we know they work well together and
(b) they include everything we'll need to build and run the sample applications in this documentation series.
You can use other packages but we recommend *this particular set* to start with because (a) they work well together and
(b) they include everything you'll need to build and run the sample applications in this series.
.l-sub-section
:marked
*Almost* everything. A cookbook or guide chapter may require an additional library such as *jQuery*.
Note: A cookbook or guide page may require an additional library such as *jQuery*.
:marked
This is far more than we need for QuickStart.
Indeed, it's more than we need for most applications.
There is no harm in installing more than we need.
We only serve to the client those packages that the application actually requests.
You'll install more than you need for QuickStart.
No worries!
You only serve to the client those packages that the application actually requests.
In this chapter we explain what each package does and why we include it.
Feel free to make substitutions later to suit your tastes and experience.
This page explains what each package does. You can make substitutions later to suit your tastes and experience.
.l-main-section
:marked
## *dependencies* and *devDependencies*
The `package.json` distinguishes between two sets of packages,
The `package.json` includes two sets of packages,
[dependencies](#dependencies) and [devDependencies](#dev-dependencies).
The packages listed under *dependencies* are essential to *running* the application.
The *dependencies* are essential to *running* the application.
The *devDependencies* are only necessary to *develop* the application.
They can be excluded from production installations as in this example:
You can exclude them from production installations by adding `--production` to the install command, as follows:
code-example(format="." language="bash").
npm install my-application --production
@ -53,9 +50,9 @@ a(id="dependencies")
.l-main-section
:marked
## *dependencies*
There are three package categories in the `dependencies` section of the application `package.json`:
The `dependencies` section of `package.json` contains:
* ***Features*** - Feature packages provide our application with framework and utility capabilities.
* ***Features*** - Feature packages give the application framework and utility capabilities.
* ***Polyfills*** - Polyfills plug gaps in the browser's JavaScript implementation.
@ -68,19 +65,18 @@ a(id="dependencies")
***@angular/core*** - Critical runtime parts of the framework needed by every application.
Includes all metadata decorators, `Component`, `Directive`, dependency injection, and the component lifecycle hooks.
***@angular/common*** - The commonly needed services, pipes and directives provided by the Angular team.
***@angular/common*** - The commonly needed services, pipes, and directives provided by the Angular team.
***@angular/compiler*** - Angular's *Template Compiler*.
It understand templates and can convert them to code that makes the app run and render.
Developers typically don’t interact with the compiler directly.
They use it indirectly via `platform-browser-dynamic` or the offline template compiler.
It understands templates and can convert them to code that makes the application run and render.
Typically you don’t interact with the compiler directly; rather, you use it indirectly via `platform-browser-dynamic` or the offline template compiler.
***@angular/platform-browser*** - Everything DOM and browser related, especially the pieces that help render into DOM.
This package also includes the bootstrapStatic method for bootstrapping applications for production builds that pre-compile templates offline.
***@angular/platform-browser-dynamic*** - Providers and a bootstrap method for applications that
***@angular/platform-browser-dynamic*** - Includes [Providers](https://angular.io/docs/ts/latest/api/core/index/Provider-type-alias.html) and a [bootstrap](https://angular.io/docs/ts/latest/guide/ngmodule.html#!#bootstrap) method for applications that
compile templates on the client. Don’t use offline compilation.
We use this package for boostrapping during development and for boostrapping plunker samples.
Use this package for bootstrapping during development and for bootstrapping plunker samples.
***@angular/http*** - Angular's http client.
@ -90,43 +86,42 @@ a(id="dependencies")
***[system.js](https://github.com/systemjs/systemjs)*** - A dynamic module loader compatible with the
[ES2015 module](http://www.2ality.com/2014/09/es6-modules-final.html) specification.
There are other viable choices including the well-regarded [webpack](https://webpack.github.io/).
SystemJS happens to be the one we use in the documentation samples. It works.
Other viable choices include the well-regarded [webpack](https://webpack.github.io/).
Our applications are likely to require additional packages that provide
Your future applications are likely to require additional packages that provide
HTML controls, themes, data access, and various utilities.
a(id="polyfills")
.l-main-section
:marked
### Polyfill Packages
### Polyfill packages
Angular requires certain [polyfills](https://en.wikipedia.org/wiki/Polyfill) in the application environment.
We install these polyfills with very specific npm packages that Angular lists in the *peerDependencies* section of its `package.json`.
Install these polyfills using the npm packages that Angular lists in the *peerDependencies* section of its `package.json`.
We must list these packages in the `dependencies` section of our own `package.json`.
You must list these packages in the `dependencies` section of your own `package.json`.
.l-sub-section
:marked
See "[Why peerDependencies?](#why-peer-dependencies)" below for background on this requirement.
For background on this requirement, see [Why peerDependencies?](#why-peer-dependencies).
:marked
***core-js*** - Monkey patches the global context (window) with essential features of ES2015 (ES6).
Developers may substitute an alternative polyfill that provides the same core APIs.
This dependency should go away once these APIs are implemented by all supported ever-green browsers.
***core-js*** - Patches the global context (window) with essential features of ES2015 (ES6).
You may substitute an alternative polyfill that provides the same core APIs.
When these APIs are implemented by the major browsers, this dependency will become unnecessary.
***reflect-metadata*** - A dependency shared between Angular and the ***TypeScript compiler***.
Developers should be able to update a TypeScript package without upgrading Angular,
You can update a TypeScript package without upgrading Angular,
which is why this is a dependency of the application and not a dependency of Angular.
***rxjs*** - A polyfill for the [Observables specification](https://github.com/zenparsing/es-observable) currently before the
[TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language.
Developers should be able to pick a preferred version of *rxjs* (within a compatible version range)
You can pick a preferred version of *rxjs* (within a compatible version range)
without waiting for Angular updates.
***zone.js*** - A polyfill for the [Zone specification](https://gist.github.com/mhevery/63fdcdf7c65886051d55) currently before the
[TC39](http://www.ecma-international.org/memento/TC39.htm) committee that determines standards for the JavaScript language.
Developers should be able to pick a preferred version of *zone.js* to use (within a compatible version range)
You can pick a preferred version of *zone.js* to use (within a compatible version range)
without waiting for Angular updates.
a(id="other")
@ -136,99 +131,94 @@ a(id="other")
***angular2-in-memory-web-api*** - An Angular-supported library that simulates a remote server's web api
without requiring an actual server or real http calls.
Good for demos, documentation samples, and early stage development (before we even have a server).
Learn about it in the [Http Client](server-communication.html#appendix-tour-of-heroes-in-memory-server) chapter.
Good for demos, samples, and early stage development (before we even have a server).
Read about it in the [Http Client](server-communication.html#appendix-tour-of-heroes-in-memory-server) page.
***bootstrap*** - [Bootstrap](http://getbootstrap.com/) is a popular HTML and CSS framework for designing responsive web apps.
Some of the documentation samples improve their appearance with *bootstrap*.
Some of the samples improve their appearance with *bootstrap*.
a(id="dev-dependencies")
.l-main-section
:marked
## *devDependencies*
The packages listed in the *devDependencies* section of the `package.json` help us develop the application.
They do not have to be deployed with the production application although there is rarely harm in doing so.
The packages listed in the *devDependencies* section of the `package.json` help you develop the application.
You don't have to deploy them with the production application although there is no harm in doing so.
***[concurrently](https://www.npmjs.com/package/concurrently)*** -
A utility to run multiple *npm* commands concurrently on OS/X, Windows, and Linux operating systems.
***[lite-server](https://www.npmjs.com/package/lite-server)*** -
A light-weight, static file server, written and maintained by [John Papa](http://johnpapa.net/)
A light-weight, static file server, by [John Papa](http://johnpapa.net/)
with excellent support for Angular apps that use routing.
***[typescript](https://www.npmjs.com/package/typescript)*** -
The TypeScript language server including the *tsc* TypeScript compiler.
The TypeScript language server, including the *tsc* TypeScript compiler.
***[typings](https://www.npmjs.com/package/typings)*** - A manager for TypeScript definition files.
Learn more about it in the [TypeScript Configuration](typescript-configuration.html#typings) chapter.
This section likely grows as we add more tools, testing, and build support.
The QuickStart set is sufficient for developing the documentation sample applications.
Read more about it in the [TypeScript Configuration](typescript-configuration.html#typings) page.
.l-main-section
a(id="why-peer-dependencies")
:marked
## Why *peerDependencies*?
We don't have a *peerDependencies* section in the QuickStart `package.json`.
But Angular itself has a *peerDependencies* section in
*its* package.json and that has important consequences for our application.
There isn't a *peerDependencies* section in the QuickStart `package.json`.
But Angular has a *peerDependencies* section in
*its* package.json, which has important consequences for your application.
It explains why we load the [polyfill](#polyfills) *dependency* packages in the QuickStart `package.json`,
and why we'll need those packages in our own applications.
It explains why you load the [polyfill](#polyfills) *dependency* packages in the QuickStart `package.json`,
and why you'll need those packages in your own applications.
Let's briefly explain what [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) are about.
An explanation of [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) follows.
As we know, packages depend on other packages. For example, our application depends upon the Angular package.
Packages depend on other packages. For example, your application depends on the Angular package.
Two packages, 'A' and 'B', could depend on the same third package 'C'.
'A' and 'B' might both list 'C' among their *dependencies*.
Two packages, "A" and "B", could depend on the same third package "C".
"A" and "B" might both list "C" among their *dependencies*.
What if 'A' and 'B' depend on different versions of 'C' ('C1' and 'C2'). The npm package system supports that!
It installs 'C1' in the `node_modules` folder for 'A' and 'C2' in the `node_modules` folder for 'B'.
Now 'A' and 'B' have their own copies of 'C' and they run without interferring. This is great.
What if "A" and "B" depend on different versions of "C" ("C1" and "C2"). The npm package system supports that.
It installs "C1" in the `node_modules` folder for "A" and "C2" in the `node_modules` folder for "B".
Now "A" and "B" have their own copies of "C" and they run without interferring with one another.
But there is a problem. Package 'A' may require the presence of 'C1' without actually calling upon it directly.
'A' may only work if *everyone is using 'C1'*. It falls down if any part of the application relies on 'C2'.
But there is a problem. Package "A" may require the presence of "C1" without actually calling upon it directly.
"A" may only work if *everyone is using "C1"*. It falls down if any part of the application relies on "C2".
The solution is for 'A' to declare that 'C1' is a *peer dependency*.
The solution is for "A" to declare that "C1" is a *peer dependency*.
The difference between a `dependency` and a `peerDependency` is roughly this:
>A **dependency** says, "I need this thing directly available to *me*."
>
>A **peerDependency** says, "if you want to use me, you need this thing available to *you*."
>A **peerDependency** says, "If you want to use me, you need this thing available to *you*."
Angular finds itself in this situation.
Accordingly, the Angular `package.json` specifies several *peer dependency* packages,
The Angular `package.json` specifies several *peer dependency* packages,
each pinned to a particular version of a third-party package.
### We must install Angular's *peerDependencies* ourselves
### We must install Angular's *peerDependencies* ourselves.
When *npm* installs packages listed in *our* `dependencies` section,
When *npm* installs packages listed in *your* `dependencies` section,
it also installs the packages listed within *their* packages `dependencies` sections.
The process is recursive.
But as of version 3, *npm* does *not* install packages listed in *peerDependencies* sections.
However, as of version 3, *npm* does *not* install packages listed in *peerDependencies* sections.
That means when our application installs Angular, ***npm* will not automatically install
This means that when your application installs Angular, ***npm* doesn't automatically install
the packages listed in Angular's *peerDependencies* section**.
Fortunately, *npm* warns us (a) when any *peer dependencies* are missing or (b)
when the application or any its other dependencies
Fortunately, *npm* issues a warning (a) When any *peer dependencies* are missing, or (b)
When the application or any of its other dependencies
installs a different version of a *peer dependency*.
These warnings are a critical guard against accidental failures due to version mismatches.
They leave us in control of package and version resolution.
These warnings guard against accidental failures due to version mismatches.
They leave you in control of package and version resolution.
It is our responsibility to list all *peer dependency* packages **among our own *devDependencies***.
It is your responsibility to list all *peer dependency* packages **among your own *devDependencies***.
.l-sub-section
:marked
#### The future of *peerDependencies*
The Angular polyfill dependencies should be just a suggestion or a hint to developers so that they know what Angular expects.
They should not be hard requirements as they are today. We don't have a way to make them optional today.
The Angular polyfill dependencies are hard requirements. Currently, there is no way to make them optional.
There is a npm feature request for "optional peerDependencies" which would allow us to model this relationship better.
Once implemented, Angular will switch from *peerDependencies* to *optionalPeerDependencies* for all polyfills.
However, there is an npm feature request for "optional peerDependencies," which would allow you to model this relationship better.
When this feature request is implemented, Angular will switch from *peerDependencies* to *optionalPeerDependencies* for all polyfills.

95
public/docs/ts/latest/guide/typescript-configuration.jade
View File

@ -1,15 +1,13 @@
include ../_util-fns
:marked
TypeScript is a primary language for Angular application development.
TypeScript is a primary language for Angular application development. It is a dialect of JavaScript with design-time support for type-safety and tooling.
TypeScript is a dialect of JavaScript with design-time support for type-safety and tooling.
Browsers can't execute TypeScript directly. Typescript must be "transpiled" into JavaScript using the *tsc* compiler,
which requires some configuration.
Browsers can't execute TypeScript directly. It has to be "transpiled" into JavaScript with the *tsc* compiler
and that effort requires some configuration.
This chapter covers some aspects of TypeScript configuration and the TypeScript environment
that are important to Angular developers.
This page covers some aspects of TypeScript configuration and the TypeScript environment
that are important to Angular developers, including details about the following files:
* [tsconfig.json](#tsconfig) - TypeScript compiler configuration.
* [typings](#typings) - TypesScript declaration files.
@ -18,44 +16,41 @@ a(id="tsconfig")
.l-main-section
:marked
## *tsconfig.json*
We typically add a TypeScript configuration file (`tsconfig.json`) to our project to
Typically, you add a TypeScript configuration file (`tsconfig.json`) to your project to
guide the compiler as it generates JavaScript files.
.l-sub-section
:marked
Get details about `tsconfig.json` from the official
For details about `tsconfig.json`, see the official
[TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
:marked
We created the following `tsconfig.json` for the [QuickStart](../quickstart.html):
We created the following `tsconfig.json` for [QuickStart](../quickstart.html):
+makeJson('quickstart/ts/tsconfig.1.json', null, 'tsconfig.json')(format=".")
:marked
The options and flags in this file are essential for Angular 2 applications.
This file contains options and flags that are essential for Angular 2 applications.
<a id="noImplicitAny"></a>
### *noImplicitAny* and *suppressImplicitAnyIndexErrors*
TypeScript developers disagree about whether the `noImplicitAny` flag should be `true` or `false`.
There is no correct answer and we can change the flag later.
But our choice now can make a difference in larger projects so it merits discussion.
There is no correct answer and you can change the flag later.
But your choice now can make a difference in larger projects, so it merits discussion.
When the `noImplicitAny` flag is `false` (the default),
the compiler silently defaults the type of a variable to `any` if it cannot infer
the type based on how the variable is used. That's what we mean by *implicit `any`*.
When the `noImplicitAny` flag is `false` (the default), and if
the compiler cannot infer the variable type based on how it's used, the compiler silently defaults the type to `any`. That's what is meant by *implicit `any`*.
We initialized the `noImplicitAny` flag to `false` in the QuickStart
In the QuickStart exercise, the `noImplicitAny` flag is initialized to `false`
to make learning TypeScript development easier.
When the `noImplicitAny` flag is `true` and the TypeScript compiler cannot infer
the type, it still generates the JavaScript files. But it also **reports an error**.
the type, it still generates the JavaScript files, but it also **reports an error**.
Many seasoned developers prefer this stricter setting because type checking catches more
unintentional errors at compile time.
We can set a variable's type to `any` even when the `noImplicitAny` flag is `true`.
We do so when that seems like the best choice for the situation,
deliberately and explicitly, after giving the matter some thought.
You can set a variable's type to `any` even when the `noImplicitAny` flag is `true`.
If we set the `noImplicitAny` flag to `true`, we may get *implicit index errors* as well.
If you set the `noImplicitAny` flag to `true`, you may get *implicit index errors* as well.
Most developers feel that *this particular error* is more annoying than helpful.
We can suppress them with the following additional flag.
You can suppress them with the following additional flag:
code-example(format=".").
"suppressImplicitAnyIndexErrors":true
@ -64,68 +59,64 @@ a(id="typings")
.l-main-section
:marked
## TypeScript Typings
Many JavaScript libraries such as jQuery, the Jasmine testing library, and Angular itself,
Many JavaScript libraries, such as jQuery, the Jasmine testing library, and Angular,
extend the JavaScript environment with features and syntax
that the TypeScript compiler doesn't recognize natively.
When the compiler doesn't recognize something, it throws an error.
We use [TypeScript type definition files](http://www.typescriptlang.org/Handbook#writing-dts-files)
&mdash; *d.ts files* &mdash; to tell the compiler about the libraries we load.
Use [TypeScript type definition files](http://www.typescriptlang.org/Handbook#writing-dts-files)&mdash;`d.ts files`&mdash;to tell the compiler about the libraries you load.
TypeScript-aware editors leverage these same definition files to display type information about library features.
Many libraries include their definition files in their npm packages where both the TypeScript compiler and editors
Many libraries include definition files in their npm packages where both the TypeScript compiler and editors
can find them. Angular is one such library.
Peek into the `node_modules/@angular/core/` folder of any Angular application to see several `...d.ts` files that describe parts of Angular.
The `node_modules/@angular/core/` folder of any Angular application contains several `d.ts` files that describe parts of Angular.
**We need do nothing to get *typings* files for library packages which include *d.ts* files &mdash; as all Angular packages do.**
**You need do nothing to get *typings* files for library packages that include `d.ts` files&mdash;as all Angular packages do.**
### Installable typings files
Sadly, many libraries &mdash; jQuery, Jasmine, and Lodash among them &mdash; do *not* include `d.ts` files in their npm packages.
Fortunately, either their authors or community contributors have created separate *d.ts* files for these libraries and
Many libraries&mdash;jQuery, Jasmine, and Lodash among them&mdash;do *not* include `d.ts` files in their npm packages.
Fortunately, either their authors or community contributors have created separate `d.ts` files for these libraries and
published them in well-known locations.
The *typings* tool can find and fetch these files for us.
The *typings* tool can find and fetch these files for you.
We installed the [typings](https://github.com/typings/typings/blob/master/README.md) tool
with npm (it's listed among the *devDependencies* in the `package.json`) and added an npm script
to run that tool automatically after *npm* installation completes.
After installing the [typings](https://github.com/typings/typings/blob/master/README.md) tool
with npm (it's listed among the *devDependencies* in the `package.json`), add an npm script (`postinstall`)
to run that tool automatically, after *npm* installation finishes.
+makeJson('quickstart/ts/package.1.json', {paths: 'scripts.postinstall'}, 'package.json (postinstall)')(format=".")
:marked
This *typings* tool command installs the *d.ts* files that we identify in a `typings.json` file into the **typings** folder.
We created a `typings.json` file in the [QuickStart](../quickstart.html):
This *typings* tool command, `typings install`, installs the `d.ts` files into the **typings** folder.
You created a `typings.json` file in the [QuickStart](../quickstart.html):
+makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".")
:marked
We identified three *typings* file in the QuickStart, the *d.ts* files for
QuickStart identified three *typings* (`d.ts`) files:
* [core-js](https://github.com/zloirock/core-js/blob/master/README.md)
that brings ES2015/ES6 capabilities to our ES5 browsers
brings ES2015/ES6 capabilities to ES5 browsers
* [jasmine](http://jasmine.github.io/) typings for the Jasmine test framework
* [node](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/node/node.d.ts) for code that references objects in the nodejs environment;
see the [webpack](./webpack.html) chapter for an example.
* [node](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/node/node.d.ts) for code that references objects in the *nodejs* environment;
You can view an example in the [webpack](./webpack.html) page.
QuickStart itself doesn't require these typings but many of the documentation samples do.
Most of us would be disappointed if we couldn't code against
typical ES2015 features or support testing right out-of-the-box.
QuickStart doesn't require these typings but many of the samples do.
We can also run the *typings* tool ourselves.
The following command (re)installs the typings files, as is sometimes necessary when the `postInstall` hook fails to do so.
You can also run the *typings* tool yourself.
If the `postInstall` command fails to (re)install the typings files, run the following command to do so.
code-example(format="").
npm run typings install
:marked
This command lists the installed typings files:
Run this command to list the installed typings files:
code-example(format="").
npm run typings list
:marked
The following command installs or updates the typings file for the Jasmine test library from the *DefinitelyTyped* repository
and updates the `typings.config` so we that we get it automatically the next time we install typings.
The following command installs or updates the typings file for the Jasmine test library from the *DefinitelyTyped* repository,
and updates the `typings.config` file so you receive it automatically the next time you install typings.
code-example(format="").
npm run typings -- install dt~jasmine --save --global
.l-sub-section
:marked
The [&ndash;&ndash; option](https://docs.npmjs.com/cli/run-script) is important;
it tells npm to pass all arguments to the right of `--` to the *typings* command.
The [&ndash;&ndash; option](https://docs.npmjs.com/cli/run-script) tells npm to pass all arguments to the right of `--` to the *typings* command.
Learn about the features of the *typings* tool at its [site on github](https://github.com/typings/typings/blob/master/README.md).
Read about the features of the *typings* tool at its [site on github](https://github.com/typings/typings/blob/master/README.md).

22
public/features.jade
View File

@ -3,8 +3,8 @@ div
h2(class="text-headline") Cross Platform
div(class="feature-row")
div(class="feature")
h3 Progressive Web Apps
p(class="text-body") Use modern web platform capabilities to deliver app-like experiences. High performance, offline and zero-step installation.
h3 Progressive web apps
p(class="text-body") Use modern web platform capabilities to deliver app-like experiences. High performance, offline, and zero-step installation.
div(class="feature")
h3 Native
@ -12,19 +12,19 @@ div
div(class="feature")
h3 Desktop
p(class="text-body") Create desktop-installed apps across Mac, Windows, and Linux using the same Angular methods you've learned for the web plus ability to access native OS APIs.
p(class="text-body") Create desktop-installed apps across Mac, Windows, and Linux using the same Angular methods you've learned for the web plus the ability to access native OS APIs.
h2(class="text-headline") Speed & Performance
h2(class="text-headline") Speed and Performance
div(class="feature-row")
div(class="feature")
h3 Code generation
p(class="text-body") Angular turns your templates into code that's highly optimized for today's JavaScript virtual machines giving you all the benefits of hand-written code with the productivity of a framework.
p(class="text-body") Angular turns your templates into code that's highly optimized for today's JavaScript virtual machines, giving you all the benefits of hand-written code with the productivity of a framework.
div(class="feature")
h3 Universal
p(class="text-body") Serve the first view of your application on node.js, .NET, PHP and other servers for near-instant rendering in just HTML and CSS. Also paves the way for sites that optimize for SEO.
p(class="text-body") Serve the first view of your application on node.js, .NET, PHP, and other servers for near-instant rendering in just HTML and CSS. Also paves the way for sites that optimize for SEO.
div(class="feature")
h3 Code Splitting
p(class="text-body") Angular apps load quickly with the new Component Router that delivers automatic code-splitting so users only load code required to render the view they request.
h3 Code splitting
p(class="text-body") Angular apps load quickly with the new Component Router, which delivers automatic code-splitting so users only load code required to render the view they request.
h2(class="text-headline") Productivity
div(class="feature-row")
@ -36,16 +36,16 @@ div
p(class="text-body") Command line tools: start building fast, add components and tests, then instantly deploy.
div(class="feature")
h3 IDEs
p(class="text-body") Get intelligent code completion, instant errors and other feedback in popular editors and IDEs.
p(class="text-body") Get intelligent code completion, instant errors, and other feedback in popular editors and IDEs.
h2(class="text-headline") Full Development Story
div(class="feature-row")
div(class="feature")
h3 Testing
p(class="text-body") With Karma for unit tests, you can know if you've broken things every time you save. And Protractor makes your scenario tests run faster and stably.
p(class="text-body") With Karma for unit tests, you can know if you've broken things every time you save. And Protractor makes your scenario tests run faster and in a stable manner.
div(class="feature")
h3 Animation
p(class="text-body") Create high performance complex choreographies and animation timelines with very little code through Angular's intuitive API.
p(class="text-body") Create high-performance, complex choreographies and animation timelines with very little code through Angular's intuitive API.
div(class="feature")
h3 Accessibility
p(class="text-body") Create accessible applications with ARIA-enabled components, developer guides, and built-in a11y test infrastructure.