iSharkFly-Docs/angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Guide & Features edits (#2180)

Browse Source 
* 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 ## Code Sample Development
All documentation is supported by sample code and plunkers. 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`. 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. **We are not using Angular yet**. There are no bindings. No extra directives. Just layout.
The `container`,`form-group`, `form-control`, and `btn` classes 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. 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!

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. **We are not using Angular yet**. There are no bindings. No extra directives. Just layout.
The `container`,`form-group`, `form-control`, and `btn` classes 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. 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!

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

@ -32,7 +32,7 @@ block includes
.l-sub-section .l-sub-section
:marked :marked
Angular applications can be compiled by developers at build-time. 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. 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. 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 .l-sub-section
:marked :marked
Angular applications can be compiled by developers at build-time. 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. 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. 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": { "npm-packages": {
"title": "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": { "pipes": {

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

@ -4,25 +4,24 @@ block includes
- var _at_angular = '@angular' - var _at_angular = '@angular'
:marked :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. either JavaScript or a language (like Dart or TypeScript) that compiles to JavaScript.
block angular-parts block angular-parts
:marked :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 :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*, writing *component* classes to manage those templates, adding application logic in *services*,
and boxing components and services in *modules*. and boxing components and services in *modules*.
Then we launch the app by *bootstrapping* the top _root module_. Then you launch the app by *bootstrapping* the _root module_.
Angular takes over, presenting our application content in a browser and Angular takes over, presenting your application content in a browser and
responding to user interactions according to the instructions we provided. responding to user interactions according to the instructions you've provided.
Of course there is more to it than this. Of course, there is more to it than this.
We'll learn the details when we dive into the guide chapters. You'll learn the details in the pages that follow. For now, focus on the big picture.
Let's get the big picture first.
figure figure
img(src="/resources/images/devguide/architecture/overview2.png" alt="overview" style="margin-left:-40px;" width="700") img(src="/resources/images/devguide/architecture/overview2.png" alt="overview" style="margin-left:-40px;" width="700")
@ -30,19 +29,19 @@ figure
:marked :marked
The architecture diagram identifies the eight main building blocks of an Angular 2 application: The architecture diagram identifies the eight main building blocks of an Angular 2 application:
1. [Modules](#modules) * [Modules](#modules)
1. [Components](#components) * [Components](#components)
1. [Templates](#templates) * [Templates](#templates)
1. [Metadata](#metadata) * [Metadata](#metadata)
1. [Data binding](#data-binding) * [Data binding](#data-binding)
1. [Directives](#directives) * [Directives](#directives)
1. [Services](#services) * [Services](#services)
1. [Dependency injection](#dependency-injection) * [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 .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 .l-main-section
:marked :marked
@ -50,18 +49,18 @@ figure
figure figure
img(src="/resources/images/devguide/architecture/module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" ) img(src="/resources/images/devguide/architecture/module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
:marked :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. _Angular modules_ are a big deal.
We can only introduce them here; the [Angular Modules](ngmodule.html) chapter covers modules in depth. This page introduces modules; the [Angular modules](ngmodule.html) page covers them in depth.
<br clear="all"><br> <br clear="all"><br>
:marked :marked
Every Angular app has at least one module, the _root module_, conventionally named `AppModule`. 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 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, _feature modules_, each a cohesive block of code dedicated to an application domain,
a workflow, or a closely-related set of capabilities. a workflow, or a closely related set of capabilities.
An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator. An Angular module, whether a _root_ or _feature_, is a class with an `@NgModule` decorator.
.l-sub-section .l-sub-section
@ -73,18 +72,18 @@ figure
Learn more</a> about decorators on the web. Learn more</a> about decorators on the web.
:marked :marked
`NgModule` is a decorator function that takes a single metadata object whose properties describe the module. `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. * `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. * `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. 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. that hosts all other app views. Only the _root module_ should set this `bootstrap` property.
Here's a simple root module: Here's a simple root module:
@ -92,21 +91,17 @@ figure
.l-sub-section .l-sub-section
:marked :marked
The `export` of `AppComponent` is just for show. 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.
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.
:marked :marked
We launch an application by _bootstrapping_ its root module. 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. 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='.') +makeExample('app/main.ts', '', 'app/main.ts')(format='.')
:marked :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. JavaScript also has its own module system for managing collections of JavaScript objects.
It's completely different and unrelated to the Angular module system. It's completely different and unrelated to the Angular module system.
@ -122,39 +117,38 @@ figure
:marked :marked
<a href="http://exploringjs.com/es6/ch_modules.html" target="_blank">Learn more about the JavaScript module system on the web.</a> <a href="http://exploringjs.com/es6/ch_modules.html" target="_blank">Learn more about the JavaScript module system on the web.</a>
:marked :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 figure
img(src="/resources/images/devguide/architecture/library-module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" ) img(src="/resources/images/devguide/architecture/library-module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" )
:marked :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> <br clear="all"><br>
:marked :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='.') +makeExample('app/app.component.ts', 'import', '')(format='.')
:marked :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='.') +makeExample('app/mini-app.ts', 'import-browser-module', '')(format='.')
:marked :marked
Our application module needs material from within that `BrowserModule` 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.
so we add it to the `@NgModule` metadata `imports` like this.
+makeExample('app/mini-app.ts', 'ngmodule-imports', '')(format='.') +makeExample('app/mini-app.ts', 'ngmodule-imports', '')(format='.')
:marked :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". 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 .l-sub-section
:marked :marked
Learn more in the [Angular Modules](ngmodule.html) chapter. Learn more from the [Angular modules](ngmodule.html) page.
.l-hr .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" ) img(src="/resources/images/devguide/architecture/hero-component.png" alt="Component" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
:marked :marked
A **component** controls a patch of screen real estate that we could call a *view*. A _component_ controls a patch of screen called 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.
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. The class interacts with the view through an API of properties and methods.
<a id="component-code"></a> <a id="component-code"></a>
A `HeroListComponent`, for example, might have a `heroes` property that returns !{_an} !{_array} of heroes For example, this `HeroListComponent` has a `heroes` property that returns !{_an} !{_array} of heroes
that it acquired from a service. that it acquires 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. `HeroListComponent` also has 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:
+makeExcerpt('app/hero-list.component.ts', 'class') +makeExcerpt('app/hero-list.component.ts', 'class')
:marked :marked
Angular creates, updates, and destroys components as the user moves through the application. 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. Your app 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.
.l-hr .l-hr
@ -196,26 +189,21 @@ figure
figure figure
img(src="/resources/images/devguide/architecture/template.png" alt="Template" align="left" style="width:200px; margin-left:-40px;margin-right:10px" ) img(src="/resources/images/devguide/architecture/template.png" alt="Template" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
:marked :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. 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`: template for our `HeroListComponent`:
+makeExample('app/hero-list.component.html') +makeExample('app/hero-list.component.html')
:marked :marked
This template features typical HTML elements like `<h2>` and `<p>`. 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).
But what are `*ngFor`, `{{hero.name}}`, `(click)`, `[hero]`, and `<hero-detail>`?
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. In the last line of the template, the `<hero-detail>` tag is a custom element that represents a new component, `HeroDetailComponent`.
The `<hero-detail>` tag is a custom element representing the `HeroDetailComponent`.
The `HeroDetailComponent` is a *different* component than the `HeroListComponent` you've been reviewing.
The `HeroDetailComponent` is a *different* component than the `HeroListComponent` we've been reviewing.
The `HeroDetailComponent` (code not shown) presents facts about a particular hero, the The `HeroDetailComponent` (code not shown) presents facts about a particular hero, the
hero that the user selects from the list presented by the `HeroListComponent`. hero that the user selects from the list presented by the `HeroListComponent`.
The `HeroDetailComponent` is a **child** of the `HeroListComponent`. The `HeroDetailComponent` is a **child** of the `HeroListComponent`.
@ -223,10 +211,8 @@ figure
figure figure
img(src="/resources/images/devguide/architecture/component-tree.png" alt="Metadata" align="left" style="width:300px; margin-left:-40px;margin-right:10px" ) img(src="/resources/images/devguide/architecture/component-tree.png" alt="Metadata" align="left" style="width:300px; margin-left:-40px;margin-right:10px" )
:marked :marked
Notice how `<hero-detail>` rests comfortably among native HTML elements. Notice how `<hero-detail>` rests comfortably among native HTML elements. Custom components mix seamlessly with native HTML in the same layouts.
We can and _will_ mix our custom components 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"> <br clear="all">
.l-hr .l-hr
@ -241,20 +227,20 @@ figure
<p style="padding-top:10px">Metadata tells Angular how to process a class.</p> <p style="padding-top:10px">Metadata tells Angular how to process a class.</p>
<br clear="all"> <br clear="all">
:marked :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. 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`: Here's some metadata for `HeroListComponent`:
+makeExcerpt('app/hero-list.component.ts', 'metadata') +makeExcerpt('app/hero-list.component.ts', 'metadata')
:marked :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. immediately below it as a component class.
block ts-decorator block ts-decorator
@ -270,32 +256,30 @@ block ts-decorator
For example, if an app's HTML contains `<hero-list></hero-list>`, then For example, if an app's HTML contains `<hero-list></hero-list>`, then
Angular inserts an instance of the `HeroListComponent` view between those tags. 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. - `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. 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. - `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` 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. We'll get to dependency injection later. so it can get the list of heroes to display.
figure figure
img(src="/resources/images/devguide/architecture/template-metadata-component.png" alt="Metadata" align="left" style="height:200px; margin-left:-40px;margin-right:10px" ) img(src="/resources/images/devguide/architecture/template-metadata-component.png" alt="Metadata" align="left" style="height:200px; margin-left:-40px;margin-right:10px" )
:marked :marked
Angular reads the metadata specified by the `@Component` The metadata in the `@Component` tells Angular where to get the major building blocks you specify for the component.
annotation. That's how Angular learns to do "the right thing".
The template, metadata, and component together describe a view. The template, metadata, and component together describe a view.
We apply other metadata !{_decorator}s in a similar fashion to guide Angular behavior. 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 `@Injectable`, `@Input`, and `@Output` are a few of the more popular !{_decorator}s.
we'll master as our Angular knowledge grows.
<br clear="all"> <br clear="all">
:marked :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. so that Angular knows what to do.
.l-hr .l-hr
@ -303,7 +287,7 @@ figure
.l-main-section .l-main-section
:marked :marked
## Data binding ## 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 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. read as any experienced jQuery programmer can attest.
figure figure
@ -311,13 +295,12 @@ figure
:marked :marked
Angular supports **data binding**, Angular supports **data binding**,
a mechanism for coordinating parts of a template with parts of a component. 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 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.
as indicated by the arrows in the diagram.
<br clear="all"> <br clear="all">
:marked :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') +makeExcerpt('app/hero-list.component.1.html', 'binding')
@ -332,8 +315,7 @@ figure
**Two-way data binding** is an important fourth form **Two-way data binding** is an important fourth form
that combines property and event binding in a single notation, using the `ngModel` directive. 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') +makeExcerpt('app/hero-detail.component.html', 'ngModel')
@ -343,13 +325,12 @@ figure
as with event binding. as with event binding.
Angular processes *all* data bindings once per JavaScript event cycle, 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 figure
img(src="/resources/images/devguide/architecture/component-databinding.png" alt="Data Binding" style="float:left; width:300px; margin-left:-40px;margin-right:10px" ) img(src="/resources/images/devguide/architecture/component-databinding.png" alt="Data Binding" style="float:left; width:300px; margin-left:-40px;margin-right:10px" )
:marked :marked
We don't know all the details yet, Data binding plays an important role in communication
but it's clear from these examples that data binding plays an important role in communication
between a template and its component. between a template and its component.
<br clear="all"> <br clear="all">
figure figure
@ -369,18 +350,17 @@ figure
Angular templates are *dynamic*. When Angular renders them, it transforms the DOM Angular templates are *dynamic*. When Angular renders them, it transforms the DOM
according to the instructions given by **directives**. 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. to attach metadata to the class.
<br clear="all"> <br clear="all">
:marked :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. a `@Component` !{_decorator} is actually a `@Directive` !{_decorator} extended with template-oriented features.
.l-sub-section .l-sub-section
:marked :marked
While **a component is technically a directive**, While **a component is technically a directive**,
components are so distinctive and central to Angular applications that we chose components are so distinctive and central to Angular applications that this architectural overview separates components from directives.
to separate components from directives in this architectural overview.
:marked :marked
Two *other* kinds of directives exist: _structural_ and _attribute_ directives. 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. **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') +makeExcerpt('app/hero-list.component.1.html', 'structural')
@ -411,12 +391,12 @@ block dart-bool
+makeExcerpt('app/hero-detail.component.html', 'ngModel') +makeExcerpt('app/hero-detail.component.html', 'ngModel')
:marked :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)) (for example, [ngSwitch](template-syntax.html#ngSwitch))
or modify aspects of DOM elements and components or modify aspects of DOM elements and components
(for example, [ngStyle](template-syntax.html#ngStyle) and [ngClass](template-syntax.html#ngClass)). (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. `HeroListComponent` are one kind of custom directive.
<!-- PENDING: link to where to learn more about other kinds! --> <!-- PENDING: link to where to learn more about other kinds! -->
@ -428,7 +408,7 @@ block dart-bool
figure figure
img(src="/resources/images/devguide/architecture/service.png" alt="Service" style="float:left; margin-left:-40px;margin-right:10px" ) img(src="/resources/images/devguide/architecture/service.png" alt="Service" style="float:left; margin-left:-40px;margin-right:10px" )
:marked :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. 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. 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 * tax calculator
* application configuration * 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. 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') +makeExcerpt('app/logger.service.ts', 'class')
@ -459,8 +439,8 @@ figure
:marked :marked
Services are everywhere. Services are everywhere.
We prefer our component classes lean. Our components don't fetch data from the server, Component classes should be lean. They don't fetch data from the server,
they don't validate user input, and they don't log directly to the console. validate user input, or log directly to the console.
They delegate such tasks to services. 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) 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. It delegates everything nontrivial to services.
Angular doesn't *enforce* these principles. 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*. application logic into services and make those services available to components through *dependency injection*.
.l-hr .l-hr
@ -488,7 +468,7 @@ figure
<br clear="all"> <br clear="all">
:marked :marked
Angular can tell which services a component needs by looking at the types of its constructor parameters. 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') +makeExcerpt('app/hero-list.component.ts (constructor)', 'ctor')
@ -501,7 +481,7 @@ figure
before returning the service to Angular. before returning the service to Angular.
When all requested services have been resolved and returned, When all requested services have been resolved and returned,
Angular can call the component's constructor with those services as arguments. 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: The process of `HeroService` injection looks a bit like this:
figure figure
@ -509,27 +489,27 @@ figure
:marked :marked
If the injector doesn't have a `HeroService`, how does it know how to make one? 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. 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. the same instance of a service is available everywhere.
+makeExample('app/app.module.ts', 'providers', 'app/app.module.ts (module providers)')(format='.') +makeExample('app/app.module.ts', 'providers', 'app/app.module.ts (module providers)')(format='.')
:marked :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='.') +makeExample('app/hero-list.component.ts', 'providers', 'app/hero-list.component.ts (component providers)')(format='.')
:marked :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. service with each new instance of that component.
<!-- We've vastly oversimplified dependency injection for this overview. <!-- 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: Points to remember about dependency injection:
@ -541,7 +521,7 @@ figure
* A *provider* is a recipe for creating a service. * A *provider* is a recipe for creating a service.
* We register *providers* with injectors. * Register *providers* with injectors.
.l-hr .l-hr
@ -549,44 +529,41 @@ figure
:marked :marked
## Wrap up ## 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) * [Modules](#modules)
1. [Components](#components) * [Components](#components)
1. [Templates](#templates) * [Templates](#templates)
1. [Metadata](#metadata) * [Metadata](#metadata)
1. [Data binding](#data-binding) * [Data binding](#data-binding)
1. [Directives](#directives) * [Directives](#directives)
1. [Services](#services) * [Services](#services)
1. [Dependency injection](#dependency-injection) * [Dependency injection](#dependency-injection)
That's a foundation for everything else in an Angular application, That's a foundation for everything else in an Angular application,
and it's more than enough to get going. 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. 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 > [**Animations**](animations.html): Animate component behavior
without deep knowledge of animation techniques or CSS. 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 > **Change detection**: The change detection documentation will cover how Angular decides that a component property value has changed,
when to update the screen. when to update the screen, and how it uses **zones** to intercept asynchronous activity and run its change detection strategies.
Learn 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. publishing and subscribing to events.
> [**Forms**](forms.html): Support complex data entry scenarios with HTML-based validation and dirty checking. > [**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. > [**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. by implementing the lifecycle hook interfaces.
> [**Pipes**](pipes.html): Services that transform values for display. > [**Pipes**](pipes.html): Use pipes in your templates to improve the user experience by transforming values for display. Consider this `currency` pipe expression:
We can put pipes in our templates to improve the user experience. Consider
this `currency` pipe expression:
<div style="margin-left:40px"> <div style="margin-left:40px">
code-example(). code-example().
price | currency:'USD':true price | currency:'USD':true
@ -597,6 +574,6 @@ code-example().
> [**Router**](router.html): Navigate from page to page within the client > [**Router**](router.html): Navigate from page to page within the client
application and never leave the browser. 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) [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 This is a practical guide to Angular for experienced programmers who
are building client applications in HTML and #{langName}. 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"> <br clear="all">
// #enddocregion intro // #enddocregion intro
@ -20,7 +18,7 @@ figure
# Organization # Organization
The documentation is divided into major thematic sections, each 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 // #enddocregion how-to-read-1
// #docregion how-to-read-2 // #docregion how-to-read-2
- var top="vertical-align:top" - var top="vertical-align:top"
@ -31,7 +29,7 @@ table(width="100%")
td <b>QuickStart</b> td <b>QuickStart</b>
td td
:marked :marked
The foundation for every chapter and sample in this documentation. The foundation for every page and sample in this documentation.
tr(style=top) tr(style=top)
td <b>Tutorial</b> td <b>Tutorial</b>
td td
@ -60,55 +58,50 @@ table(width="100%")
Authoritative details about each member of the Angular libraries. Authoritative details about each member of the Angular libraries.
:marked :marked
# Learning path # 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. For those new to Angular, the recommended learning path runs through the *Basics* section:
Most of that 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. 1. Try [QuickStart](../quickstart.html). 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. 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 1. Take the *Tour of Heroes* [tutorial](../tutorial), which picks up where QuickStart leaves off,
and builds a simple data-driven app. and builds a simple data-driven app. The app demonstrates the essential characteristics of a professional application:
Simple, yes, but with the essential characteristics we'd expect of a professional application:
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access. 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 to build large, maintainable applications
1. [Dependency Injection](dependency-injection.html) is the way we build large, maintainable applications
from small, single-purpose parts. from small, single-purpose parts.
1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML. 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 // #enddocregion how-to-read-2
// #docregion the-rest // #docregion the-rest
:marked :marked
# Code samples # Code samples
Every chapter includes code snippets that we can reuse in our own applications. Each page includes code snippets that you can reuse in your applications.
These snippets are excerpts from a sample application that accompanies the chapter. These snippets are excerpts from a sample application that accompanies the page.
block example-links block example-links
:marked :marked
Look for a link to a running version of that sample near the top of each page, 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 :marked
A few early chapters are written as tutorials and are clearly marked as such. A few early pages are written as tutorials and are clearly marked as such.
Most chapters are *not* tutorials. The rest of the pages highlight key points in code rather than explain each step necessary to build the sample.
They 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}.
We can always get the full source by way of the #{_liveLink}.
# Reference pages # Reference pages
@ -120,10 +113,10 @@ block example-links
# Feedback # 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 Use the [angular.io Github repo](https://github.com/angular/angular.io) for **documentation** issues and pull requests.
[angular.io](https://github.com/angular/angular.io) github repository.
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 // #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. It may add service providers to the application dependency injectors.
And there are more options covered here. 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). either immediately when the application launches or later, as needed, via the [Router](router.html).
## Contents ## Contents
@ -34,7 +34,7 @@ block includes
* [NgModule metadata properties](#ngmodule-properties "A technical summary of the @NgModule metadata properties") * [NgModule metadata properties](#ngmodule-properties "A technical summary of the @NgModule metadata properties")
### Live examples ### 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: 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> * <live-example plnkr="minimal.0">A minimal NgModule app</live-example>
@ -45,11 +45,11 @@ block includes
### Frequently Asked Questions (FAQs) ### 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 The companion [Angular Module FAQs](../cookbook/ngmodule-faq.html "Angular Module FAQs") cookbook
offers ready answers to specific design and implementation questions. 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 .l-hr
@ -92,7 +92,7 @@ a#angular-modularity
that represent collections of related functionality. that represent collections of related functionality.
We then import these modules into the _root module_. 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 a#root_module
.l-main-section .l-main-section
@ -131,7 +131,7 @@ a#bootstrap
We launch the application by bootstrapping the `AppModule` in the `main.ts` file. We launch the application by bootstrapping the `AppModule` in the `main.ts` file.
Angular offers a variety of bootstrapping options, targeting multiple platforms. 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 ### 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") 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=".") +makeExample('ngmodule/ts/app/main.ts', '', 'app/main.ts (dynamic)')(format=".")
:marked :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> <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. 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 the Angular hierarchical dependency injection system and how to configure that system
with [providers](dependency-injection.html#providers) at different levels of the with [providers](dependency-injection.html#providers) at different levels of the
application's component tree. application's component tree.
@ -668,7 +668,7 @@ a#lazy-load
### App routing ### App routing
+makeExample('ngmodule/ts/app/app.routing.ts', '', 'app/app.routing.ts')(format='.') +makeExample('ngmodule/ts/app/app.routing.ts', '', 'app/app.routing.ts')(format='.')
:marked :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. concentrate on the intersection of Angular modules and routing.
This file defines three routes. This file defines three routes.
@ -768,7 +768,7 @@ a#hero-module
.file hero.service.ts .file hero.service.ts
.file highlight.directive.ts .file highlight.directive.ts
:marked :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. 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`) Its template has a `<router-outlet>` that displays either a list of heroes (`HeroList`)
or an editor of a selected hero (`HeroDetail`). or an editor of a selected hero (`HeroDetail`).
@ -880,7 +880,7 @@ a#core-module
.l-sub-section .l-sub-section
:marked :marked
We're importing some extra symbols from the Angular core library that we're not using yet. 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 :marked
The `@NgModule` metadata should be familiar. The `@NgModule` metadata should be familiar.
We declare the `TitleComponent` because this module _owns_ it and we export it 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 include ../_util-fns
:marked :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>). These packages are maintained and installed with the Node Package Manager (<a href="https://docs.npmjs.com/" target="_blank">npm</a>).
.l-sub-section .l-sub-section
:marked :marked
Node.js and npm are essential to Angular 2 development. 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"> <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`** **Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher**
by running `node -v` and `npm -v` in a terminal/console window. by running the commands `node -v` and `npm -v` in a terminal/console window.
Older versions produce errors. 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 :marked
We recommend a comprehensive starter-set of packages as specified in the `dependencies` and `devDependencies` 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: <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=".") +makeJson('quickstart/ts/package.1.json',{ paths: 'dependencies, devDependencies'}, 'package.json (dependencies)')(format=".")
:marked :marked
There are other possible package choices and you're likely to add and subtract to meet your application needs. You can use other packages but we recommend *this particular set* to start with because (a) they work well together and
We're recommending *this particular set* because (a) we know they work well together and (b) they include everything you'll need to build and run the sample applications in this series.
(b) they include everything we'll need to build and run the sample applications in this documentation series.
.l-sub-section .l-sub-section
:marked :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 :marked
This is far more than we need for QuickStart. You'll install more than you need for QuickStart.
Indeed, it's more than we need for most applications. No worries!
There is no harm in installing more than we need. You only serve to the client those packages that the application actually requests.
We 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. This page explains what each package does. You can make substitutions later to suit your tastes and experience.
Feel free to make substitutions later to suit your tastes and experience.
.l-main-section .l-main-section
:marked :marked
## *dependencies* and *devDependencies* ## *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). [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. 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"). code-example(format="." language="bash").
npm install my-application --production npm install my-application --production
@ -53,9 +50,9 @@ a(id="dependencies")
.l-main-section .l-main-section
:marked :marked
## *dependencies* ## *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. * ***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. ***@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. 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*. ***@angular/compiler*** - Angular's *Template Compiler*.
It understand templates and can convert them to code that makes the app run and render. It understands templates and can convert them to code that makes the application run and render.
Developers typically don’t interact with the compiler directly. Typically you don’t interact with the compiler directly; rather, you use it indirectly via `platform-browser-dynamic` or the offline template compiler.
They 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. ***@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. 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. 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. ***@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 ***[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. [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/). Other viable choices include the well-regarded [webpack](https://webpack.github.io/).
SystemJS happens to be the one we use in the documentation samples. It works.
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. HTML controls, themes, data access, and various utilities.
a(id="polyfills") a(id="polyfills")
.l-main-section .l-main-section
:marked :marked
### Polyfill Packages ### Polyfill packages
Angular requires certain [polyfills](https://en.wikipedia.org/wiki/Polyfill) in the application environment. 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 .l-sub-section
:marked :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 :marked
***core-js*** - Monkey patches the global context (window) with essential features of ES2015 (ES6). ***core-js*** - Patches the global context (window) with essential features of ES2015 (ES6).
Developers may substitute an alternative polyfill that provides the same core APIs. You 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. 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***. ***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. 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 ***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. [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. without waiting for Angular updates.
***zone.js*** - A polyfill for the [Zone specification](https://gist.github.com/mhevery/63fdcdf7c65886051d55) currently before the ***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. [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. without waiting for Angular updates.
a(id="other") 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 ***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. without requiring an actual server or real http calls.
Good for demos, documentation samples, and early stage development (before we even have a server). Good for demos, 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. 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. ***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") a(id="dev-dependencies")
.l-main-section .l-main-section
:marked :marked
## *devDependencies* ## *devDependencies*
The packages listed in the *devDependencies* section of the `package.json` help us develop the application. The packages listed in the *devDependencies* section of the `package.json` help you develop the application.
They do not have to be deployed with the production application although there is rarely harm in doing so. 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)*** - ***[concurrently](https://www.npmjs.com/package/concurrently)*** -
A utility to run multiple *npm* commands concurrently on OS/X, Windows, and Linux operating systems. 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)*** - ***[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. with excellent support for Angular apps that use routing.
***[typescript](https://www.npmjs.com/package/typescript)*** - ***[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. ***[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. Read more about it in the [TypeScript Configuration](typescript-configuration.html#typings) page.
This section likely grows as we add more tools, testing, and build support.
The QuickStart set is sufficient for developing the documentation sample applications.
.l-main-section .l-main-section
a(id="why-peer-dependencies") a(id="why-peer-dependencies")
:marked :marked
## Why *peerDependencies*? ## Why *peerDependencies*?
We don't have a *peerDependencies* section in the QuickStart `package.json`. There isn't a *peerDependencies* section in the QuickStart `package.json`.
But Angular itself has a *peerDependencies* section in But Angular has a *peerDependencies* section in
*its* package.json and that has important consequences for our application. *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`, It explains why you load the [polyfill](#polyfills) *dependency* packages in the QuickStart `package.json`,
and why we'll need those packages in our own applications. 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'. Two packages, "A" and "B", could depend on the same third package "C".
'A' and 'B' might both list 'C' among their *dependencies*. "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! 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'. 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. 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. 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'. "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: The difference between a `dependency` and a `peerDependency` is roughly this:
>A **dependency** says, "I need this thing directly available to *me*." >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. The Angular `package.json` specifies several *peer dependency* packages,
Accordingly, the Angular `package.json` specifies several *peer dependency* packages,
each pinned to a particular version of a third-party package. 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. it also installs the packages listed within *their* packages `dependencies` sections.
The process is recursive. 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**. the packages listed in Angular's *peerDependencies* section**.
Fortunately, *npm* warns us (a) when any *peer dependencies* are missing or (b) Fortunately, *npm* issues a warning (a) When any *peer dependencies* are missing, or (b)
when the application or any its other dependencies When the application or any of its other dependencies
installs a different version of a *peer dependency*. installs a different version of a *peer dependency*.
These warnings are a critical guard against accidental failures due to version mismatches. These warnings guard against accidental failures due to version mismatches.
They leave us in control of package and version resolution. 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 .l-sub-section
:marked :marked
#### The future of *peerDependencies* #### 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. The Angular polyfill dependencies are hard requirements. Currently, there is no way to make them optional.
They should not be hard requirements as they are today. We don't have a way to make them optional today.
There is a npm feature request for "optional peerDependencies" which would allow us to model this relationship better. However, there is an npm feature request for "optional peerDependencies," which would allow you to model this relationship better.
Once implemented, Angular will switch from *peerDependencies* to *optionalPeerDependencies* for all polyfills. 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 include ../_util-fns
:marked :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 This page covers some aspects of TypeScript configuration and the TypeScript environment
and that effort requires some configuration. that are important to Angular developers, including details about the following files:
This chapter covers some aspects of TypeScript configuration and the TypeScript environment
that are important to Angular developers.
* [tsconfig.json](#tsconfig) - TypeScript compiler configuration. * [tsconfig.json](#tsconfig) - TypeScript compiler configuration.
* [typings](#typings) - TypesScript declaration files. * [typings](#typings) - TypesScript declaration files.
@ -18,44 +16,41 @@ a(id="tsconfig")
.l-main-section .l-main-section
:marked :marked
## *tsconfig.json* ## *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. guide the compiler as it generates JavaScript files.
.l-sub-section .l-sub-section
:marked :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). [TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
:marked :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=".") +makeJson('quickstart/ts/tsconfig.1.json', null, 'tsconfig.json')(format=".")
:marked :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> <a id="noImplicitAny"></a>
### *noImplicitAny* and *suppressImplicitAnyIndexErrors* ### *noImplicitAny* and *suppressImplicitAnyIndexErrors*
TypeScript developers disagree about whether the `noImplicitAny` flag should be `true` or `false`. 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. There is no correct answer and you can change the flag later.
But our choice now can make a difference in larger projects so it merits discussion. But your choice now can make a difference in larger projects, so it merits discussion.
When the `noImplicitAny` flag is `false` (the default), When the `noImplicitAny` flag is `false` (the default), and if
the compiler silently defaults the type of a variable to `any` if it cannot infer 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`*.
the type based on how the variable is used. That's what we mean 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. to make learning TypeScript development easier.
When the `noImplicitAny` flag is `true` and the TypeScript compiler cannot infer 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 Many seasoned developers prefer this stricter setting because type checking catches more
unintentional errors at compile time. unintentional errors at compile time.
We can set a variable's type to `any` even when the `noImplicitAny` flag is `true`. You 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.
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. 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="."). code-example(format=".").
"suppressImplicitAnyIndexErrors":true "suppressImplicitAnyIndexErrors":true
@ -64,68 +59,64 @@ a(id="typings")
.l-main-section .l-main-section
:marked :marked
## TypeScript Typings ## 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 extend the JavaScript environment with features and syntax
that the TypeScript compiler doesn't recognize natively. that the TypeScript compiler doesn't recognize natively.
When the compiler doesn't recognize something, it throws an error. 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) 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.
&mdash; *d.ts files* &mdash; to tell the compiler about the libraries we load.
TypeScript-aware editors leverage these same definition files to display type information about library features. 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. 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 ### Installable typings files
Sadly, many libraries &mdash; jQuery, Jasmine, and Lodash among them &mdash; do *not* include `d.ts` files in their npm packages. 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 Fortunately, either their authors or community contributors have created separate `d.ts` files for these libraries and
published them in well-known locations. 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 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`) and added an npm script 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 completes. to run that tool automatically, after *npm* installation finishes.
+makeJson('quickstart/ts/package.1.json', {paths: 'scripts.postinstall'}, 'package.json (postinstall)')(format=".") +makeJson('quickstart/ts/package.1.json', {paths: 'scripts.postinstall'}, 'package.json (postinstall)')(format=".")
:marked :marked
This *typings* tool command installs the *d.ts* files that we identify in a `typings.json` file into the **typings** folder. This *typings* tool command, `typings install`, installs the `d.ts` files into the **typings** folder.
We created a `typings.json` file in the [QuickStart](../quickstart.html): You created a `typings.json` file in the [QuickStart](../quickstart.html):
+makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".") +makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".")
:marked :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) * [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 * [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; * [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. 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. QuickStart doesn't require these typings but many of the 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.
We can also run the *typings* tool ourselves. You can also run the *typings* tool yourself.
The following command (re)installs the typings files, as is sometimes necessary when the `postInstall` hook fails to do so. If the `postInstall` command fails to (re)install the typings files, run the following command to do so.
code-example(format=""). code-example(format="").
npm run typings install npm run typings install
:marked :marked
This command lists the installed typings files: Run this command to list the installed typings files:
code-example(format=""). code-example(format="").
npm run typings list npm run typings list
:marked :marked
The following command installs or updates the typings file for the Jasmine test library from the *DefinitelyTyped* repository 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. and updates the `typings.config` file so you receive it automatically the next time you install typings.
code-example(format=""). code-example(format="").
npm run typings -- install dt~jasmine --save --global npm run typings -- install dt~jasmine --save --global
.l-sub-section .l-sub-section
:marked :marked
The [&ndash;&ndash; option](https://docs.npmjs.com/cli/run-script) is important; 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.
it 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 h2(class="text-headline") Cross Platform
div(class="feature-row") div(class="feature-row")
div(class="feature") div(class="feature")
h3 Progressive Web Apps 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. p(class="text-body") Use modern web platform capabilities to deliver app-like experiences. High performance, offline, and zero-step installation.
div(class="feature") div(class="feature")
h3 Native h3 Native
@ -12,19 +12,19 @@ div
div(class="feature") div(class="feature")
h3 Desktop 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-row")
div(class="feature") div(class="feature")
h3 Code generation 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") div(class="feature")
h3 Universal 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") div(class="feature")
h3 Code Splitting 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. 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 h2(class="text-headline") Productivity
div(class="feature-row") 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. p(class="text-body") Command line tools: start building fast, add components and tests, then instantly deploy.
div(class="feature") div(class="feature")
h3 IDEs 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 h2(class="text-headline") Full Development Story
div(class="feature-row") div(class="feature-row")
div(class="feature") div(class="feature")
h3 Testing 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") div(class="feature")
h3 Animation 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") div(class="feature")
h3 Accessibility h3 Accessibility
p(class="text-body") Create accessible applications with ARIA-enabled components, developer guides, and built-in a11y test infrastructure. p(class="text-body") Create accessible applications with ARIA-enabled components, developer guides, and built-in a11y test infrastructure.