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

docs(aio): fix relative links 

The migrator was updated to automatically fix these links.
See fca5fb0280
and 3927b7a038

The result of this is that, going forward, we should ask
authors to include the path from the base href to the thing
being linked. E.g. guide/architecture#intro
This commit is contained in:
Peter Bacon Darwin 2017-03-11 15:36:40 +00:00 committed by Chuck Jazdzewski
parent 1847550ad1
commit ab40fcb068
47 changed files with 956 additions and 956 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
aio/content/guide/ajs-quick-reference.md
View File

@ -17,15 +17,15 @@ by mapping AngularJS syntax to the equivalent Angular syntax.
## Contents ## Contents
* [Template basics](#template-basics)—binding and local variables. * [Template basics](guide/ajs-quick-reference#template-basics)—binding and local variables.
* [Template directives](#template-directives)—built-in directives `ngIf` and `ngClass`. * [Template directives](guide/ajs-quick-reference#template-directives)—built-in directives `ngIf` and `ngClass`.
* [Filters/pipes](#filters-pipes)—built-in *filters*, known as *pipes* in Angular. * [Filters/pipes](guide/ajs-quick-reference#filters-pipes)—built-in *filters*, known as *pipes* in Angular.
* [Modules/controllers/components](#controllers-components)—*modules* in Angular are slightly different from *modules* in AngularJS, and *controllers* are *components* in Angular. * [Modules/controllers/components](guide/ajs-quick-reference#controllers-components)—*modules* in Angular are slightly different from *modules* in AngularJS, and *controllers* are *components* in Angular.
* [Style sheets](#style-sheets)—more options for CSS than in AngularJS. * [Style sheets](guide/ajs-quick-reference#style-sheets)—more options for CSS than in AngularJS.
## Template basics ## Template basics
Templates are the user-facing part of an Angular application and are written in HTML. Templates are the user-facing part of an Angular application and are written in HTML.
@ -86,8 +86,8 @@ The following table lists some of the key AngularJS template features with their
The context of the binding is implied and is always the The context of the binding is implied and is always the
associated component, so it needs no reference variable. associated component, so it needs no reference variable.
For more information, see the [Interpolation](../guide/template-syntax.html#interpolation) For more information, see the [Interpolation](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -117,7 +117,7 @@ The following table lists some of the key AngularJS template features with their
Many (but not all) of the built-in filters from AngularJS are Many (but not all) of the built-in filters from AngularJS are
built-in pipes in Angular. built-in pipes in Angular.
For more information, see [Filters/pipes](#filters-pipes) below. For more information, see [Filters/pipes](guide/ajs-quick-reference#filters-pipes) below.
</td> </td>
@ -145,8 +145,8 @@ The following table lists some of the key AngularJS template features with their
Angular has true template input variables that are explicitly defined using the `let` keyword. Angular has true template input variables that are explicitly defined using the `let` keyword.
For more information, see the [ngFor micro-syntax](../guide/template-syntax.html#microsyntax) For more information, see the [ngFor micro-syntax](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -155,7 +155,7 @@ The following table lists some of the key AngularJS template features with their
</table> </table>
[Back to top](#top) [Back to top](guide/ajs-quick-reference#top)
## Template directives ## Template directives
AngularJS provides more than seventy built-in directives for templates. AngularJS provides more than seventy built-in directives for templates.
@ -219,7 +219,7 @@ The following are some of the key AngularJS built-in directives and their equiva
in `main.ts` in `main.ts`
and the application's root component (`AppComponent`) in `app.module.ts`. and the application's root component (`AppComponent`) in `app.module.ts`.
For more information see the [Setup](../guide/setup.html) page. For more information see the [Setup](guide/setup) page.
</td> </td>
@ -262,8 +262,8 @@ The following are some of the key AngularJS built-in directives and their equiva
Angular also has **class binding**, which is a good way to add or remove a single class, Angular also has **class binding**, which is a good way to add or remove a single class,
as shown in the third example. as shown in the third example.
For more information see the [Attribute, class, and style bindings](../guide/template-syntax.html#other-bindings) For more information see the [Attribute, class, and style bindings](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -309,8 +309,8 @@ The following are some of the key AngularJS built-in directives and their equiva
For a list of DOM events, see: https://developer.mozilla.org/en-US/docs/Web/Events. For a list of DOM events, see: https://developer.mozilla.org/en-US/docs/Web/Events.
For more information, see the [Event binding](../guide/template-syntax.html#event-binding) For more information, see the [Event binding](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -340,7 +340,7 @@ The following are some of the key AngularJS built-in directives and their equiva
In Angular, the template no longer specifies its associated controller. In Angular, the template no longer specifies its associated controller.
Rather, the component specifies its associated template as part of the component class decorator. Rather, the component specifies its associated template as part of the component class decorator.
For more information, see [Architecture Overview](../guide/architecture.html#component). For more information, see [Architecture Overview](guide/architecture).
</td> </td>
@ -353,14 +353,14 @@ The following are some of the key AngularJS built-in directives and their equiva
<td> <td>
### ng-hide ### ng-hide
In AngularJS, the `ng-hide` directive shows or hides the associated HTML element based on In AngularJS, the `ng-hide` directive shows or hides the associated HTML element based on
an expression. For more information, see [ng-show](#ng-show). an expression. For more information, see [ng-show](guide/ajs-quick-reference#ng-show).
</td> </td>
<td> <td>
### Bind to the `hidden` property ### Bind to the `hidden` property
In Angular, you use property binding; there is no built-in *hide* directive. In Angular, you use property binding; there is no built-in *hide* directive.
For more information, see [ng-show](#ng-show). For more information, see [ng-show](guide/ajs-quick-reference#ng-show).
</td> </td>
@ -396,15 +396,15 @@ The following are some of the key AngularJS built-in directives and their equiva
Angular uses property binding; there is no built-in *href* directive. Angular uses property binding; there is no built-in *href* directive.
Place the element's `href` property in square brackets and set it to a quoted template expression. Place the element's `href` property in square brackets and set it to a quoted template expression.
For more information see the [Property binding](../guide/template-syntax.html#property-binding) For more information see the [Property binding](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
In Angular, `href` is no longer used for routing. Routing uses `routerLink`, as shown in the following example. In Angular, `href` is no longer used for routing. Routing uses `routerLink`, as shown in the following example.
{@example 'cb-ajs-quick-reference/ts/src/app/app.component.html' region='router-link'} {@example 'cb-ajs-quick-reference/ts/src/app/app.component.html' region='router-link'}
For more information on routing, see the [RouterLink binding](../guide/router.html#router-link) For more information on routing, see the [RouterLink binding](guide/router)
section of the [Routing & Navigation](../guide/router.html) page. section of the [Routing & Navigation](guide/router) page.
</td> </td>
@ -438,7 +438,7 @@ The following are some of the key AngularJS built-in directives and their equiva
In this example, the `<table>` element is removed from the DOM unless the `movies` array has a length. In this example, the `<table>` element is removed from the DOM unless the `movies` array has a length.
The (*) before `ngIf` is required in this example. The (*) before `ngIf` is required in this example.
For more information, see [Structural Directives](../guide/structural-directives.html). For more information, see [Structural Directives](guide/structural-directives).
</td> </td>
@ -468,7 +468,7 @@ The following are some of the key AngularJS built-in directives and their equiva
For more information on two-way binding with `ngModel`, see the [NgModel&mdash;Two-way binding to For more information on two-way binding with `ngModel`, see the [NgModel&mdash;Two-way binding to
form elements with `[(ngModel)]`](../guide/template-syntax.html#ngModel) form elements with `[(ngModel)]`](../guide/template-syntax.html#ngModel)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -505,7 +505,7 @@ The following are some of the key AngularJS built-in directives and their equiva
the `let` keyword identifies `movie` as an input variable; the `let` keyword identifies `movie` as an input variable;
the list preposition is `of`, not `in`. the list preposition is `of`, not `in`.
For more information, see [Structural Directives](../guide/structural-directives.html). For more information, see [Structural Directives](guide/structural-directives).
</td> </td>
@ -542,8 +542,8 @@ The following are some of the key AngularJS built-in directives and their equiva
In this example, the `<div>` element is hidden if the `favoriteHero` variable is not truthy. In this example, the `<div>` element is hidden if the `favoriteHero` variable is not truthy.
For more information on property binding, see the [Property binding](../guide/template-syntax.html#property-binding) For more information on property binding, see the [Property binding](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -572,8 +572,8 @@ The following are some of the key AngularJS built-in directives and their equiva
Angular uses property binding; there is no built-in *src* directive. Angular uses property binding; there is no built-in *src* directive.
Place the `src` property in square brackets and set it to a quoted template expression. Place the `src` property in square brackets and set it to a quoted template expression.
For more information on property binding, see the [Property binding](../guide/template-syntax.html#property-binding) For more information on property binding, see the [Property binding](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -608,11 +608,11 @@ The following are some of the key AngularJS built-in directives and their equiva
Angular also has **style binding**, which is good way to set a single style. This is shown in the second example. Angular also has **style binding**, which is good way to set a single style. This is shown in the second example.
For more information on style binding, see the [Style binding](../guide/template-syntax.html#style-binding) section of the For more information on style binding, see the [Style binding](guide/template-syntax) section of the
[Template Syntax](../guide/template-syntax.html) page. [Template Syntax](guide/template-syntax) page.
For more information on the `ngStyle` directive, see [NgStyle](../guide/template-syntax.html#ngStyle) For more information on the `ngStyle` directive, see [NgStyle](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -664,8 +664,8 @@ The following are some of the key AngularJS built-in directives and their equiva
The (*) before `ngSwitchCase` and `ngSwitchDefault` is required in this example. The (*) before `ngSwitchCase` and `ngSwitchDefault` is required in this example.
For more information, see [The NgSwitch directives](../guide/template-syntax.html#ngSwitch) For more information, see [The NgSwitch directives](guide/template-syntax)
section of the [Template Syntax](../guide/template-syntax.html) page. section of the [Template Syntax](guide/template-syntax) page.
</td> </td>
@ -674,7 +674,7 @@ The following are some of the key AngularJS built-in directives and their equiva
</table> </table>
[Back to top](#top) [Back to top](guide/ajs-quick-reference#top)
{@a filters-pipes} {@a filters-pipes}
@ -682,7 +682,7 @@ The following are some of the key AngularJS built-in directives and their equiva
## Filters/pipes ## Filters/pipes
Angular **pipes** provide formatting and transformation for data in the template, similar to AngularJS **filters**. Angular **pipes** provide formatting and transformation for data in the template, similar to AngularJS **filters**.
Many of the built-in filters in AngularJS have corresponding pipes in Angular. Many of the built-in filters in AngularJS have corresponding pipes in Angular.
For more information on pipes, see [Pipes](../guide/pipes.html). For more information on pipes, see [Pipes](guide/pipes).
<table width="100%"> <table width="100%">
@ -913,7 +913,7 @@ For more information on pipes, see [Pipes](../guide/pipes.html).
</table> </table>
[Back to top](#top) [Back to top](guide/ajs-quick-reference#top)
{@a controllers-components} {@a controllers-components}
@ -975,8 +975,8 @@ The Angular code is shown using TypeScript.
This is a nonissue in Angular because ES 2015 modules This is a nonissue in Angular because ES 2015 modules
handle the namespacing for you. handle the namespacing for you.
For more information on modules, see the [Modules](../guide/architecture.html#modules) section of the For more information on modules, see the [Modules](guide/architecture) section of the
[Architecture Overview](../guide/architecture.html). [Architecture Overview](guide/architecture).
</td> </td>
@ -1005,7 +1005,7 @@ The Angular code is shown using TypeScript.
- `imports`: specifies the list of other modules that this module depends upon - `imports`: specifies the list of other modules that this module depends upon
- `declaration`: keeps track of your components, pipes, and directives. - `declaration`: keeps track of your components, pipes, and directives.
For more information on modules, see [Angular Modules (NgModule)](../guide/ngmodule.html). For more information on modules, see [Angular Modules (NgModule)](guide/ngmodule).
</td> </td>
@ -1043,8 +1043,8 @@ The Angular code is shown using TypeScript.
This is how you associate a template with logic, which is defined in the component class. This is how you associate a template with logic, which is defined in the component class.
For more information, see the [Components](../guide/architecture.html#components) For more information, see the [Components](guide/architecture)
section of the [Architecture Overview](../guide/architecture.html) page. section of the [Architecture Overview](guide/architecture) page.
</td> </td>
@ -1073,8 +1073,8 @@ The Angular code is shown using TypeScript.
NOTE: If you are using TypeScript with AngularJS, you must use the `export` keyword to export the component class. NOTE: If you are using TypeScript with AngularJS, you must use the `export` keyword to export the component class.
For more information, see the [Components](../guide/architecture.html#components) For more information, see the [Components](guide/architecture)
section of the [Architecture Overview](../guide/architecture.html) page. section of the [Architecture Overview](guide/architecture) page.
</td> </td>
@ -1108,8 +1108,8 @@ The Angular code is shown using TypeScript.
This example injects a `MovieService`. This example injects a `MovieService`.
The first parameter's TypeScript type tells Angular what to inject, even after minification. The first parameter's TypeScript type tells Angular what to inject, even after minification.
For more information, see the [Dependency injection](../guide/architecture.html#dependency-injection) For more information, see the [Dependency injection](guide/architecture)
section of the [Architecture Overview](../guide/architecture.html). section of the [Architecture Overview](guide/architecture).
</td> </td>
@ -1118,7 +1118,7 @@ The Angular code is shown using TypeScript.
</table> </table>
[Back to top](#top) [Back to top](guide/ajs-quick-reference#top)
{@a style-sheets} {@a style-sheets}
@ -1192,4 +1192,4 @@ also encapsulate a style sheet within a specific component.
</table> </table>
[Back to top](#top) [Back to top](guide/ajs-quick-reference#top)

20
aio/content/guide/animations.md
View File

@ -30,16 +30,16 @@ add it to your page.
# Contents # Contents
* [Example: Transitioning between two states](#example-transitioning-between-states). * [Example: Transitioning between two states](guide/animations#example-transitioning-between-states).
* [States and transitions](#states-and-transitions). * [States and transitions](guide/animations#states-and-transitions).
* [Example: Entering and leaving](#example-entering-and-leaving). * [Example: Entering and leaving](guide/animations#example-entering-and-leaving).
* [Example: Entering and leaving from different states](#example-entering-and-leaving-from-different-states). * [Example: Entering and leaving from different states](guide/animations#example-entering-and-leaving-from-different-states).
* [Animatable properties and units](#animatable-properties-and-units). * [Animatable properties and units](guide/animations#animatable-properties-and-units).
* [Automatic property calculation](#automatic-property-calculation). * [Automatic property calculation](guide/animations#automatic-property-calculation).
* [Animation timing](#animation-timing). * [Animation timing](guide/animations#animation-timing).
* [Multi-step animations with keyframes](#multi-step-animations-with-keyframes). * [Multi-step animations with keyframes](guide/animations#multi-step-animations-with-keyframes).
* [Parallel animation groups](#parallel-animation-groups). * [Parallel animation groups](guide/animations#parallel-animation-groups).
* [Animation callbacks](#animation-callbacks). * [Animation callbacks](guide/animations#animation-callbacks).
The examples in this page are available as a <live-example></live-example>. The examples in this page are available as a <live-example></live-example>.

30
aio/content/guide/aot-compiler.md
View File

@ -11,16 +11,16 @@ during a build process.
{@a toc} {@a toc}
## Table of Contents ## Table of Contents
* [Overview](#overview) * [Overview](guide/aot-compiler#overview)
* [_Ahead-of-Time_ vs _Just-in-Time_](#aot-jit) * [_Ahead-of-Time_ vs _Just-in-Time_](guide/aot-compiler#aot-jit)
* [Compile with AOT](#compile) * [Compile with AOT](guide/aot-compiler#compile)
* [Bootstrap](#bootstrap) * [Bootstrap](guide/aot-compiler#bootstrap)
* [Tree Shaking](#tree-shaking) * [Tree Shaking](guide/aot-compiler#tree-shaking)
* [Load the bundle](#load) * [Load the bundle](guide/aot-compiler#load)
* [Serve the app](#serve) * [Serve the app](guide/aot-compiler#serve)
* [Workflow and convenience script](#workflow) * [Workflow and convenience script](guide/aot-compiler#workflow)
* [Source Code](#source-code) * [Source Code](guide/aot-compiler#source-code)
* [Tour of Heroes](#toh) * [Tour of Heroes](guide/aot-compiler#toh)
{@a overview} {@a overview}
@ -128,7 +128,7 @@ then modify it to look as follows.
The `compilerOptions` section is unchanged except for one property. The `compilerOptions` section is unchanged except for one property.
**Set the `module` to `es2015`**. **Set the `module` to `es2015`**.
This is important as explained later in the [Tree Shaking](#tree-shaking) section. This is important as explained later in the [Tree Shaking](guide/aot-compiler#tree-shaking) section.
What's really new is the `ngc` section at the bottom called `angularCompilerOptions`. What's really new is the `ngc` section at the bottom called `angularCompilerOptions`.
Its `"genDir"` property tells the compiler Its `"genDir"` property tells the compiler
@ -198,7 +198,7 @@ The AOT path changes application bootstrapping.
Instead of bootstrapping `AppModule`, you bootstrap the application with the generated module factory, `AppModuleNgFactory`. Instead of bootstrapping `AppModule`, you bootstrap the application with the generated module factory, `AppModuleNgFactory`.
Make a copy of `main.ts` and name it `main-jit.ts`. Make a copy of `main.ts` and name it `main-jit.ts`.
This is the JIT version; set it aside as you may need it [later](#run-jit "Running with JIT"). This is the JIT version; set it aside as you may need it [later](guide/aot-compiler#run-jit "Running with JIT").
Open `main.ts` and convert it to AOT compilation. Open `main.ts` and convert it to AOT compilation.
Switch from the `platformBrowserDynamic.bootstrap` used in JIT compilation to Switch from the `platformBrowserDynamic.bootstrap` used in JIT compilation to
@ -408,7 +408,7 @@ The same source code can be built both ways. Here's one way to do that.
{@example 'cb-aot-compiler/ts/src/index-jit.html' region='jit'} {@example 'cb-aot-compiler/ts/src/index-jit.html' region='jit'}
Notice the slight change to the `system.import` which now specifies `src/app/main-jit`. Notice the slight change to the `system.import` which now specifies `src/app/main-jit`.
That's the JIT version of the bootstrap file that we preserved [above](#bootstrap) That's the JIT version of the bootstrap file that we preserved [above](guide/aot-compiler#bootstrap)
Open a _different_ terminal window and enter. Open a _different_ terminal window and enter.
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
npm start npm start
@ -434,7 +434,7 @@ Now you can develop JIT and AOT, side-by-side.
The sample above is a trivial variation of the QuickStart app. The sample above is a trivial variation of the QuickStart app.
In this section you apply what you've learned about AOT compilation and Tree Shaking In this section you apply what you've learned about AOT compilation and Tree Shaking
to an app with more substance, the tutorial [_Tour of Heroes_](../tutorial/toh-pt6.html). to an app with more substance, the tutorial [_Tour of Heroes_](tutorial/toh-pt6).
### JIT in development, AOT in production ### JIT in development, AOT in production
@ -472,7 +472,7 @@ It does not need `SystemJS`, so that script is absent from its `index.html`
***main.ts*** ***main.ts***
JIT and AOT applications boot in much the same way but require different Angular libraries to do so. JIT and AOT applications boot in much the same way but require different Angular libraries to do so.
The key differences, covered in the [Bootstrap](#bootstrap) section above, The key differences, covered in the [Bootstrap](guide/aot-compiler#bootstrap) section above,
are evident in these `main` files which can and should reside in the same folder: are evident in these `main` files which can and should reside in the same folder:
<md-tab-group> <md-tab-group>

14
aio/content/guide/appmodule.md
View File

@ -7,17 +7,17 @@ Tell Angular how to construct and bootstrap the app in the root "AppModule".
@description @description
An Angular module class describes how the application parts fit together. An Angular module class describes how the application parts fit together.
Every application has at least one Angular module, the _root_ module Every application has at least one Angular module, the _root_ module
that you [bootstrap](#main) to launch the application. that you [bootstrap](guide/appmodule#main) to launch the application.
You can call it anything you want. The conventional name is `AppModule`. You can call it anything you want. The conventional name is `AppModule`.
The [setup](setup.html) instructions produce a new project with the following minimal `AppModule`. The [setup](guide/setup) instructions produce a new project with the following minimal `AppModule`.
You'll evolve this module as your application grows. You'll evolve this module as your application grows.
{@example 'setup/ts/src/app/app.module.ts'} {@example 'setup/ts/src/app/app.module.ts'}
After the `import` statements, you come to a class adorned with the After the `import` statements, you come to a class adorned with the
**`@NgModule`** [_decorator_](glossary.html#decorator '"Decorator" explained'). **`@NgModule`** [_decorator_](guide/glossary).
The `@NgModule` decorator identifies `AppModule` as an Angular module class (also called an `NgModule` class). The `@NgModule` decorator identifies `AppModule` as an Angular module class (also called an `NgModule` class).
`@NgModule` takes a _metadata_ object that tells Angular how to compile and launch the application. `@NgModule` takes a _metadata_ object that tells Angular how to compile and launch the application.
@ -26,7 +26,7 @@ The `@NgModule` decorator identifies `AppModule` as an Angular module class (als
* **_declarations_** &mdash; the application's lone component, which is also ... * **_declarations_** &mdash; the application's lone component, which is also ...
* **_bootstrap_** &mdash; the _root_ component that Angular creates and inserts into the `index.html` host web page. * **_bootstrap_** &mdash; the _root_ component that Angular creates and inserts into the `index.html` host web page.
The [Angular Modules (NgModule)](ngmodule.html) guide dives deeply into the details of Angular modules. The [Angular Modules (NgModule)](guide/ngmodule) guide dives deeply into the details of Angular modules.
All you need to know at the moment is a few basics about these three properties. All you need to know at the moment is a few basics about these three properties.
@ -76,7 +76,7 @@ You must declare _every_ component in an `NgModule` class.
If you use a component without declaring it, you'll see a clear error message in the browser console. If you use a component without declaring it, you'll see a clear error message in the browser console.
You'll learn to create two other kinds of classes &mdash; You'll learn to create two other kinds of classes &mdash;
[directives](attribute-directives.html) and [pipes](pipes.html) &mdash; [directives](guide/attribute-directives) and [pipes](guide/pipes) &mdash;
that you must also add to the `declarations` array. that you must also add to the `declarations` array.
@ -93,7 +93,7 @@ Do not put any other kind of class in `declarations`; _not_ `NgModule` classes,
{@a bootstrap-array} {@a bootstrap-array}
### The _bootstrap_ array ### The _bootstrap_ array
You launch the application by [_bootstrapping_](#main) the root `AppModule`. You launch the application by [_bootstrapping_](guide/appmodule#main) the root `AppModule`.
Among other things, the _bootstrapping_ process creates the component(s) listed in the `bootstrap` array Among other things, the _bootstrapping_ process creates the component(s) listed in the `bootstrap` array
and inserts each one into the browser DOM. and inserts each one into the browser DOM.
@ -154,4 +154,4 @@ As your app grows, you'll consider subdividing it into multiple "feature" module
some of which can be loaded later ("lazy loaded") if and when the user chooses some of which can be loaded later ("lazy loaded") if and when the user chooses
to visit those features. to visit those features.
When you're ready to explore these possibilities, visit the [Angular Modules (NgModule)](ngmodule.html) guide. When you're ready to explore these possibilities, visit the [Angular Modules (NgModule)](guide/ngmodule) guide.

72
aio/content/guide/architecture.md
View File

@ -22,14 +22,14 @@ You'll learn the details in the pages that follow. For now, focus on the big pic
The architecture diagram identifies the eight main building blocks of an Angular application: The architecture diagram identifies the eight main building blocks of an Angular application:
* [Modules](#modules) * [Modules](guide/architecture#modules)
* [Components](#components) * [Components](guide/architecture#components)
* [Templates](#templates) * [Templates](guide/architecture#templates)
* [Metadata](#metadata) * [Metadata](guide/architecture#metadata)
* [Data binding](#data-binding) * [Data binding](guide/architecture#data-binding)
* [Directives](#directives) * [Directives](guide/architecture#directives)
* [Services](#services) * [Services](guide/architecture#services)
* [Dependency injection](#dependency-injection) * [Dependency injection](guide/architecture#dependency-injection)
Learn these building blocks, and you're on your way. Learn these building blocks, and you're on your way.
@ -78,7 +78,7 @@ For example, this `HeroListComponent` has a `heroes` property that returns !{_an
that it acquires from a service. that it acquires from a service.
`HeroListComponent` also has a `selectHero()` method that sets a `selectedHero` property when the user clicks to choose a hero from that list. `HeroListComponent` also has a `selectHero()` method that sets a `selectedHero` property when the user clicks to choose a hero from that list.
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.
Your app 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](guide/lifecycle-hooks), like `ngOnInit()` declared above.
<div class='l-hr'> <div class='l-hr'>
@ -99,7 +99,7 @@ template for our `HeroListComponent`:
{@example 'architecture/ts/src/app/hero-list.component.html'} {@example 'architecture/ts/src/app/hero-list.component.html'}
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). 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](guide/template-syntax).
In the last line of the template, the `<hero-detail>` tag is a custom element that represents a new component, `HeroDetailComponent`. In the last line of the template, the `<hero-detail>` tag is a custom element that represents a new component, `HeroDetailComponent`.
@ -126,7 +126,7 @@ Notice how `<hero-detail>` rests comfortably among native HTML elements. Custom
</figure> </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 class="l-clear-both">[Looking back at the code](#component-code) for `HeroListComponent`, you can see that it's just a class. <br class="l-clear-both">[Looking back at the code](guide/architecture#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, `HeroListComponent` really is *just a class*. It's not a component until you *tell Angular about it*. In fact, `HeroListComponent` really is *just a class*. It's not a component until you *tell Angular about it*.
@ -144,7 +144,7 @@ where it finds a `<hero-list>` tag in *parent* HTML.
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`: module-relative address of this component's HTML template, shown [above](#templates). - `templateUrl`: module-relative address of this component's HTML template, shown [above](guide/architecture#templates).
- `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 the 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. so it can get the list of heroes to display.
@ -178,14 +178,14 @@ 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.
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.
As the diagram shows, there are four forms of data binding syntax. Each form has a direction &mdash; to the DOM, from the DOM, or in both directions.<br class="l-clear-both">The `HeroListComponent` [example](#templates) template has three forms: As the diagram shows, there are four forms of data binding syntax. Each form has a direction &mdash; to the DOM, from the DOM, or in both directions.<br class="l-clear-both">The `HeroListComponent` [example](guide/architecture#templates) template has three forms:
* The `{{hero.name}}` [*interpolation*](displaying-data.html#interpolation) * The `{{hero.name}}` [*interpolation*](guide/displaying-data)
displays the component's `hero.name` property value within the `<li>` element. displays the component's `hero.name` property value within the `<li>` element.
* The `[hero]` [*property binding*](template-syntax.html#property-binding) passes the value of `selectedHero` from * The `[hero]` [*property binding*](guide/template-syntax) passes the value of `selectedHero` from
the parent `HeroListComponent` to the `hero` property of the child `HeroDetailComponent`. the parent `HeroListComponent` to the `hero` property of the child `HeroDetailComponent`.
* The `(click)` [*event binding*](user-input.html#click) calls the component's `selectHero` method when the user clicks a hero's name. * The `(click)` [*event binding*](guide/user-input) calls the component's `selectHero` method when the user clicks a hero's name.
**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.
@ -234,9 +234,9 @@ sometimes by name but more often as the target of an assignment or a binding.
**Structural** directives alter layout by adding, removing, and replacing elements in DOM. **Structural** directives alter layout by adding, removing, and replacing elements in DOM.
The [example template](#templates) uses two built-in structural directives: The [example template](guide/architecture#templates) uses two built-in structural directives:
* [`*ngFor`](displaying-data.html#ngFor) tells Angular to stamp out one `<li>` per hero in the `heroes` list. * [`*ngFor`](guide/displaying-data) tells Angular to stamp out one `<li>` per hero in the `heroes` list.
* [`*ngIf`](displaying-data.html#ngIf) includes the `HeroDetail` component only if a selected hero exists. * [`*ngIf`](guide/displaying-data) includes the `HeroDetail` component only if a selected hero exists.
**Attribute** directives alter the appearance or behavior of an existing element. **Attribute** directives alter the appearance or behavior of an existing element.
In templates they look like regular HTML attributes, hence the name. In templates they look like regular HTML attributes, hence the name.
@ -245,9 +245,9 @@ an example of an attribute directive. `ngModel` modifies the behavior of
an existing element (typically an `<input>`) an existing element (typically an `<input>`)
by setting its display value property and responding to change events. by setting its display value property and responding to change events.
Angular has a few more 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](guide/template-syntax))
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](guide/template-syntax) and [ngClass](guide/template-syntax)).
Of course, you can also write your 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.
@ -336,7 +336,7 @@ 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) page. --> The full story is in the [dependency injection](guide/dependency-injection) page. -->
Points to remember about dependency injection: Points to remember about dependency injection:
@ -359,14 +359,14 @@ Points to remember about dependency injection:
You've learned the basics 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:
* [Modules](#modules) * [Modules](guide/architecture#modules)
* [Components](#components) * [Components](guide/architecture#components)
* [Templates](#templates) * [Templates](guide/architecture#templates)
* [Metadata](#metadata) * [Metadata](guide/architecture#metadata)
* [Data binding](#data-binding) * [Data binding](guide/architecture#data-binding)
* [Directives](#directives) * [Directives](guide/architecture#directives)
* [Services](#services) * [Services](guide/architecture#services)
* [Dependency injection](#dependency-injection) * [Dependency injection](guide/architecture#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.
@ -375,7 +375,7 @@ 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 documentation (or soon will be). Most of them are covered in this documentation (or soon will be).
> [**Animations**](animations.html): Animate component behavior > [**Animations**](guide/animations): Animate component behavior
without deep knowledge of animation techniques or CSS with Angular's animation library. without deep knowledge of animation techniques or CSS with Angular's animation library.
> **Change detection**: The change detection documentation will cover how Angular decides that a component property value has changed, > **Change detection**: The change detection documentation will cover how Angular decides that a component property value has changed,
@ -384,18 +384,18 @@ when to update the screen, and how it uses **zones** to intercept asynchronous a
> **Events**: The events documentation will cover how to use components and services to raise events with 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**](guide/forms): 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**](guide/server-communication): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client.
> [**Lifecycle hooks**](lifecycle-hooks.html): Tap into key moments in the lifetime of a component, from its creation to its destruction, > [**Lifecycle hooks**](guide/lifecycle-hooks): 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): Use pipes in your templates to improve the user experience by transforming values for display. Consider this `currency` pipe expression: > [**Pipes**](guide/pipes): Use pipes in your templates to improve the user experience by transforming values for display. Consider this `currency` pipe expression:
> >
> > `price | currency:'USD':true` > > `price | currency:'USD':true`
> >
> It displays a price of 42.33 as `$42.33`. > It displays a price of 42.33 as `$42.33`.
> [**Router**](router.html): Navigate from page to page within the client > [**Router**](guide/router): Navigate from page to page within the client
application and never leave the browser. application and never leave the browser.

36
aio/content/guide/attribute-directives.md
View File

@ -9,12 +9,12 @@ An **Attribute** directive changes the appearance or behavior of a DOM element.
# Contents # Contents
* [Directives overview](#directive-overview) * [Directives overview](guide/attribute-directives#directive-overview)
* [Build a simple attribute directive](#write-directive) * [Build a simple attribute directive](guide/attribute-directives#write-directive)
* [Apply the attribute directive to an element in a template](#apply-directive) * [Apply the attribute directive to an element in a template](guide/attribute-directives#apply-directive)
* [Respond to user-initiated events](#respond-to-user) * [Respond to user-initiated events](guide/attribute-directives#respond-to-user)
* [Pass values into the directive with an _@Input_ data binding](#bindings) * [Pass values into the directive with an _@Input_ data binding](guide/attribute-directives#bindings)
* [Bind to a second property](#second-property) * [Bind to a second property](guide/attribute-directives#second-property)
Try the <live-example title="Attribute Directive example"></live-example>. Try the <live-example title="Attribute Directive example"></live-example>.
@ -27,15 +27,15 @@ There are three kinds of directives in Angular:
1. Attribute directives&mdash;change the appearance or behavior of an element, component, or another directive. 1. Attribute directives&mdash;change the appearance or behavior of an element, component, or another directive.
*Components* are the most common of the three directives. *Components* are the most common of the three directives.
You saw a component for the first time in the [QuickStart](../quickstart.html) guide. You saw a component for the first time in the [QuickStart](quickstart) guide.
*Structural Directives* change the structure of the view. *Structural Directives* change the structure of the view.
Two examples are [NgFor](template-syntax.html#ngFor) and [NgIf](template-syntax.html#ngIf). Two examples are [NgFor](guide/template-syntax) and [NgIf](guide/template-syntax).
Learn about them in the [Structural Directives](structural-directives.html) guide. Learn about them in the [Structural Directives](guide/structural-directives) guide.
*Attribute directives* are used as attributes of elements. *Attribute directives* are used as attributes of elements.
The built-in [NgStyle](template-syntax.html#ngStyle) directive in the The built-in [NgStyle](guide/template-syntax) directive in the
[Template Syntax](template-syntax.html) guide, for example, [Template Syntax](guide/template-syntax) guide, for example,
can change several element styles at the same time. can change several element styles at the same time.
## Build a simple attribute directive ## Build a simple attribute directive
@ -50,7 +50,7 @@ directive to set an element's background color
when the user hovers over that element. You can apply it like this: when the user hovers over that element. You can apply it like this:
### Write the directive code ### Write the directive code
Follow the [setup](setup.html) instructions for creating a new local project Follow the [setup](guide/setup) instructions for creating a new local project
named <span ngio-ex>attribute-directives</span>. named <span ngio-ex>attribute-directives</span>.
Create the following source file in the indicated folder: Create the following source file in the indicated folder:
@ -61,7 +61,7 @@ Create the following source file in the indicated folder:
The `import` statement specifies symbols from the Angular `core`: The `import` statement specifies symbols from the Angular `core`:
1. `Directive` provides the functionality of the `@Directive` decorator. 1. `Directive` provides the functionality of the `@Directive` decorator.
1. `ElementRef` [injects](dependency-injection.html) into the directive's constructor 1. `ElementRef` [injects](guide/dependency-injection) into the directive's constructor
so the code can access the DOM element. so the code can access the DOM element.
1. `Input` allows data to flow from the binding expression into the directive. 1. `Input` allows data to flow from the binding expression into the directive.
@ -195,7 +195,7 @@ Start by adding a `highlightColor` property to the directive class like this:
Notice the `@Input` !{_decorator}. It adds metadata to the class that makes the directive's `highlightColor` property available for binding. Notice the `@Input` !{_decorator}. It adds metadata to the class that makes the directive's `highlightColor` property available for binding.
It's called an *input* property because data flows from the binding expression _into_ the directive. It's called an *input* property because data flows from the binding expression _into_ the directive.
Without that input metadata, Angular rejects the binding; see [below](#why-input "Why add @Input?") for more about that. Without that input metadata, Angular rejects the binding; see [below](guide/attribute-directives#why-input "Why add @Input?") for more about that.
Try it by adding the following directive binding variations to the `AppComponent` template: Try it by adding the following directive binding variations to the `AppComponent` template:
Add a `color` property to the `AppComponent`. Add a `color` property to the `AppComponent`.
@ -268,10 +268,10 @@ Here's how the harness should work when you're done coding.
This page covered how to: This page covered how to:
- [Build an **attribute directive**](#write-directive) that modifies the behavior of an element. - [Build an **attribute directive**](guide/attribute-directives#write-directive) that modifies the behavior of an element.
- [Apply the directive](#apply-directive) to an element in a template. - [Apply the directive](guide/attribute-directives#apply-directive) to an element in a template.
- [Respond to **events**](#respond-to-user) that change the directive's behavior. - [Respond to **events**](guide/attribute-directives#respond-to-user) that change the directive's behavior.
- [**Bind** values to the directive](#bindings). - [**Bind** values to the directive](guide/attribute-directives#bindings).
The final source code follows: The final source code follows:

12
aio/content/guide/browser-support.md
View File

@ -307,7 +307,7 @@ These are the polyfills required to run an Angular application on each supported
<td> <td>
[ES6](#core-es6) [ES6](guide/browser-support#core-es6)
</td> </td>
@ -322,7 +322,7 @@ These are the polyfills required to run an Angular application on each supported
<td> <td>
[ES6<br>classList](#classlist) [ES6<br>classList](guide/browser-support#classlist)
</td> </td>
@ -370,7 +370,7 @@ Here are the features which may require additional polyfills:
<td> <td>
[Web Animations](#web-animations) [Web Animations](guide/browser-support#web-animations)
</td> </td>
@ -390,7 +390,7 @@ Here are the features which may require additional polyfills:
<td> <td>
[Intl API](#intl) [Intl API](guide/browser-support#intl)
</td> </td>
@ -410,7 +410,7 @@ Here are the features which may require additional polyfills:
<td> <td>
[classList](#classlist) [classList](guide/browser-support#classlist)
</td> </td>
@ -430,7 +430,7 @@ Here are the features which may require additional polyfills:
<td> <td>
[Typed&nbsp;Array](#typedarray) <br>[Blob](#blob)<br>[FormData](#formdata) [Typed&nbsp;Array](guide/browser-support#typedarray) <br>[Blob](guide/browser-support#blob)<br>[FormData](guide/browser-support#formdata)
</td> </td>

86
aio/content/guide/cb-dependency-injection.md
View File

@ -9,41 +9,41 @@ Dependency Injection is a powerful pattern for managing code dependencies.
In this cookbook we will explore many of the features of Dependency Injection (DI) in Angular. In this cookbook we will explore many of the features of Dependency Injection (DI) in Angular.
<a id="toc"></a>## Table of contents <a id="toc"></a>## Table of contents
[Application-wide dependencies](#app-wide-dependencies) [Application-wide dependencies](guide/cb-dependency-injection#app-wide-dependencies)
[External module configuration](#external-module-configuration) [External module configuration](guide/cb-dependency-injection#external-module-configuration)
[*@Injectable* and nested service dependencies](#nested-dependencies) [*@Injectable* and nested service dependencies](guide/cb-dependency-injection#nested-dependencies)
[Limit service scope to a component subtree](#service-scope) [Limit service scope to a component subtree](guide/cb-dependency-injection#service-scope)
[Multiple service instances (sandboxing)](#multiple-service-instances) [Multiple service instances (sandboxing)](guide/cb-dependency-injection#multiple-service-instances)
[Qualify dependency lookup with *@Optional* and *@Host*](#qualify-dependency-lookup) [Qualify dependency lookup with *@Optional* and *@Host*](guide/cb-dependency-injection#qualify-dependency-lookup)
[Inject the component's DOM element](#component-element) [Inject the component's DOM element](guide/cb-dependency-injection#component-element)
[Define dependencies with providers](#providers) [Define dependencies with providers](guide/cb-dependency-injection#providers)
* [The *provide* object literal](#provide) * [The *provide* object literal](guide/cb-dependency-injection#provide)
* [useValue - the *value provider*](#usevalue) * [useValue - the *value provider*](guide/cb-dependency-injection#usevalue)
* [useClass - the *class provider*](#useclass) * [useClass - the *class provider*](guide/cb-dependency-injection#useclass)
* [useExisting - the *alias provider*](#useexisting) * [useExisting - the *alias provider*](guide/cb-dependency-injection#useexisting)
* [useFactory - the *factory provider*](#usefactory) * [useFactory - the *factory provider*](guide/cb-dependency-injection#usefactory)
[Provider token alternatives](#tokens) [Provider token alternatives](guide/cb-dependency-injection#tokens)
* [class-interface](#class-interface) * [class-interface](guide/cb-dependency-injection#class-interface)
* [OpaqueToken](#opaque-token) * [OpaqueToken](guide/cb-dependency-injection#opaque-token)
[Inject into a derived class](#di-inheritance) [Inject into a derived class](guide/cb-dependency-injection#di-inheritance)
[Find a parent component by injection](#find-parent) [Find a parent component by injection](guide/cb-dependency-injection#find-parent)
* [Find parent with a known component type](#known-parent) * [Find parent with a known component type](guide/cb-dependency-injection#known-parent)
* [Cannot find a parent by its base class](#base-parent) * [Cannot find a parent by its base class](guide/cb-dependency-injection#base-parent)
* [Find a parent by its class-interface](#class-interface-parent) * [Find a parent by its class-interface](guide/cb-dependency-injection#class-interface-parent)
* [Find a parent in a tree of parents (*@SkipSelf*)](#parent-tree) * [Find a parent in a tree of parents (*@SkipSelf*)](guide/cb-dependency-injection#parent-tree)
* [A *provideParent* helper function](#provideparent) * [A *provideParent* helper function](guide/cb-dependency-injection#provideparent)
[Break circularities with a forward class reference (*forwardRef*)](#forwardref) [Break circularities with a forward class reference (*forwardRef*)](guide/cb-dependency-injection#forwardref)
**See the <live-example name="cb-dependency-injection"></live-example>** **See the <live-example name="cb-dependency-injection"></live-example>**
of the code supporting this cookbook. of the code supporting this cookbook.
@ -62,7 +62,7 @@ Service classes can act as their own providers which is why listing them in the
is all the registration we need. is all the registration we need.
A *provider* is something that can create or deliver a service. A *provider* is something that can create or deliver a service.
Angular creates a service instance from a class provider by "new-ing" it. Angular creates a service instance from a class provider by "new-ing" it.
Learn more about providers [below](#providers).Now that we've registered these services, Learn more about providers [below](guide/cb-dependency-injection#providers).Now that we've registered these services,
Angular can inject them into the constructor of *any* component or service, *anywhere* in the application. Angular can inject them into the constructor of *any* component or service, *anywhere* in the application.
{@example 'cb-dependency-injection/ts/src/app/hero-bios.component.ts' region='ctor'} {@example 'cb-dependency-injection/ts/src/app/hero-bios.component.ts' region='ctor'}
@ -79,7 +79,7 @@ We do this when (a) we expect the service to be injectable everywhere
or (b) we must configure another application global service _before it starts_. or (b) we must configure another application global service _before it starts_.
We see an example of the second case here, where we configure the Component Router with a non-default We see an example of the second case here, where we configure the Component Router with a non-default
[location strategy](../guide/router.html#location-strategy) by listing its provider [location strategy](guide/router) by listing its provider
in the `providers` list of the `AppModule`. in the `providers` list of the `AppModule`.
@ -264,7 +264,7 @@ But when this component is projected into a *parent* component, that parent comp
We look at this second, more interesting case in our next example. We look at this second, more interesting case in our next example.
### Demonstration ### Demonstration
The `HeroBiosAndContactsComponent` is a revision of the `HeroBiosComponent` that we looked at [above](#hero-bios-component). The `HeroBiosAndContactsComponent` is a revision of the `HeroBiosComponent` that we looked at [above](guide/cb-dependency-injection#hero-bios-component).
{@example 'cb-dependency-injection/ts/src/app/hero-bios.component.ts' region='hero-bios-and-contacts'} {@example 'cb-dependency-injection/ts/src/app/hero-bios.component.ts' region='hero-bios-and-contacts'}
@ -325,7 +325,7 @@ Although we strive to avoid it, many visual effects and 3rd party tools (such as
require DOM access. require DOM access.
To illustrate, we've written a simplified version of the `HighlightDirective` from To illustrate, we've written a simplified version of the `HighlightDirective` from
the [Attribute Directives](../guide/attribute-directives.html) chapter. the [Attribute Directives](guide/attribute-directives) chapter.
{@example 'cb-dependency-injection/ts/src/app/highlight.directive.ts'} {@example 'cb-dependency-injection/ts/src/app/highlight.directive.ts'}
@ -371,7 +371,7 @@ If it doesn't, it may be able to make one with the help of a ***provider***.
A *provider* is a recipe for delivering a service associated with a *token*. A *provider* is a recipe for delivering a service associated with a *token*.
If the injector doesn't have a provider for the requested *token*, it delegates the request If the injector doesn't have a provider for the requested *token*, it delegates the request
to its parent injector, where the process repeats until there are no more injectors. to its parent injector, where the process repeats until there are no more injectors.
If the search is futile, the injector throws an error ... unless the request was [optional](#optional). If the search is futile, the injector throws an error ... unless the request was [optional](guide/cb-dependency-injection#optional).
Let's return our attention to providers themselves.A new injector has no providers. Let's return our attention to providers themselves.A new injector has no providers.
Angular initializes the injectors it creates with some providers it cares about. Angular initializes the injectors it creates with some providers it cares about.
@ -408,7 +408,7 @@ It's visually simple: a few properties and the output of a logger. The code behi
#### The *provide* object literal #### The *provide* object literal
The `provide` object literal takes a *token* and a *definition object*. The `provide` object literal takes a *token* and a *definition object*.
The *token* is usually a class but [it doesn't have to be](#tokens). The *token* is usually a class but [it doesn't have to be](guide/cb-dependency-injection#tokens).
The *definition* object has one main property, (e.g. `useValue`) that indicates how the provider The *definition* object has one main property, (e.g. `useValue`) that indicates how the provider
should create or return the provided value. should create or return the provided value.
@ -433,7 +433,7 @@ The `Hero` provider token is a class which makes sense because the value is a `H
and the consumer of the injected hero would want the type information. and the consumer of the injected hero would want the type information.
The `TITLE` provider token is *not a class*. The `TITLE` provider token is *not a class*.
It's a special kind of provider lookup key called an [OpaqueToken](#opaquetoken). It's a special kind of provider lookup key called an [OpaqueToken](guide/cb-dependency-injection#opaquetoken).
We often use an `OpaqueToken` when the dependency is a simple value like a string, a number, or a function. We often use an `OpaqueToken` when the dependency is a simple value like a string, a number, or a function.
The value of a *value provider* must be defined *now*. We can't create the value later. The value of a *value provider* must be defined *now*. We can't create the value later.
@ -486,7 +486,7 @@ creating ***two ways to access the same service object***.
Narrowing an API through an aliasing interface is _one_ important use case for this technique. Narrowing an API through an aliasing interface is _one_ important use case for this technique.
We're aliasing for that very purpose here. We're aliasing for that very purpose here.
Imagine that the `LoggerService` had a large API (it's actually only three methods and a property). Imagine that the `LoggerService` had a large API (it's actually only three methods and a property).
We want to shrink that API surface to just the two members exposed by the `MinimalLogger` [*class-interface*](#class-interface): We want to shrink that API surface to just the two members exposed by the `MinimalLogger` [*class-interface*](guide/cb-dependency-injection#class-interface):
{@example 'cb-dependency-injection/ts/src/app/date-logger.service.ts' region='minimal-logger'} {@example 'cb-dependency-injection/ts/src/app/date-logger.service.ts' region='minimal-logger'}
@ -718,7 +718,7 @@ after injecting an `AlexComponent` into her constructor:
{@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='cathy'} {@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='cathy'}
We added the [@Optional](#optional) qualifier for safety but We added the [@Optional](guide/cb-dependency-injection#optional) qualifier for safety but
the <live-example name="cb-dependency-injection"></live-example> the <live-example name="cb-dependency-injection"></live-example>
confirms that the `alex` parameter is set. confirms that the `alex` parameter is set.
@ -741,7 +741,7 @@ That's not possible because TypeScript interfaces disappear from the transpiled
which doesn't support interfaces. There's no artifact we could look for.We're not claiming this is good design. which doesn't support interfaces. There's no artifact we could look for.We're not claiming this is good design.
We are asking *can a component inject its parent via the parent's base class*? We are asking *can a component inject its parent via the parent's base class*?
The sample's `CraigComponent` explores this question. [Looking back](#alex) The sample's `CraigComponent` explores this question. [Looking back](guide/cb-dependency-injection#alex)
we see that the `Alex` component *extends* (*inherits*) from a class named `Base`. we see that the `Alex` component *extends* (*inherits*) from a class named `Base`.
{@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='alex-class-signature'} {@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='alex-class-signature'}
@ -758,14 +758,14 @@ confirms that the `alex` parameter is null.
<a id="class-interface-parent"></a> <a id="class-interface-parent"></a>
### Find a parent by its class-interface ### Find a parent by its class-interface
We can find a parent component with a [class-interface](#class-interface). We can find a parent component with a [class-interface](guide/cb-dependency-injection#class-interface).
The parent must cooperate by providing an *alias* to itself in the name of a *class-interface* token. The parent must cooperate by providing an *alias* to itself in the name of a *class-interface* token.
Recall that Angular always adds a component instance to its own injector; Recall that Angular always adds a component instance to its own injector;
that's why we could inject *Alex* into *Cathy* [earlier](#known-parent). that's why we could inject *Alex* into *Cathy* [earlier](guide/cb-dependency-injection#known-parent).
We write an [*alias provider*](#useexisting) &mdash; a `provide` object literal with a `useExisting` definition &mdash; We write an [*alias provider*](guide/cb-dependency-injection#useexisting) &mdash; a `provide` object literal with a `useExisting` definition &mdash;
that creates an *alternative* way to inject the same component instance that creates an *alternative* way to inject the same component instance
and add that provider to the `providers` array of the `@Component` metadata for the `AlexComponent`: and add that provider to the `providers` array of the `@Component` metadata for the `AlexComponent`:
@ -774,8 +774,8 @@ and add that provider to the `providers` array of the `@Component` metadata for
{@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='alex-providers'} {@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='alex-providers'}
[Parent](#parent-token) is the provider's *class-interface* token. [Parent](guide/cb-dependency-injection#parent-token) is the provider's *class-interface* token.
The [*forwardRef*](#forwardref) breaks the circular reference we just created by having the `AlexComponent` refer to itself. The [*forwardRef*](guide/cb-dependency-injection#forwardref) breaks the circular reference we just created by having the `AlexComponent` refer to itself.
*Carol*, the third of *Alex*'s child components, injects the parent into its `parent` parameter, the same way we've done it before: *Carol*, the third of *Alex*'s child components, injects the parent into its `parent` parameter, the same way we've done it before:
@ -802,8 +802,8 @@ Here's *Barry*:
{@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='barry'} {@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='barry'}
*Barry*'s `providers` array looks just like [*Alex*'s](#alex-providers). *Barry*'s `providers` array looks just like [*Alex*'s](guide/cb-dependency-injection#alex-providers).
If we're going to keep writing [*alias providers*](#useexisting) like this we should create a [helper function](#provideparent). If we're going to keep writing [*alias providers*](guide/cb-dependency-injection#useexisting) like this we should create a [helper function](guide/cb-dependency-injection#provideparent).
For now, focus on *Barry*'s constructor: For now, focus on *Barry*'s constructor:
<md-tab-group> <md-tab-group>
@ -841,7 +841,7 @@ Here's *Alice*, *Barry* and family in action:
{@a parent-token} {@a parent-token}
### The *Parent* class-interface ### The *Parent* class-interface
We [learned earlier](#class-interface) that a *class-interface* is an abstract class used as an interface rather than as a base class. We [learned earlier](guide/cb-dependency-injection#class-interface) that a *class-interface* is an abstract class used as an interface rather than as a base class.
Our example defines a `Parent` *class-interface* . Our example defines a `Parent` *class-interface* .
@ -870,7 +870,7 @@ It doesn't in this example *only* to demonstrate that the code will compile and
### A *provideParent* helper function ### A *provideParent* helper function
Writing variations of the same parent *alias provider* gets old quickly, Writing variations of the same parent *alias provider* gets old quickly,
especially this awful mouthful with a [*forwardRef*](#forwardref): especially this awful mouthful with a [*forwardRef*](guide/cb-dependency-injection#forwardref):
{@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='alex-providers'} {@example 'cb-dependency-injection/ts/src/app/parent-finder.component.ts' region='alex-providers'}

42
aio/content/guide/change-log.md
View File

@ -13,7 +13,7 @@ Now you can download the sample code for any guide and run it locally.
Look for the new download links next to the "live example" links. Look for the new download links next to the "live example" links.
## Template Syntax/Structural Directives: refreshed (2017-02-06) ## Template Syntax/Structural Directives: refreshed (2017-02-06)
The [_Template-Syntax_](template-syntax.html) and [_Structural Directives_](structural-directives.html) The [_Template-Syntax_](guide/template-syntax) and [_Structural Directives_](guide/structural-directives)
guides were significantly revised for clarity, accuracy, and current recommended practices. guides were significantly revised for clarity, accuracy, and current recommended practices.
Discusses `<ng-container>`. Discusses `<ng-container>`.
Revised samples are more clear and cover all topics discussed. Revised samples are more clear and cover all topics discussed.
@ -38,43 +38,43 @@ Notably:
* Added `lite-server` configuration (`bs-config.json`) to serve `src/`. * Added `lite-server` configuration (`bs-config.json`) to serve `src/`.
## NEW: Reactive Forms guide (2017-01-31) ## NEW: Reactive Forms guide (2017-01-31)
The new [**Reactive Forms**](reactive-forms.html) guide explains how and why to build a "reactive form". The new [**Reactive Forms**](guide/reactive-forms) guide explains how and why to build a "reactive form".
"Reactive Forms" are the code-based counterpart to the declarative "Template Driven" forms approach "Reactive Forms" are the code-based counterpart to the declarative "Template Driven" forms approach
introduced in the [Forms](forms.html) guide. introduced in the [Forms](guide/forms) guide.
Check it out before you decide how to add forms to your app. Check it out before you decide how to add forms to your app.
Remember also that you can use both techniques in the same app, Remember also that you can use both techniques in the same app,
choosing the approach that best fits each scenario. choosing the approach that best fits each scenario.
## NEW: Deployment guide (2017-01-30) ## NEW: Deployment guide (2017-01-30)
The new [Deployment](deployment.html) guide describes techniques for putting your application on a server. The new [Deployment](guide/deployment) guide describes techniques for putting your application on a server.
It includes important advice on optimizing for production. It includes important advice on optimizing for production.
## Hierarchical Dependency Injection: refreshed (2017-01-13) ## Hierarchical Dependency Injection: refreshed (2017-01-13)
[Hierarchical Dependency Injection](hierarchical-dependency-injection.html) guide is significantly revised. [Hierarchical Dependency Injection](guide/hierarchical-dependency-injection) guide is significantly revised.
Closes issue #3086. Closes issue #3086.
Revised samples are clearer and cover all topics discussed. Revised samples are clearer and cover all topics discussed.
## Miscellaneous (2017-01-05) ## Miscellaneous (2017-01-05)
* [Setup](setup.html) guide: * [Setup](guide/setup) guide:
added (optional) instructions on how to remove _non-essential_ files. added (optional) instructions on how to remove _non-essential_ files.
* No longer consolidate RxJS operator imports in `rxjs-extensions` file; each file should import what it needs. * No longer consolidate RxJS operator imports in `rxjs-extensions` file; each file should import what it needs.
* All samples prepend template/style URLs with `./` as a best practice. * All samples prepend template/style URLs with `./` as a best practice.
* [Style Guide](style-guide.html): copy edits and revised rules. * [Style Guide](guide/style-guide): copy edits and revised rules.
## Router: more detail (2016-12-21) ## Router: more detail (2016-12-21)
Added more information to the [Router](router.html) guide Added more information to the [Router](guide/router) guide
including sections named outlets, wildcard routes, and preload strategies. including sections named outlets, wildcard routes, and preload strategies.
## HTTP: how to set default request headers (and other request options) (2016-12-14) ## HTTP: how to set default request headers (and other request options) (2016-12-14)
Added section on how to set default request headers (and other request options) to Added section on how to set default request headers (and other request options) to
[HTTP](server-communication.html#override-default-request-options) guide. [HTTP](guide/server-communication) guide.
## Testing: added component test plunkers (2016-12-02) ## Testing: added component test plunkers (2016-12-02)
Added two plunkers that each test _one simple component_ so you can write a component test plunker of your own: <live-example name="setup" plnkr="quickstart-specs">one</live-example> for the QuickStart seed's `AppComponent` and <live-example name="testing" plnkr="banner-specs">another</live-example> for the Testing guide's `BannerComponent`. Added two plunkers that each test _one simple component_ so you can write a component test plunker of your own: <live-example name="setup" plnkr="quickstart-specs">one</live-example> for the QuickStart seed's `AppComponent` and <live-example name="testing" plnkr="banner-specs">another</live-example> for the Testing guide's `BannerComponent`.
Linked to these plunkers in [Testing](testing.html#live-examples) and [Setup anatomy](setup-systemjs-anatomy) guides. Linked to these plunkers in [Testing](guide/testing) and [Setup anatomy](guide/setup-systemjs-anatomy) guides.
## Internationalization: pluralization and _select_ (2016-11-30) ## Internationalization: pluralization and _select_ (2016-11-30)
The [Internationalization (i18n)](../cookbook/i18n.html) guide explains how to handle pluralization and The [Internationalization (i18n)](cookbook/i18n) guide explains how to handle pluralization and
translation of alternative texts with `select`. translation of alternative texts with `select`.
The sample demonstrates these features too. The sample demonstrates these features too.
@ -86,7 +86,7 @@ see quickstart issue: [angular/quickstart#294](https://github.com/angular/quicks
## QuickStart Rewrite (2016-11-18) ## QuickStart Rewrite (2016-11-18)
The QuickStart is completely rewritten so that it actually is quick. The QuickStart is completely rewritten so that it actually is quick.
It references a minimal "Hello Angular" app running in Plunker. It references a minimal "Hello Angular" app running in Plunker.
The new [Setup](setup.html) page tells you how to install a local development environment The new [Setup](guide/setup) page tells you how to install a local development environment
by downloading (or cloning) the QuickStart github repository. by downloading (or cloning) the QuickStart github repository.
You are no longer asked to copy-and-paste code into setup files that were not explained anyway. You are no longer asked to copy-and-paste code into setup files that were not explained anyway.
@ -94,14 +94,14 @@ You are no longer asked to copy-and-paste code into setup files that were not ex
Docs and code samples updated and tested with Angular v.2.2.0. Docs and code samples updated and tested with Angular v.2.2.0.
## UPDATE: NgUpgrade Guide for the AOT friendly _upgrade/static_ module (2016-11-14) ## UPDATE: NgUpgrade Guide for the AOT friendly _upgrade/static_ module (2016-11-14)
The updated [NgUpgrade Guide](upgrade.html) guide covers the The updated [NgUpgrade Guide](guide/upgrade) guide covers the
new AOT friendly `upgrade/static` module new AOT friendly `upgrade/static` module
released in v.2.2.0, which is the recommended released in v.2.2.0, which is the recommended
facility for migrating from AngularJS to Angular. facility for migrating from AngularJS to Angular.
The documentation for the version prior to v.2.2.0 has been removed. The documentation for the version prior to v.2.2.0 has been removed.
## ES6 described in "TypeScript to JavaScript" (2016-11-14) ## ES6 described in "TypeScript to JavaScript" (2016-11-14)
The updated [TypeScript to JavaScript](../cookbook/ts-to-js.html) cookbook The updated [TypeScript to JavaScript](cookbook/ts-to-js) cookbook
now explains how to write apps in ES6/7 now explains how to write apps in ES6/7
by translating the common idioms in the TypeScript documentation examples by translating the common idioms in the TypeScript documentation examples
(and elsewhere on the web) to ES6/7 and ES5. (and elsewhere on the web) to ES6/7 and ES5.
@ -114,7 +114,7 @@ Documentation samples now get TypeScript type information for 3rd party librarie
from npm `@types` packages rather than with the _typings_ tooling. from npm `@types` packages rather than with the _typings_ tooling.
The `typings.json` file is gone. The `typings.json` file is gone.
The [AngularJS Upgrade](upgrade.html) guide reflects this change. The [AngularJS Upgrade](guide/upgrade) guide reflects this change.
The `package.json` installs `@types/angular` and several `@types/angular-...` The `package.json` installs `@types/angular` and several `@types/angular-...`
packages in support of upgrade; these are not needed for pure Angular development. packages in support of upgrade; these are not needed for pure Angular development.
@ -138,7 +138,7 @@ New `:enter` and `:leave` aliases make animation more natural.
Docs and code samples updated and tested with Angular v.2.1.0. Docs and code samples updated and tested with Angular v.2.1.0.
## NEW "Ahead of time (AOT) Compilation" cookbook (2016-10-11) ## NEW "Ahead of time (AOT) Compilation" cookbook (2016-10-11)
The NEW [Ahead of time (AOT) Compilation](../cookbook/aot-compiler.html) cookbook The NEW [Ahead of time (AOT) Compilation](cookbook/aot-compiler) cookbook
explains what AOT compilation is and why you'd want it. explains what AOT compilation is and why you'd want it.
It demonstrates the basics with a QuickStart app It demonstrates the basics with a QuickStart app
followed by the more advanced considerations of compiling and bundling the Tour of Heroes. followed by the more advanced considerations of compiling and bundling the Tour of Heroes.
@ -147,17 +147,17 @@ followed by the more advanced considerations of compiling and bundling the Tour
Docs and code samples updated and tested with Angular v.2.0.2. Docs and code samples updated and tested with Angular v.2.0.2.
## "Routing and Navigation" guide with the _Router Module_ (2016-10-5) ## "Routing and Navigation" guide with the _Router Module_ (2016-10-5)
The [Routing and Navigation](router.html) guide now locates route configuration The [Routing and Navigation](guide/router) guide now locates route configuration
in a _Routing Module_. in a _Routing Module_.
The _Routing Module_ replaces the previous _routing object_ involving the `ModuleWithProviders`. The _Routing Module_ replaces the previous _routing object_ involving the `ModuleWithProviders`.
All guided samples with routing use the _Routing Module_ and prose content has been updated, All guided samples with routing use the _Routing Module_ and prose content has been updated,
most conspicuously in the most conspicuously in the
[NgModule](ngmodule.html) guide and [NgModule FAQ](../cookbook/ngmodule-faq.html) cookbook. [NgModule](guide/ngmodule) guide and [NgModule FAQ](cookbook/ngmodule-faq) cookbook.
## New "Internationalization" Cookbook (2016-09-30) ## New "Internationalization" Cookbook (2016-09-30)
Added a new [Internationalization (i18n)](../cookbook/i18n.html) cookbook that shows how Added a new [Internationalization (i18n)](cookbook/i18n) cookbook that shows how
to use Angular "i18n" facilities to translate template text into multiple languages. to use Angular "i18n" facilities to translate template text into multiple languages.
## "angular-in-memory-web-api" package rename (2016-09-27) ## "angular-in-memory-web-api" package rename (2016-09-27)
@ -171,7 +171,7 @@ The new "angular-in-memory-web-api" has new features.
## "Style Guide" with _NgModules_ (2016-09-27) ## "Style Guide" with _NgModules_ (2016-09-27)
[StyleGuide](style-guide.html) explains recommended conventions for Angular modules (NgModule). [StyleGuide](guide/style-guide) explains recommended conventions for Angular modules (NgModule).
Barrels now are far less useful and have been removed from the style guide; Barrels now are far less useful and have been removed from the style guide;
they remain valuable but are not a matter of Angular style. they remain valuable but are not a matter of Angular style.
Also relaxed the rule that discouraged use of the `@Component.host` property. Also relaxed the rule that discouraged use of the `@Component.host` property.
@ -187,5 +187,5 @@ modules with SystemJS as the samples currently do.
## "Lifecycle Hooks" guide simplified (2016-09-24) ## "Lifecycle Hooks" guide simplified (2016-09-24)
The [Lifecycle Hooks](lifecycle-hooks.html) guide is shorter, simpler, and The [Lifecycle Hooks](guide/lifecycle-hooks) guide is shorter, simpler, and
draws more attention to the order in which Angular calls the hooks. draws more attention to the order in which Angular calls the hooks.

38
aio/content/guide/component-communication.md
View File

@ -9,25 +9,25 @@ Share information between different directives and components.
in which two or more components share information. in which two or more components share information.
<a id="toc"></a>## Table of contents <a id="toc"></a>## Table of contents
[Pass data from parent to child with input binding](#parent-to-child) [Pass data from parent to child with input binding](guide/component-communication#parent-to-child)
[Intercept input property changes with a setter](#parent-to-child-setter) [Intercept input property changes with a setter](guide/component-communication#parent-to-child-setter)
[Intercept input property changes with *ngOnChanges*](#parent-to-child-on-changes) [Intercept input property changes with *ngOnChanges*](guide/component-communication#parent-to-child-on-changes)
[Parent listens for child event](#child-to-parent) [Parent listens for child event](guide/component-communication#child-to-parent)
[Parent interacts with child via a *local variable*](#parent-to-child-local-var) [Parent interacts with child via a *local variable*](guide/component-communication#parent-to-child-local-var)
[Parent calls a *ViewChild*](#parent-to-view-child) [Parent calls a *ViewChild*](guide/component-communication#parent-to-view-child)
[Parent and children communicate via a service](#bidirectional-service) [Parent and children communicate via a service](guide/component-communication#bidirectional-service)
**See the <live-example name="cb-component-communication"></live-example>**. **See the <live-example name="cb-component-communication"></live-example>**.
<a id="parent-to-child"></a>## Pass data from parent to child with input binding <a id="parent-to-child"></a>## Pass data from parent to child with input binding
`HeroChildComponent` has two ***input properties***, `HeroChildComponent` has two ***input properties***,
typically adorned with [@Input decorations](../guide/template-syntax.html#inputs-outputs). typically adorned with [@Input decorations](guide/template-syntax).
{@example 'cb-component-communication/ts/src/app/hero-child.component.ts'} {@example 'cb-component-communication/ts/src/app/hero-child.component.ts'}
@ -54,7 +54,7 @@ E2E test that all children were instantiated and displayed as expected:
{@example 'cb-component-communication/e2e-spec.ts' region='parent-to-child'} {@example 'cb-component-communication/e2e-spec.ts' region='parent-to-child'}
[Back to top](#top) [Back to top](guide/component-communication#top)
<a id="parent-to-child-setter"></a>## Intercept input property changes with a setter <a id="parent-to-child-setter"></a>## Intercept input property changes with a setter
@ -83,14 +83,14 @@ E2E tests of input property setter with empty and non-empty names:
{@example 'cb-component-communication/e2e-spec.ts' region='parent-to-child-setter'} {@example 'cb-component-communication/e2e-spec.ts' region='parent-to-child-setter'}
[Back to top](#top) [Back to top](guide/component-communication#top)
<a id="parent-to-child-on-changes"></a>## Intercept input property changes with *ngOnChanges* <a id="parent-to-child-on-changes"></a>## Intercept input property changes with *ngOnChanges*
Detect and act upon changes to input property values with the `ngOnChanges` method of the `OnChanges` lifecycle hook interface. Detect and act upon changes to input property values with the `ngOnChanges` method of the `OnChanges` lifecycle hook interface.
May prefer this approach to the property setter when watching multiple, interacting input properties. May prefer this approach to the property setter when watching multiple, interacting input properties.
Learn about `ngOnChanges` in the [LifeCycle Hooks](../guide/lifecycle-hooks.html) chapter.This `VersionChildComponent` detects changes to the `major` and `minor` input properties and composes a log message reporting these changes: Learn about `ngOnChanges` in the [LifeCycle Hooks](guide/lifecycle-hooks) chapter.This `VersionChildComponent` detects changes to the `major` and `minor` input properties and composes a log message reporting these changes:
{@example 'cb-component-communication/ts/src/app/version-child.component.ts'} {@example 'cb-component-communication/ts/src/app/version-child.component.ts'}
@ -114,7 +114,7 @@ the expected `ngOnChanges` calls and values:
{@example 'cb-component-communication/e2e-spec.ts' region='parent-to-child-onchanges'} {@example 'cb-component-communication/e2e-spec.ts' region='parent-to-child-onchanges'}
[Back to top](#top) [Back to top](guide/component-communication#top)
<a id="child-to-parent"></a>## Parent listens for child event <a id="child-to-parent"></a>## Parent listens for child event
@ -122,7 +122,7 @@ The child component exposes an `EventEmitter` property with which it `emits` eve
The parent binds to that event property and reacts to those events. The parent binds to that event property and reacts to those events.
The child's `EventEmitter` property is an ***output property***, The child's `EventEmitter` property is an ***output property***,
typically adorned with an [@Output decoration](../guide/template-syntax.html#inputs-outputs) typically adorned with an [@Output decoration](guide/template-syntax)
as seen in this `VoterComponent`: as seen in this `VoterComponent`:
@ -150,7 +150,7 @@ Test that clicking the *Agree* and *Disagree* buttons update the appropriate cou
{@example 'cb-component-communication/e2e-spec.ts' region='child-to-parent'} {@example 'cb-component-communication/e2e-spec.ts' region='child-to-parent'}
[Back to top](#top) [Back to top](guide/component-communication#top)
## Parent interacts with child via *local variable* ## Parent interacts with child via *local variable*
@ -200,7 +200,7 @@ Test also that clicking the *Stop* button pauses the countdown timer:
{@example 'cb-component-communication/e2e-spec.ts' region='countdown-timer-tests'} {@example 'cb-component-communication/e2e-spec.ts' region='countdown-timer-tests'}
[Back to top](#top) [Back to top](guide/component-communication#top)
<a id="parent-to-view-child"></a>## Parent calls a *ViewChild* <a id="parent-to-view-child"></a>## Parent calls a *ViewChild*
@ -214,9 +214,9 @@ must read or write child component values or must call child component methods.
When the parent component *class* requires that kind of access, When the parent component *class* requires that kind of access,
we ***inject*** the child component into the parent as a *ViewChild*. we ***inject*** the child component into the parent as a *ViewChild*.
We'll illustrate this technique with the same [Countdown Timer](#countdown-timer-example) example. We'll illustrate this technique with the same [Countdown Timer](guide/component-communication#countdown-timer-example) example.
We won't change its appearance or behavior. We won't change its appearance or behavior.
The child [CountdownTimerComponent](#countdown-timer-example) is the same as well. The child [CountdownTimerComponent](guide/component-communication#countdown-timer-example) is the same as well.
We are switching from the *local variable* to the *ViewChild* technique We are switching from the *local variable* to the *ViewChild* technique
solely for the purpose of demonstration.Here is the parent, `CountdownViewChildParentComponent`: solely for the purpose of demonstration.Here is the parent, `CountdownViewChildParentComponent`:
@ -248,7 +248,7 @@ We use `setTimeout` to wait one tick and then revise the `seconds` method so
that it takes future values from the timer component. that it takes future values from the timer component.
### Test it ### Test it
Use [the same countdown timer tests](#countdown-tests) as before.[Back to top](#top) Use [the same countdown timer tests](guide/component-communication#countdown-tests) as before.[Back to top](guide/component-communication#top)
<a id="bidirectional-service"></a>## Parent and children communicate via a service <a id="bidirectional-service"></a>## Parent and children communicate via a service
@ -298,4 +298,4 @@ and verify that the *History* meets expectations:
{@example 'cb-component-communication/e2e-spec.ts' region='bidirectional-service'} {@example 'cb-component-communication/e2e-spec.ts' region='bidirectional-service'}
[Back to top](#top) [Back to top](guide/component-communication#top)

8
aio/content/guide/component-relative-paths.md
View File

@ -33,7 +33,7 @@ It would be much easier to write and maintain our application components if we c
We can if we build our application as `commonjs` modules and load those modules We can if we build our application as `commonjs` modules and load those modules
with a suitable package loader such as `systemjs` or `webpack`. with a suitable package loader such as `systemjs` or `webpack`.
Learn why [below](#why-default). Learn why [below](guide/component-relative-paths#why-default).
The Angular CLI uses these technologies and defaults to the The Angular CLI uses these technologies and defaults to the
*component-relative path* approach described here. *component-relative path* approach described here.
@ -98,7 +98,7 @@ The result looks like this:
~~~ {.alert.is-helpful} ~~~ {.alert.is-helpful}
Webpack users may prefer [an alternative approach](#webpack). Webpack users may prefer [an alternative approach](guide/component-relative-paths#webpack).
~~~ ~~~
@ -189,6 +189,6 @@ properties that reference *component-relative URLS.
{@example 'webpack/ts/src/app/app.component.ts'} {@example 'webpack/ts/src/app/app.component.ts'}
Webpack will do a `require` behind the scenes to load the templates and styles. Read more [here](../guide/webpack.html#highlights). Webpack will do a `require` behind the scenes to load the templates and styles. Read more [here](guide/webpack).
See the [Introduction to Webpack](../guide/webpack.html). See the [Introduction to Webpack](guide/webpack).

16
aio/content/guide/component-styles.md
View File

@ -16,12 +16,12 @@ This page describes how to load and apply these component styles.
## Table Of Contents ## Table Of Contents
* [Using component styles](#using-component-styles) * [Using component styles](guide/component-styles#using-component-styles)
* [Special selectors](#special-selectors) * [Special selectors](guide/component-styles#special-selectors)
* [Loading styles into components](#loading-styles) * [Loading styles into components](guide/component-styles#loading-styles)
* [Controlling view encapsulation: native, emulated, and none](#view-encapsulation) * [Controlling view encapsulation: native, emulated, and none](guide/component-styles#view-encapsulation)
* [Appendix 1: Inspecting the CSS generated in emulated view encapsulation](#inspect-generated-css) * [Appendix 1: Inspecting the CSS generated in emulated view encapsulation](guide/component-styles#inspect-generated-css)
* [Appendix 2: Loading styles with relative URLs](#relative-urls) * [Appendix 2: Loading styles with relative URLs](guide/component-styles#relative-urls)
You can run the <live-example></live-example> in Plunker and download the code from there. You can run the <live-example></live-example> in Plunker and download the code from there.
@ -120,7 +120,7 @@ The `/deep/` selector also has the alias `>>>`. You can use either interchangeab
Use the `/deep/` and `>>>` selectors only with *emulated* view encapsulation. Use the `/deep/` and `>>>` selectors only with *emulated* view encapsulation.
Emulated is the default and most commonly used view encapsulation. For more information, see the Emulated is the default and most commonly used view encapsulation. For more information, see the
[Controlling view encapsulation](#view-encapsulation) section. [Controlling view encapsulation](guide/component-styles#view-encapsulation) section.
~~~ ~~~
@ -201,7 +201,7 @@ Choose from the following modes:
view inside that shadow DOM. The component's styles are included within the shadow DOM. view inside that shadow DOM. The component's styles are included within the shadow DOM.
* `Emulated` view encapsulation (the default) emulates the behavior of shadow DOM by preprocessing * `Emulated` view encapsulation (the default) emulates the behavior of shadow DOM by preprocessing
(and renaming) the CSS code to effectively scope the CSS to the component's view. (and renaming) the CSS code to effectively scope the CSS to the component's view.
For details, see [Appendix 1](#inspect-generated-css). For details, see [Appendix 1](guide/component-styles#inspect-generated-css).
* `None` means that Angular does no view encapsulation. * `None` means that Angular does no view encapsulation.
Angular adds the CSS to the global styles. Angular adds the CSS to the global styles.
The scoping rules, isolations, and protections discussed earlier don't apply. The scoping rules, isolations, and protections discussed earlier don't apply.

40
aio/content/guide/dependency-injection.md
View File

@ -11,13 +11,13 @@ we really can't build an Angular application without it.
It's used so widely that almost everyone just calls it _DI_. It's used so widely that almost everyone just calls it _DI_.
In this chapter we'll learn what DI is and why we want it. In this chapter we'll learn what DI is and why we want it.
Then we'll learn [how to use it](#angular-di) in an Angular app. Then we'll learn [how to use it](guide/dependency-injection#angular-di) in an Angular app.
- [Why dependency injection?](#why-dependency-injection) - [Why dependency injection?](guide/dependency-injection#why-dependency-injection)
- [Angular dependency injection](#angular-dependency-injection) - [Angular dependency injection](guide/dependency-injection#angular-dependency-injection)
- [Injector providers](#injector-providers) - [Injector providers](guide/dependency-injection#injector-providers)
- [Dependency injection tokens](#dependency-injection-tokens) - [Dependency injection tokens](guide/dependency-injection#dependency-injection-tokens)
- [Summary](#summary) - [Summary](guide/dependency-injection#summary)
Run the <live-example></live-example>. Run the <live-example></live-example>.
@ -170,7 +170,7 @@ That sounds nice. What does it do for us when building components in Angular?
Let's see, one step at a time. Let's see, one step at a time.
We'll begin with a simplified version of the `HeroesComponent` We'll begin with a simplified version of the `HeroesComponent`
that we built in the [The Tour of Heroes](../tutorial/). that we built in the [The Tour of Heroes](tutorial/).
<md-tab-group> <md-tab-group>
@ -219,7 +219,7 @@ write the service code in its own file.
Our `HeroService` exposes a `getHeroes` method that returns Our `HeroService` exposes a `getHeroes` method that returns
the same mock data as before, but none of its consumers need to know that. the same mock data as before, but none of its consumers need to know that.
Notice the `@Injectable()` #{_decorator} above the service class. Notice the `@Injectable()` #{_decorator} above the service class.
We'll discuss its purpose [shortly](#injectable). We'll discuss its purpose [shortly](guide/dependency-injection#injectable).
We aren't even pretending this is a real service. We aren't even pretending this is a real service.
If we were actually getting data from a remote server, the API would have to be If we were actually getting data from a remote server, the API would have to be
@ -239,7 +239,7 @@ We don't have to create an Angular injector.
Angular creates an application-wide injector for us during the bootstrap process. Angular creates an application-wide injector for us during the bootstrap process.
We do have to configure the injector by registering the **providers** We do have to configure the injector by registering the **providers**
that create the services our application requires. that create the services our application requires.
We'll explain what [providers](#providers) are later in this chapter. We'll explain what [providers](guide/dependency-injection#providers) are later in this chapter.
### Registering providers in a component ### Registering providers in a component
Here's a revised `HeroesComponent` that registers the `HeroService`. Here's a revised `HeroesComponent` that registers the `HeroService`.
@ -251,7 +251,7 @@ Here's a revised `HeroesComponent` that registers the `HeroService`.
The `HeroListComponent` should get heroes from the injected `HeroService`. The `HeroListComponent` should get heroes from the injected `HeroService`.
Per the dependency injection pattern, the component must ask for the service in its Per the dependency injection pattern, the component must ask for the service in its
constructor, [as we explained earlier](#ctor-injection). constructor, [as we explained earlier](guide/dependency-injection#ctor-injection).
It's a small change: It's a small change:
<md-tab-group> <md-tab-group>
@ -301,10 +301,10 @@ would be explicitly created:
{@example 'dependency-injection/ts/src/app/car/car-injector.ts' region='injector-create-and-call'} {@example 'dependency-injection/ts/src/app/car/car-injector.ts' region='injector-create-and-call'}
We won't find code like that in the Tour of Heroes or any of our other samples. We won't find code like that in the Tour of Heroes or any of our other samples.
We *could* write code that [explicitly creates an injector](#explicit-injector) if we *had* to, but we rarely do. We *could* write code that [explicitly creates an injector](guide/dependency-injection#explicit-injector) if we *had* to, but we rarely do.
Angular takes care of creating and calling injectors Angular takes care of creating and calling injectors
when it creates components for us &mdash; whether through HTML markup, as in `<hero-list></hero-list>`, when it creates components for us &mdash; whether through HTML markup, as in `<hero-list></hero-list>`,
or after navigating to a component with the [router](./router.html). or after navigating to a component with the [router](guide/router).
If we let Angular do its job, we'll enjoy the benefits of automated dependency injection. If we let Angular do its job, we'll enjoy the benefits of automated dependency injection.
### Singleton services ### Singleton services
@ -314,7 +314,7 @@ In our example, a single `HeroService` instance is shared among the
However, Angular DI is an hierarchical injection However, Angular DI is an hierarchical injection
system, which means that nested injectors can create their own service instances. system, which means that nested injectors can create their own service instances.
Learn more about that in the [Hierarchical Injectors](./hierarchical-dependency-injection.html) chapter. Learn more about that in the [Hierarchical Injectors](guide/hierarchical-dependency-injection) chapter.
### Testing the component ### Testing the component
We emphasized earlier that designing a class for dependency injection makes the class easier to test. We emphasized earlier that designing a class for dependency injection makes the class easier to test.
@ -327,7 +327,7 @@ under test:
{@example 'dependency-injection/ts/src/app/test.component.ts' region='spec'} {@example 'dependency-injection/ts/src/app/test.component.ts' region='spec'}
Learn more in [Testing](./testing.html). Learn more in [Testing](guide/testing).
### When the service needs a service ### When the service needs a service
Our `HeroService` is very simple. It doesn't have any dependencies of its own. Our `HeroService` is very simple. It doesn't have any dependencies of its own.
@ -453,7 +453,7 @@ We wrote the `providers` #{_array} like this:
{@example 'dependency-injection/ts/src/app/providers.component.ts' region='providers-3'} {@example 'dependency-injection/ts/src/app/providers.component.ts' region='providers-3'}
The first is the [token](#token) that serves as the key for both locating a dependency value The first is the [token](guide/dependency-injection#token) that serves as the key for both locating a dependency value
and registering the provider. and registering the provider.
The second is a !{_secondParam}, The second is a !{_secondParam},
@ -528,8 +528,8 @@ which makes this object play the logger role.
{@example 'dependency-injection/ts/src/app/providers.component.ts' region='providers-7'} {@example 'dependency-injection/ts/src/app/providers.component.ts' region='providers-7'}
See more `useValue` examples in the See more `useValue` examples in the
[Non-class dependencies](#non-class-dependencies) and [Non-class dependencies](guide/dependency-injection#non-class-dependencies) and
[OpaqueToken](#opaquetoken) sections. [OpaqueToken](guide/dependency-injection#opaquetoken) sections.
<div id='factory-provider'> <div id='factory-provider'>
@ -583,7 +583,7 @@ We inject both the `Logger` and the `UserService` into the factory provider and
The `useFactory` field tells Angular that the provider is a factory function The `useFactory` field tells Angular that the provider is a factory function
whose implementation is the `heroServiceFactory`. whose implementation is the `heroServiceFactory`.
The `deps` property is #{_an} #{_array} of [provider tokens](#token). The `deps` property is #{_an} #{_array} of [provider tokens](guide/dependency-injection#token).
The `Logger` and `UserService` classes serve as tokens for their own class providers. The `Logger` and `UserService` classes serve as tokens for their own class providers.
The injector resolves these tokens and injects the corresponding services into the matching factory function parameters. The injector resolves these tokens and injects the corresponding services into the matching factory function parameters.
Notice that we captured the factory provider in #{_an} #{exportedvar}, `heroServiceProvider`. Notice that we captured the factory provider in #{_an} #{exportedvar}, `heroServiceProvider`.
@ -647,7 +647,7 @@ This is especially convenient when we consider that most dependency values are p
{@example 'dependency-injection/ts/src/app/app.config.ts' region='config'} {@example 'dependency-injection/ts/src/app/app.config.ts' region='config'}
We'd like to make this configuration object available for injection. We'd like to make this configuration object available for injection.
We know we can register an object with a [value provider](#value-provider). We know we can register an object with a [value provider](guide/dependency-injection#value-provider).
### OpaqueToken ### OpaqueToken
One solution to choosing a provider token for non-class dependencies is One solution to choosing a provider token for non-class dependencies is
@ -700,7 +700,7 @@ adding a parameter to a constructor.
Angular dependency injection is more capable than we've described. Angular dependency injection is more capable than we've described.
We can learn more about its advanced features, beginning with its support for We can learn more about its advanced features, beginning with its support for
nested injectors, in the nested injectors, in the
[Hierarchical Dependency Injection](hierarchical-dependency-injection.html) chapter. [Hierarchical Dependency Injection](guide/hierarchical-dependency-injection) chapter.
## Appendix: Working with injectors directly ## Appendix: Working with injectors directly

76
aio/content/guide/deployment.md
View File

@ -10,21 +10,21 @@ This page describes tools and techniques for deploy and optimize your Angular ap
{@a toc} {@a toc}
## Table of contents ## Table of contents
* [Overview](#overview) * [Overview](guide/deployment#overview)
* [Simplest deployment possible](#dev-deploy) * [Simplest deployment possible](guide/deployment#dev-deploy)
* [Optimize for production](#optimize) * [Optimize for production](guide/deployment#optimize)
* [Ahead-of-Time (AOT) compilation](#aot) * [Ahead-of-Time (AOT) compilation](guide/deployment#aot)
* [Webpack](#webpack) * [Webpack](guide/deployment#webpack)
* [Tree shaking with _rollup_](#rollup) * [Tree shaking with _rollup_](guide/deployment#rollup)
* [Pruned libraries](#prune) * [Pruned libraries](guide/deployment#prune)
* [Measure performance first](#measure) * [Measure performance first](guide/deployment#measure)
* [Angular configuration](#angular-configuration) * [Angular configuration](guide/deployment#angular-configuration)
* [The `base` tag](#base-tag) * [The `base` tag](guide/deployment#base-tag)
* [Enable production mode](#enable-prod-mode) * [Enable production mode](guide/deployment#enable-prod-mode)
* [Lazy loading](#lazy-loading) * [Lazy loading](guide/deployment#lazy-loading)
* [Server configuration](#server-configuration) * [Server configuration](guide/deployment#server-configuration)
* [Routed apps must fallback to `index.html`](#fallback) * [Routed apps must fallback to `index.html`](guide/deployment#fallback)
* [CORS: requesting services from a different server](#cors) * [CORS: requesting services from a different server](guide/deployment#cors)
{@a overview} {@a overview}
@ -34,20 +34,20 @@ This page describes tools and techniques for deploy and optimize your Angular ap
This guide describes techniques for preparing and deploying an Angular application to a server running remotely. This guide describes techniques for preparing and deploying an Angular application to a server running remotely.
The techniques progress from _easy but suboptimal_ to _more optimal and more involved_. The techniques progress from _easy but suboptimal_ to _more optimal and more involved_.
* The [simple way](#dev-deploy "Simplest deployment possible") is to copy the development environment to the server. * The [simple way](guide/deployment#dev-deploy "Simplest deployment possible") is to copy the development environment to the server.
* [_Ahead of Time_ compilation (AOT)](#aot "AOT Compilation") is the first of * [_Ahead of Time_ compilation (AOT)](guide/deployment#aot "AOT Compilation") is the first of
[several optimization strategies](#optimize). [several optimization strategies](guide/deployment#optimize).
You'll also want to read the [detailed instructions in the AOT Cookbook](../cookbook/aot-compiler.html "AOT Cookbook"). You'll also want to read the [detailed instructions in the AOT Cookbook](cookbook/aot-compiler).
* [Webpack](#webpack "Webpack Optimization") is a popular general purpose packaging tool with a rich ecosystem, including plugins for AOT. * [Webpack](guide/deployment#webpack "Webpack Optimization") is a popular general purpose packaging tool with a rich ecosystem, including plugins for AOT.
The Angular [webpack guide](webpack.html "Webpack: an introduction") can get you started and The Angular [webpack guide](guide/webpack) can get you started and
_this_ page provides additional optimization advice, but you'll probably have to learn more about webpack on your own. _this_ page provides additional optimization advice, but you'll probably have to learn more about webpack on your own.
* The [Angular configuration](#angular-configuration "Angular configuration") section calls attention to * The [Angular configuration](guide/deployment#angular-configuration "Angular configuration") section calls attention to
specific client application changes that could improve performance. specific client application changes that could improve performance.
* The [Server configuration](#server-configuration "Server configuration") section describes * The [Server configuration](guide/deployment#server-configuration "Server configuration") section describes
server-side changes that may be necessary, _no matter how you deploy the application_. server-side changes that may be necessary, _no matter how you deploy the application_.
@ -61,7 +61,7 @@ directly out of the development environment.
It's already running locally. You'll just copy it, almost _as is_, It's already running locally. You'll just copy it, almost _as is_,
to a non-local server that others can reach. to a non-local server that others can reach.
1. Copy _everything_ (or [_almost_ everything](#node-modules "Loading npm packages from the web")) 1. Copy _everything_ (or [_almost_ everything](guide/deployment#node-modules "Loading npm packages from the web"))
from the local project folder to a folder on the server. from the local project folder to a folder on the server.
1. If you're serving the app out of a subfolder, 1. If you're serving the app out of a subfolder,
@ -69,12 +69,12 @@ edit a version of `index.html` to set the `<base href>` appropriately.
For example, if the URL to `index.html` is `www.mysite.com/my/app/`, set the _base href_ to For example, if the URL to `index.html` is `www.mysite.com/my/app/`, set the _base href_ to
`<base href="/my/app/">`. `<base href="/my/app/">`.
Otherwise, leave it alone. Otherwise, leave it alone.
[More on this below](#base-tag). [More on this below](guide/deployment#base-tag).
1. Configure the server to redirect requests for missing files to `index.html`. 1. Configure the server to redirect requests for missing files to `index.html`.
[More on this below](#fallback). [More on this below](guide/deployment#fallback).
1. Enable production mode as [described below](#enable-prod-mode) (optional). 1. Enable production mode as [described below](guide/deployment#enable-prod-mode) (optional).
That's the simplest deployment you can do. That's the simplest deployment you can do.
@ -83,7 +83,7 @@ That's the simplest deployment you can do.
This is _not_ a production deployment. It's not optimized and it won't be fast for users. This is _not_ a production deployment. It's not optimized and it won't be fast for users.
It might be good enough for sharing your progress and ideas internally with managers, teammates, and other stakeholders. It might be good enough for sharing your progress and ideas internally with managers, teammates, and other stakeholders.
Be sure to read about [optimizing for production](#optimize "Optimizing for production") below. Be sure to read about [optimizing for production](guide/deployment#optimize "Optimizing for production") below.
@ -184,7 +184,7 @@ The following trivial router sample app shows these changes.
Practice with this sample before attempting these techniques on your application. Practice with this sample before attempting these techniques on your application.
1. Follow the [setup instructions](../guide/setup.html "Angular QuickStart setup") for creating a new project 1. Follow the [setup instructions](guide/setup) for creating a new project
named <ngio-ex path="simple-deployment"></ngio-ex>. named <ngio-ex path="simple-deployment"></ngio-ex>.
1. Add the "Simple deployment" sample files shown above. 1. Add the "Simple deployment" sample files shown above.
@ -254,9 +254,9 @@ Apps compiled with AOT launch faster for several reasons.
* You don't download the Angular compiler, which is pretty big on its own. * You don't download the Angular compiler, which is pretty big on its own.
* The compiler discards unused Angular directives that a tree-shaking tool can then exclude. * The compiler discards unused Angular directives that a tree-shaking tool can then exclude.
Learn more about AOT Compilation in the [AOT Cookbook](../cookbook/aot-compiler.html "AOT Cookbook") Learn more about AOT Compilation in the [AOT Cookbook](cookbook/aot-compiler)
which describes running the AOT compiler from the command line which describes running the AOT compiler from the command line
and using [_rollup_](#rollup) for bundling, minification, uglification and tree shaking. and using [_rollup_](guide/deployment#rollup) for bundling, minification, uglification and tree shaking.
{@a webpack} {@a webpack}
@ -264,7 +264,7 @@ and using [_rollup_](#rollup) for bundling, minification, uglification and tree
<a href="https://webpack.js.org/" target="_blank" title="Webpack 2">Webpack 2</a> is another <a href="https://webpack.js.org/" target="_blank" title="Webpack 2">Webpack 2</a> is another
great option for inlining templates and style-sheets, for bundling, minifying, and uglifying the application. great option for inlining templates and style-sheets, for bundling, minifying, and uglifying the application.
The "[Webpack: an introduction](webpack.html "Webpack: an introduction")" guide will get you started The "[Webpack: an introduction](guide/webpack)" guide will get you started
using webpack with Angular. using webpack with Angular.
Consider configuring _Webpack_ with the official Consider configuring _Webpack_ with the official
@ -338,7 +338,7 @@ For example, given the `<base href="/my/app/">`, the browser resolves a URL such
into a server request for `my/app/some/place/foo.jpg`. into a server request for `my/app/some/place/foo.jpg`.
During navigation, the Angular router uses the _base href_ as the base path to component, template, and module files. During navigation, the Angular router uses the _base href_ as the base path to component, template, and module files.
See also the [*APP_BASE_HREF*](../api/common/index/APP_BASE_HREF-let.html "API: APP_BASE_HREF") alternative.In development, you typically start the server in the folder that holds `index.html`. See also the [*APP_BASE_HREF*](api/common/index/APP_BASE_HREF-let) alternative.In development, you typically start the server in the folder that holds `index.html`.
That's the root folder and you'd add `<base href="/">` near the top of `index.html` because `/` is the root of the app. That's the root folder and you'd add `<base href="/">` near the top of `index.html` because `/` is the root of the app.
But on the shared or production server, you might serve the app from a subfolder. But on the shared or production server, you might serve the app from a subfolder.
@ -361,7 +361,7 @@ console:
Switching to production mode can make it run faster by disabling development specific checks such as the dual change detection cycles. Switching to production mode can make it run faster by disabling development specific checks such as the dual change detection cycles.
To enable [production mode](../api/core/index/enableProdMode-function.html) when running remotely, add the following code to the `main.ts`. To enable [production mode](api/core/index/enableProdMode-function) when running remotely, add the following code to the `main.ts`.
{@example 'deployment/ts/src/main.ts' region='enableProdMode'} {@example 'deployment/ts/src/main.ts' region='enableProdMode'}
@ -375,8 +375,8 @@ You can dramatically reduce launch time by only loading the application modules
absolutely must be present when the app starts. absolutely must be present when the app starts.
Configure the Angular Router to defer loading of all other modules (and their associated code), either by Configure the Angular Router to defer loading of all other modules (and their associated code), either by
[waiting until the app has launched](router.html#preloading "Preloading") [waiting until the app has launched](guide/router)
or by [_lazy loading_](router.html#asynchronous-routing "Lazy loading") or by [_lazy loading_](guide/router)
them on demand. them on demand.
#### Don't eagerly import something from a lazy loaded module #### Don't eagerly import something from a lazy loaded module
@ -545,5 +545,5 @@ Read about how to enable CORS for specific servers at
{@a next-steps} {@a next-steps}
## Next steps ## Next steps
If you want to go beyond the [simple _copy-deploy_](#dev-deploy "Simplest deployment possible") approach, If you want to go beyond the [simple _copy-deploy_](guide/deployment#dev-deploy "Simplest deployment possible") approach,
read the [AOT Cookbook](../cookbook/aot-compiler.html "AOT Cookbook") next. read the [AOT Cookbook](cookbook/aot-compiler) next.

22
aio/content/guide/displaying-data.md
View File

@ -19,9 +19,9 @@ The final UI looks like this:
# Contents # Contents
* [Showing component properties with interpolation](#interpolation). * [Showing component properties with interpolation](guide/displaying-data#interpolation).
* [Showing !{_an} !{_array} property with NgFor](#ngFor). * [Showing !{_an} !{_array} property with NgFor](guide/displaying-data#ngFor).
* [Conditional display with NgIf](#ngIf). * [Conditional display with NgIf](guide/displaying-data#ngIf).
The <live-example></live-example> demonstrates all of the syntax and code The <live-example></live-example> demonstrates all of the syntax and code
snippets described in this page. snippets described in this page.
@ -31,7 +31,7 @@ The easiest way to display a component property
is to bind the property name through interpolation. is to bind the property name through interpolation.
With interpolation, you put the property name in the view template, enclosed in double curly braces: `{{myHero}}`. With interpolation, you put the property name in the view template, enclosed in double curly braces: `{{myHero}}`.
Follow the [setup](setup.html) instructions for creating a new project Follow the [setup](guide/setup) instructions for creating a new project
named <ngio-ex path="displaying-data"></ngio-ex>. named <ngio-ex path="displaying-data"></ngio-ex>.
Then modify the <ngio-ex path="app.component.ts"></ngio-ex> file by Then modify the <ngio-ex path="app.component.ts"></ngio-ex> file by
@ -93,22 +93,22 @@ It marks that `<li>` element (and its children) as the "repeater template":
~~~ {.alert.is-important} ~~~ {.alert.is-important}
Don't forget the leading asterisk (\*) in `*ngFor`. It is an essential part of the syntax. Don't forget the leading asterisk (\*) in `*ngFor`. It is an essential part of the syntax.
For more information, see the [Template Syntax](./template-syntax.html#ngFor) page. For more information, see the [Template Syntax](guide/template-syntax) page.
~~~ ~~~
Notice the `hero` in the `ngFor` double-quoted instruction; Notice the `hero` in the `ngFor` double-quoted instruction;
it is an example of a template input variable. Read it is an example of a template input variable. Read
more about template input variables in the [microsyntax](./template-syntax.html#microsyntax) section of more about template input variables in the [microsyntax](guide/template-syntax) section of
the [Template Syntax](./template-syntax.html) page. the [Template Syntax](guide/template-syntax) page.
Angular duplicates the `<li>` for each item in the list, setting the `hero` variable Angular duplicates the `<li>` for each item in the list, setting the `hero` variable
to the item (the hero) in the current iteration. Angular uses that variable as the to the item (the hero) in the current iteration. Angular uses that variable as the
context for the interpolation in the double curly braces. context for the interpolation in the double curly braces.
In this case, `ngFor` is displaying !{_an} !{_array}, but `ngFor` can In this case, `ngFor` is displaying !{_an} !{_array}, but `ngFor` can
repeat items for any [iterable](!{_iterableUrl}) object.Now the heroes appear in an unordered list. repeat items for any [iterable](guide/!{_iterableUrl}) object.Now the heroes appear in an unordered list.
<figure class='image-display'> <figure class='image-display'>
<img src="assets/images/devguide/displaying-data/hero-names-list.png" alt="After ngfor"> </img> <img src="assets/images/devguide/displaying-data/hero-names-list.png" alt="After ngfor"> </img>
@ -150,7 +150,7 @@ To see it in action, add the following paragraph at the bottom of the template:
~~~ {.alert.is-important} ~~~ {.alert.is-important}
Don't forget the leading asterisk (\*) in `*ngIf`. It is an essential part of the syntax. Don't forget the leading asterisk (\*) in `*ngIf`. It is an essential part of the syntax.
Read more about `ngIf` and `*` in the [ngIf section](./template-syntax.html#ngIf) of the [Template Syntax](./template-syntax.html) page. Read more about `ngIf` and `*` in the [ngIf section](guide/template-syntax) of the [Template Syntax](guide/template-syntax) page.
~~~ ~~~
@ -160,8 +160,8 @@ The template expression inside the double quotes,
When the component's list of heroes has more than three items, Angular adds the paragraph When the component's list of heroes has more than three items, Angular adds the paragraph
to the DOM and the message appears. If there are three or fewer items, Angular omits the to the DOM and the message appears. If there are three or fewer items, Angular omits the
paragraph, so no message appears. For more information, paragraph, so no message appears. For more information,
see the [template expressions](./template-syntax.html#template-expressions) section of the see the [template expressions](guide/template-syntax) section of the
[Template Syntax](./template-syntax.html) page. [Template Syntax](guide/template-syntax) page.
~~~ {.alert.is-helpful} ~~~ {.alert.is-helpful}

6
aio/content/guide/dynamic-component-loader.md
View File

@ -11,11 +11,11 @@ In this cookbook we show how to use `ComponentFactoryResolver` to add components
<a id="toc"></a>## Table of contents <a id="toc"></a>## Table of contents
[Dynamic Component Loading](#dynamic-loading) [Dynamic Component Loading](guide/dynamic-component-loader#dynamic-loading)
[Where to load the component](#where-to-load) [Where to load the component](guide/dynamic-component-loader#where-to-load)
[Loading components](#loading-components) [Loading components](guide/dynamic-component-loader#loading-components)
<a id="dynamic-loading"></a>## Dynamic Component Loading <a id="dynamic-loading"></a>## Dynamic Component Loading

12
aio/content/guide/dynamic-form.md
View File

@ -21,15 +21,15 @@ The agency is constantly tinkering with the application process.
We can create the forms on the fly *without changing our application code*. We can create the forms on the fly *without changing our application code*.
<a id="toc"></a>## Table of contents <a id="toc"></a>## Table of contents
[Bootstrap](#bootstrap) [Bootstrap](guide/dynamic-form#bootstrap)
[Question Model](#object-model) [Question Model](guide/dynamic-form#object-model)
[Form Component](#form-component) [Form Component](guide/dynamic-form#form-component)
[Questionnaire Metadata](#questionnaire-metadata) [Questionnaire Metadata](guide/dynamic-form#questionnaire-metadata)
[Dynamic Template](#dynamic-template) [Dynamic Template](guide/dynamic-form#dynamic-template)
**See the <live-example name="cb-dynamic-form"></live-example>**. **See the <live-example name="cb-dynamic-form"></live-example>**.
<a id="bootstrap"></a>## Bootstrap <a id="bootstrap"></a>## Bootstrap
@ -165,4 +165,4 @@ The final form looks like this:
<img src="assets/images/cookbooks/dynamic-form/dynamic-form.png" alt="Dynamic-Form"> </img> <img src="assets/images/cookbooks/dynamic-form/dynamic-form.png" alt="Dynamic-Form"> </img>
</figure> </figure>
[Back to top](#top) [Back to top](guide/dynamic-form#top)

34
aio/content/guide/form-validation.md
View File

@ -12,21 +12,21 @@ We can improve overall data quality by validating user input for accuracy and co
In this cookbook we show how to validate user input in the UI and display useful validation messages In this cookbook we show how to validate user input in the UI and display useful validation messages
using first the template-driven forms and then the reactive forms approach. using first the template-driven forms and then the reactive forms approach.
Learn more about these choices in the [Forms chapter.](../guide/forms.html) Learn more about these choices in the [Forms chapter.](guide/forms)
{@a toc} {@a toc}
## Table of Contents ## Table of Contents
[Simple Template-Driven Forms](#template1) [Simple Template-Driven Forms](guide/form-validation#template1)
[Template-Driven Forms with validation messages in code](#template2) [Template-Driven Forms with validation messages in code](guide/form-validation#template2)
[Reactive Forms with validation in code](#reactive) [Reactive Forms with validation in code](guide/form-validation#reactive)
[Custom validation](#custom-validation) [Custom validation](guide/form-validation#custom-validation)
[Testing](#testing) [Testing](guide/form-validation#testing)
{@a live-example} {@a live-example}
@ -85,7 +85,7 @@ The full template repeats this kind of layout for each data entry control on the
We shouldn't show errors for a new hero before the user has had a chance to edit the value. We shouldn't show errors for a new hero before the user has had a chance to edit the value.
The checks for `dirty` and `touched` prevent premature display of errors. The checks for `dirty` and `touched` prevent premature display of errors.
Learn about `dirty` and `touched` in the [Forms](../guide/forms.html) chapter.The component class manages the hero model used in the data binding Learn about `dirty` and `touched` in the [Forms](guide/forms) chapter.The component class manages the hero model used in the data binding
as well as other code to support the view. as well as other code to support the view.
@ -148,8 +148,8 @@ The `<input>` element HTML is almost the same. There are noteworthy differences:
- The hard-code error message `<divs>` are gone. - The hard-code error message `<divs>` are gone.
- There's a new attribute, `forbiddenName`, that is actually a custom validation directive. - There's a new attribute, `forbiddenName`, that is actually a custom validation directive.
It invalidates the control if the user enters "bob" anywhere in the name ([try it](#live-example)). It invalidates the control if the user enters "bob" anywhere in the name ([try it](guide/form-validation#live-example)).
We discuss [custom validation directives](#custom-validation) later in this cookbook. We discuss [custom validation directives](guide/form-validation#custom-validation) later in this cookbook.
- The `#name` template variable is gone because we no longer refer to the Angular control for this element. - The `#name` template variable is gone because we no longer refer to the Angular control for this element.
@ -179,7 +179,7 @@ the name of that variable as a string (`'heroForm'` in this case).
- The `heroForm` object changes several times during the life of the component, most notably when we add a new hero. - The `heroForm` object changes several times during the life of the component, most notably when we add a new hero.
We'll have to re-inspect it periodically. We'll have to re-inspect it periodically.
- Angular calls the `ngAfterViewChecked` [lifecycle hook method](../guide/lifecycle-hooks.html#afterview) - Angular calls the `ngAfterViewChecked` [lifecycle hook method](guide/lifecycle-hooks)
when anything changes in the view. when anything changes in the view.
That's the right time to see if there's a new `heroForm` object. That's the right time to see if there's a new `heroForm` object.
@ -245,7 +245,7 @@ Here's how we imported it in the `HeroFormTemplateModule`.
We haven't talked about the `SharedModule` or its `SubmittedComponent` which appears at the bottom of every We haven't talked about the `SharedModule` or its `SubmittedComponent` which appears at the bottom of every
form template in this cookbook. form template in this cookbook.
They're not germane to the validation story. Look at the [live example](#live-example) if you're interested. They're not germane to the validation story. Look at the [live example](guide/form-validation#live-example) if you're interested.
@ -266,7 +266,7 @@ This approach requires a bit more effort. *You have to write the control model a
In return, you can In return, you can
* add, change, and remove validation functions on the fly * add, change, and remove validation functions on the fly
* manipulate the control model dynamically from within the component * manipulate the control model dynamically from within the component
* [test](#testing) validation and control logic with isolated unit tests. * [test](guide/form-validation#testing) validation and control logic with isolated unit tests.
The third cookbook sample re-writes the hero form in _reactive forms_ style. The third cookbook sample re-writes the hero form in _reactive forms_ style.
@ -346,7 +346,7 @@ Here's the section of code devoted to that process, paired with the template-dri
- we inject the `FormBuilder` in a constructor. - we inject the `FormBuilder` in a constructor.
- we call a `buildForm` method in the `ngOnInit` [lifecycle hook method](../guide/lifecycle-hooks.html#hooks-overview) - we call a `buildForm` method in the `ngOnInit` [lifecycle hook method](guide/lifecycle-hooks)
because that's when we'll have the hero data. We'll call it again in the `addHero` method. because that's when we'll have the hero data. We'll call it again in the `addHero` method.
A real app would retrieve the hero asynchronously from a data service, a task best performed in the `ngOnInit` hook.- the `buildForm` method uses the `FormBuilder` (`fb`) to declare the form control model. A real app would retrieve the hero asynchronously from a data service, a task best performed in the `ngOnInit` hook.- the `buildForm` method uses the `FormBuilder` (`fb`) to declare the form control model.
Then it attaches the same `onValueChanged` handler (there's a one line difference) Then it attaches the same `onValueChanged` handler (there's a one line difference)
@ -363,9 +363,9 @@ Most of the validator functions are stock validators provided by Angular as stat
Angular has stock validators that correspond to the standard HTML validation attributes. Angular has stock validators that correspond to the standard HTML validation attributes.
The `forbiddenNames` validator on the `"name"` control is a custom validator, The `forbiddenNames` validator on the `"name"` control is a custom validator,
discussed in a separate [section below](#custom-validation). discussed in a separate [section below](guide/form-validation#custom-validation).
Learn more about `FormBuilder` in the [Introduction to FormBuilder](../guide/reactive-forms.html#formbuilder) section of Reactive Forms guide. Learn more about `FormBuilder` in the [Introduction to FormBuilder](guide/reactive-forms) section of Reactive Forms guide.
#### Committing hero value changes #### Committing hero value changes
In two-way data binding, the user's changes flow automatically from the controls back to the data model properties. In two-way data binding, the user's changes flow automatically from the controls back to the data model properties.
@ -410,7 +410,7 @@ Here's the complete reactive component file, compared to the two template-driven
</md-tab-group> </md-tab-group>
Run the [live example](#live-example) to see how the reactive form behaves Run the [live example](guide/form-validation#live-example) to see how the reactive form behaves
and to compare all of the files in this cookbook sample. and to compare all of the files in this cookbook sample.
@ -461,7 +461,7 @@ The rest of the directive is unremarkable and we present it here without further
{@example 'cb-form-validation/ts/src/app/shared/forbidden-name.directive.ts' region='directive'} {@example 'cb-form-validation/ts/src/app/shared/forbidden-name.directive.ts' region='directive'}
See the [Attribute Directives](../guide/attribute-directives.html) chapter. See the [Attribute Directives](guide/attribute-directives) chapter.

30
aio/content/guide/forms.md
View File

@ -29,7 +29,7 @@ You can run the <live-example></live-example> in Plunker and download the code f
## Template-driven forms ## Template-driven forms
You can build forms by writing templates in the Angular [template syntax](./template-syntax.html) with You can build forms by writing templates in the Angular [template syntax](guide/template-syntax) with
the form-specific directives and techniques described in this page. the form-specific directives and techniques described in this page.
You can also use a reactive (or model-driven) approach to build forms. You can also use a reactive (or model-driven) approach to build forms.
@ -74,7 +74,7 @@ You'll build this form in small steps:
1. Disable the form’s *Submit* button until the form is valid. 1. Disable the form’s *Submit* button until the form is valid.
## Setup ## Setup
Follow the [setup](setup.html) instructions for creating a new project Follow the [setup](guide/setup) instructions for creating a new project
named <span ngio-ex>angular-forms</span>. named <span ngio-ex>angular-forms</span>.
## Create the Hero model class ## Create the Hero model class
@ -119,8 +119,8 @@ Understanding this component requires only the Angular concepts covered in previ
- You defined dummy data for `model` and `powers`, as befits a demo. - You defined dummy data for `model` and `powers`, as befits a demo.
Down the road, you can inject a data service to get and save real data Down the road, you can inject a data service to get and save real data
or perhaps expose these properties as inputs and outputs or perhaps expose these properties as inputs and outputs
(see [Input and output properties](./template-syntax.html#inputs-outputs) on the (see [Input and output properties](guide/template-syntax) on the
[Template Syntax](./template-syntax.html) page) for binding to a [Template Syntax](guide/template-syntax) page) for binding to a
parent component. This is not a concern now and these future changes won't affect the form. parent component. This is not a concern now and these future changes won't affect the form.
- You added a `diagnostic` property to return a JSON representation of the model. - You added a `diagnostic` property to return a JSON representation of the model.
It'll help you see what you're doing during development; you've left yourself a cleanup note to discard it later. It'll help you see what you're doing during development; you've left yourself a cleanup note to discard it later.
@ -230,7 +230,7 @@ You maintain that list internally (in `HeroFormComponent`).
You'll add a `select` to the You'll add a `select` to the
form and bind the options to the `powers` list using `ngFor`, form and bind the options to the `powers` list using `ngFor`,
a technique seen previously in the [Displaying Data](./displaying-data.html) page. a technique seen previously in the [Displaying Data](guide/displaying-data) page.
Add the following HTML *immediately below* the *Alter Ego* group: Add the following HTML *immediately below* the *Alter Ego* group:
This code repeats the `<option>` tag for each power in the list of powers. This code repeats the `<option>` tag for each power in the list of powers.
@ -247,8 +247,8 @@ Running the app right now would be disappointing.
You don't see hero data because you're not binding to the `Hero` yet. You don't see hero data because you're not binding to the `Hero` yet.
You know how to do that from earlier pages. You know how to do that from earlier pages.
[Displaying Data](./displaying-data.html) teaches property binding. [Displaying Data](guide/displaying-data) teaches property binding.
[User Input](./user-input.html) shows how to listen for DOM events with an [User Input](guide/user-input) shows how to listen for DOM events with an
event binding and how to update a component property with the displayed value. event binding and how to update a component property with the displayed value.
Now you need to display, listen, and extract at the same time. Now you need to display, listen, and extract at the same time.
@ -278,8 +278,8 @@ back again.
That's *two-way data binding*. That's *two-way data binding*.
For more information, see For more information, see
[Two-way binding with NgModel](template-syntax.html#ngModel) on the [Two-way binding with NgModel](guide/template-syntax) on the
the [Template Syntax](template-syntax.html) page. the [Template Syntax](guide/template-syntax) page.
Notice that you also added a `name` attribute to the `<input>` tag and set it to "name", Notice that you also added a `name` attribute to the `<input>` tag and set it to "name",
which makes sense for the hero's name. Any unique value will do, but using a descriptive name is helpful. which makes sense for the hero's name. Any unique value will do, but using a descriptive name is helpful.
Defining a `name` attribute is a requirement when using `[(ngModel)]` in combination with a form. Defining a `name` attribute is a requirement when using `[(ngModel)]` in combination with a form.
@ -287,7 +287,7 @@ Defining a `name` attribute is a requirement when using `[(ngModel)]` in combina
Internally, Angular creates `FormControl` instances and Internally, Angular creates `FormControl` instances and
registers them with an `NgForm` directive that Angular attached to the `<form>` tag. registers them with an `NgForm` directive that Angular attached to the `<form>` tag.
Each `FormControl` is registered under the name you assigned to the `name` attribute. Each `FormControl` is registered under the name you assigned to the `name` attribute.
Read more in [The NgForm directive](#ngForm), later in this page. Read more in [The NgForm directive](guide/forms#ngForm), later in this page.
Add similar `[(ngModel)]` bindings and `name` attributes to *Alter Ego* and *Hero Power*. Add similar `[(ngModel)]` bindings and `name` attributes to *Alter Ego* and *Hero Power*.
You'll ditch the input box binding message You'll ditch the input box binding message
and add a new binding (at the top) to the component's `diagnostic` property. and add a new binding (at the top) to the component's `diagnostic` property.
@ -401,7 +401,7 @@ You can leverage those class names to change the appearance of the control.
</table> </table>
Temporarily add a [template reference variable](./template-syntax.html#ref-vars) named `spy` Temporarily add a [template reference variable](guide/template-syntax) named `spy`
to the _Name_ `<input>` tag and use it to display the input's CSS classes. to the _Name_ `<input>` tag and use it to display the input's CSS classes.
Now run the app and look at the _Name_ input box. Now run the app and look at the _Name_ input box.
Follow these steps *precisely*: Follow these steps *precisely*:
@ -458,7 +458,7 @@ When the user deletes the name, the form should look like this:
</figure> </figure>
To achieve this effect, extend the `<input>` tag with the following: To achieve this effect, extend the `<input>` tag with the following:
- A [template reference variable](./template-syntax.html#ref-vars). - A [template reference variable](guide/template-syntax).
- The "*is required*" message in a nearby `<div>`, which you'll display only if the control is invalid. - The "*is required*" message in a nearby `<div>`, which you'll display only if the control is invalid.
Here's an example of an error message added to the _name_ input box: Here's an example of an error message added to the _name_ input box:
@ -466,7 +466,7 @@ You need a template reference variable to access the input box's Angular control
Here you created a variable called `name` and gave it the value "ngModel". Here you created a variable called `name` and gave it the value "ngModel".
Why "ngModel"? Why "ngModel"?
A directive's [exportAs](../api/core/index/Directive-decorator.html) property A directive's [exportAs](api/core/index/Directive-decorator) property
tells Angular how to link the reference variable to the directive. tells Angular how to link the reference variable to the directive.
You set `name` to `ngModel` because the `ngModel` directive's `exportAs` property happens to be "ngModel". You set `name` to `ngModel` because the `ngModel` directive's `exportAs` property happens to be "ngModel".
You control visibility of the name error message by binding properties of the `name` You control visibility of the name error message by binding properties of the `name`
@ -481,7 +481,7 @@ you'll see the error message immediately, before you've done anything.
Some developers want to the message to display only when the user makes an invalid change. Some developers want to the message to display only when the user makes an invalid change.
Hiding the message while the control is "pristine" achieves that goal. Hiding the message while the control is "pristine" achieves that goal.
You'll see the significance of this choice when you [add a new hero](#new-hero) to the form. You'll see the significance of this choice when you [add a new hero](guide/forms#new-hero) to the form.
The hero *Alter Ego* is optional so you can leave that be. The hero *Alter Ego* is optional so you can leave that be.
@ -540,7 +540,7 @@ The variable `heroForm` is now a reference to the `NgForm` directive that govern
### The _NgForm_ directive ### The _NgForm_ directive
What `NgForm` directive? What `NgForm` directive?
You didn't add an [NgForm](../api/forms/index/NgForm-directive.html) directive. You didn't add an [NgForm](api/forms/index/NgForm-directive) directive.
Angular did. Angular automatically creates and attaches an `NgForm` directive to the `<form>` tag. Angular did. Angular automatically creates and attaches an `NgForm` directive to the `<form>` tag.

6
aio/content/guide/hierarchical-dependency-injection.md
View File

@ -6,7 +6,7 @@ Angular's hierarchical dependency injection system supports nested injectors in
@description @description
You learned the basics of Angular Dependency injection in the You learned the basics of Angular Dependency injection in the
[Dependency Injection](./dependency-injection.html) guide. [Dependency Injection](guide/dependency-injection) guide.
Angular has a _Hierarchical Dependency Injection_ system. Angular has a _Hierarchical Dependency Injection_ system.
There is actually a tree of injectors that parallel an application's component tree. There is actually a tree of injectors that parallel an application's component tree.
@ -18,7 +18,7 @@ Try the <live-example></live-example>.
## The injector tree ## The injector tree
In the [Dependency Injection](./dependency-injection.html) guide, In the [Dependency Injection](guide/dependency-injection) guide,
you learned how to configure a dependency injector and how to retrieve dependencies where you need them. you learned how to configure a dependency injector and how to retrieve dependencies where you need them.
In fact, there is no such thing as ***the*** injector. In fact, there is no such thing as ***the*** injector.
@ -150,7 +150,7 @@ You can review it and download it from the <live-example></live-example>.
Another reason to re-provide a service is to substitute a _more specialized_ implementation of that service, Another reason to re-provide a service is to substitute a _more specialized_ implementation of that service,
deeper in the component tree. deeper in the component tree.
Consider again the Car example from the [Dependency Injection](./dependency-injection.html) guide. Consider again the Car example from the [Dependency Injection](guide/dependency-injection) guide.
Suppose you configured the root injector (marked as A) with _generic_ providers for Suppose you configured the root injector (marked as A) with _generic_ providers for
`CarService`, `EngineService` and `TiresService`. `CarService`, `EngineService` and `TiresService`.

36
aio/content/guide/i18n.md
View File

@ -12,17 +12,17 @@ Angular's _internationalization_ (_i18n_) tools help make your app available in
## Table of contents ## Table of contents
* [Angular and i18n template translation](#angular-i18n) * [Angular and i18n template translation](guide/i18n#angular-i18n)
* [Mark text with the _i18n_ attribute](#i18n-attribute) * [Mark text with the _i18n_ attribute](guide/i18n#i18n-attribute)
* [Add _i18n-..._ translation attributes](#translate-attributes) * [Add _i18n-..._ translation attributes](guide/i18n#translate-attributes)
* [Handle singular and plural](#cardinality) * [Handle singular and plural](guide/i18n#cardinality)
* [Select among alternative texts](#select) * [Select among alternative texts](guide/i18n#select)
* [Create a translation source file with the **_ng-xi18n_ extraction tool**](#ng-xi18n) * [Create a translation source file with the **_ng-xi18n_ extraction tool**](guide/i18n#ng-xi18n)
* [Translate text messages](#translate) * [Translate text messages](guide/i18n#translate)
* [Merge the completed translation file into the app](#merge) * [Merge the completed translation file into the app](guide/i18n#merge)
* [Merge with the JIT compiler](#jit) * [Merge with the JIT compiler](guide/i18n#jit)
* [Internationalization with the AOT compiler](#aot) * [Internationalization with the AOT compiler](guide/i18n#aot)
* [Translation file maintenance and _id_ changes](#maintenance) * [Translation file maintenance and _id_ changes](guide/i18n#maintenance)
**Try this** <live-example name="cb-i18n" title="i18n Example in Spanish">live example</live-example> **Try this** <live-example name="cb-i18n" title="i18n Example in Spanish">live example</live-example>
of a JIT-compiled app, translated into Spanish. of a JIT-compiled app, translated into Spanish.
@ -346,7 +346,7 @@ replace the `<target/>` tag with the Spanish greeting:
Note that the tool generates the `id`. **Don't touch it.** Note that the tool generates the `id`. **Don't touch it.**
Its value depends on the content of the message and its assigned meaning. Its value depends on the content of the message and its assigned meaning.
Change either factor and the `id` changes as well. Change either factor and the `id` changes as well.
See the **[translation file maintenance discussion](#maintenance)**. See the **[translation file maintenance discussion](guide/i18n#maintenance)**.
~~~ ~~~
@ -465,8 +465,8 @@ You provide the Angular compiler with three new pieces of information:
_How_ you provide this information depends upon whether you compile with _How_ you provide this information depends upon whether you compile with
the JIT (_Just-in-Time_) compiler or the AOT (_Ahead-of-Time_) compiler. the JIT (_Just-in-Time_) compiler or the AOT (_Ahead-of-Time_) compiler.
* With [JIT](#jit), you provide the information at bootstrap time. * With [JIT](guide/i18n#jit), you provide the information at bootstrap time.
* With [AOT](#aot), you pass the information as `ngc` options. * With [AOT](guide/i18n#aot), you pass the information as `ngc` options.
{@a jit} {@a jit}
@ -524,10 +524,10 @@ and the corresponding translation file:
It must return a `Promise` because this function could read a translation file asynchronously from the server. It must return a `Promise` because this function could read a translation file asynchronously from the server.
1. It creates a transaction filename from the locale according to the name and location convention 1. It creates a transaction filename from the locale according to the name and location convention
[described earlier](#localization-folder). [described earlier](guide/i18n#localization-folder).
1. The `getTranslationsWithSystemJs` method reads the translation and returns the contents as a string. 1. The `getTranslationsWithSystemJs` method reads the translation and returns the contents as a string.
Notice that it appends `!text` to the filename, telling SystemJS to use the [text plugin](#text-plugin). Notice that it appends `!text` to the filename, telling SystemJS to use the [text plugin](guide/i18n#text-plugin).
1. The callback composes a providers array with the three translation providers. 1. The callback composes a providers array with the three translation providers.
@ -574,8 +574,8 @@ It does explain the few steps necessary to tell the AOT compiler to apply a tran
Internationalization with the AOT compiler requires Internationalization with the AOT compiler requires
some setup specifically for AOT compilation. some setup specifically for AOT compilation.
Start with the application project as shown Start with the application project as shown
[just before merging the translation file](#app-pre-translation) [just before merging the translation file](guide/i18n#app-pre-translation)
and refer to the [AOT cookbook](aot-compiler.html) to make it _AOT-ready_. and refer to the [AOT cookbook](guide/aot-compiler) to make it _AOT-ready_.
Next, issue an `ngc` compile command for each supported language (including English). Next, issue an `ngc` compile command for each supported language (including English).
The result is a separate version of the application for each language. The result is a separate version of the application for each language.

12
aio/content/guide/index.md
View File

@ -6,7 +6,7 @@ How to read and use this documentation.
@description @description
This page describes the Angular documentation at a high level. This page describes the Angular documentation at a high level.
If you're new to Angular, you may want to visit "[Learning Angular](learning-angular.html)" first. If you're new to Angular, you may want to visit "[Learning Angular](guide/learning-angular)" first.
## Themes ## Themes
@ -132,7 +132,7 @@ Each page includes code snippets from a sample application that accompanies the
You can reuse these snippets in your applications. You can reuse these snippets in your applications.
Look for a link to a running version of that sample, often near the top of the page, Look for a link to a running version of that sample, often near the top of the page,
such as this <live-example nodownload name="architecture"></live-example> from the [Architecture](architecture.html) page. such as this <live-example nodownload name="architecture"></live-example> from the [Architecture](guide/architecture) page.
<span if-docs="ts"> <span if-docs="ts">
The link launches a browser-based, code editor where you 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.
</span> </span>
@ -142,10 +142,10 @@ Just download, unzip, run `npm install` to install the dependencies and run it w
## Reference pages ## Reference pages
* The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios. * The [Cheat Sheet](guide/cheatsheet) lists Angular syntax for common scenarios.
* The [Glossary](glossary.html) defines terms that Angular developers should know. * The [Glossary](guide/glossary) defines terms that Angular developers should know.
<li if-docs="ts">The [Change Log](change-log.html) announces what's new and changed in the documentation.</li> <li if-docs="ts">The [Change Log](guide/change-log) announces what's new and changed in the documentation.</li>
* The [API Reference](../api/) is the authority on every public-facing member of the Angular libraries. * The [API Reference](api/) is the authority on every public-facing member of the Angular libraries.
## Feedback ## Feedback

24
aio/content/guide/learning-angular.md
View File

@ -15,32 +15,32 @@ You don't have to read the documentation straight through. Most pages stand on
Those new to Angular may wish to follow this popular learning path. Those new to Angular may wish to follow this popular learning path.
<br class="l-clear-left"> <br class="l-clear-left">
1. [Setup](setup.html "Setup locally withe Quickstart seed") for local Angular development, if you haven't already done so. 1. [Setup](guide/setup) for local Angular development, if you haven't already done so.
1. Take the [*Tour of Heroes* tutorial](../tutorial "Tour of Heroes"). 1. Take the [*Tour of Heroes* tutorial](tutorial "Tour of Heroes").
The *Tour of Heroes* takes you step-by-step from [setup](setup.html) The *Tour of Heroes* takes you step-by-step from [setup](guide/setup)
to a full-featured example that demonstrates the essential characteristics of a professional application: to a full-featured example that demonstrates the essential characteristics 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.
1. <a id="architecture"></a>Read the [Architecture](architecture.html) overview for the big picture. 1. <a id="architecture"></a>Read the [Architecture](guide/architecture) overview for the big picture.
1. [The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application. 1. [The Root Module](guide/appmodule) introduces the `NgModule` class that tells Angular how to compile and run your application.
1. [Displaying Data](displaying-data.html) shows how data binding puts component property values on screen. 1. [Displaying Data](guide/displaying-data) shows how data binding puts component property values on screen.
1. [User Input](user-input.html) explains how to respond to user-initiated DOM events. 1. [User Input](guide/user-input) explains how to respond to user-initiated DOM events.
1. [Forms](forms.html) covers data entry and validation within the UI. 1. [Forms](guide/forms) covers data entry and validation within the UI.
1. [Dependency Injection](dependency-injection.html) is the way to build large, maintainable applications 1. [Dependency Injection](guide/dependency-injection) is the way to 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](guide/template-syntax) is a comprehensive study of Angular template HTML.
After reading the above sections, feel free to skip around among the other pages on this site. After reading the above sections, feel free to skip around among the other pages on this site.
### Next Step ### Next Step
Try the [tutorial](../tutorial "Tour of Heroes") if you're ready to start coding or Try the [tutorial](tutorial "Tour of Heroes") if you're ready to start coding or
visit the [Architecture](architecture.html "Basic Concepts") page if you prefer to learn the basic concepts first. visit the [Architecture](guide/architecture) page if you prefer to learn the basic concepts first.

12
aio/content/guide/lifecycle-hooks.md
View File

@ -492,7 +492,7 @@ created under test or before you decide to display it.
Constructors should do no more than set the initial local variables to simple values. Constructors should do no more than set the initial local variables to simple values.
An `ngOnInit` is a good place for a component to fetch its initial data. The An `ngOnInit` is a good place for a component to fetch its initial data. The
[Tutorial](../tutorial/toh-pt4.html#oninit) and [HTTP](server-communication.html#oninit) chapter [Tutorial](tutorial/toh-pt4) and [HTTP](guide/server-communication) chapter
show how. show how.
@ -523,7 +523,7 @@ This example monitors the `OnChanges` hook.
{@example 'lifecycle-hooks/ts/src/app/on-changes.component.ts' region='ng-on-changes'} {@example 'lifecycle-hooks/ts/src/app/on-changes.component.ts' region='ng-on-changes'}
The `ngOnChanges` method takes an object that maps each changed property name to a The `ngOnChanges` method takes an object that maps each changed property name to a
[SimpleChange](../api/core/index/SimpleChange-class.html) object holding the current and previous property values. [SimpleChange](api/core/index/SimpleChange-class) object holding the current and previous property values.
This hook iterates over the changed properties and logs them. This hook iterates over the changed properties and logs them.
The example component, `OnChangesComponent`, has two input properties: `hero` and `power`. The example component, `OnChangesComponent`, has two input properties: `hero` and `power`.
@ -588,7 +588,7 @@ The `AfterViewComponent` displays this child view *within its template*:
The following hooks take action based on changing values *within the child view* The following hooks take action based on changing values *within the child view*
which can only be reached by querying for the child view via the property decorated with which can only be reached by querying for the child view via the property decorated with
[@ViewChild](../api/core/index/ViewChild-decorator.html). [@ViewChild](api/core/index/ViewChild-decorator).
{@example 'lifecycle-hooks/ts/src/app/after-view.component.ts' region='hooks'} {@example 'lifecycle-hooks/ts/src/app/after-view.component.ts' region='hooks'}
@ -626,7 +626,7 @@ The *AfterContent* sample explores the `AfterContentInit` and `AfterContentCheck
into the component's template in a designated spot. into the component's template in a designated spot.
AngularJS developers know this technique as *transclusion*. AngularJS developers know this technique as *transclusion*.
Consider this variation on the [previous _AfterView_](#afterview) example. Consider this variation on the [previous _AfterView_](guide/lifecycle-hooks#afterview) example.
This time, instead of including the child view within the template, it imports the content from This time, instead of including the child view within the template, it imports the content from
the `AfterContentComponent`'s parent. Here's the parent's template. the `AfterContentComponent`'s parent. Here's the parent's template.
@ -661,7 +661,7 @@ projected into the component.
The following *AfterContent* hooks take action based on changing values in a *content child* The following *AfterContent* hooks take action based on changing values in a *content child*
which can only be reached by querying for it via the property decorated with which can only be reached by querying for it via the property decorated with
[@ContentChild](../api/core/index/ContentChild-decorator.html). [@ContentChild](api/core/index/ContentChild-decorator).
{@example 'lifecycle-hooks/ts/src/app/after-content.component.ts' region='hooks'} {@example 'lifecycle-hooks/ts/src/app/after-content.component.ts' region='hooks'}
@ -672,7 +672,7 @@ which can only be reached by querying for it via the property decorated with
### No unidirectional flow worries with _AfterContent..._ ### No unidirectional flow worries with _AfterContent..._
This component's `doSomething` method update's the component's data-bound `comment` property immediately. This component's `doSomething` method update's the component's data-bound `comment` property immediately.
There's no [need to wait](#wait-a-tick). There's no [need to wait](guide/lifecycle-hooks#wait-a-tick).
Recall that Angular calls both *AfterContent* hooks before calling either of the *AfterView* hooks. Recall that Angular calls both *AfterContent* hooks before calling either of the *AfterView* hooks.
Angular completes composition of the projected content *before* finishing the composition of this component's view. Angular completes composition of the projected content *before* finishing the composition of this component's view.

2
aio/content/guide/ngcontainer.md
View File

@ -8,5 +8,5 @@
This guide has been withdrawn. This guide has been withdrawn.
The essential information about this feature The essential information about this feature
is in the [Structural Directives](structural-directives.html#ngcontainer) guide. is in the [Structural Directives](guide/structural-directives) guide.
The original draft has been retained for possible future use. The original draft has been retained for possible future use.

88
aio/content/guide/ngmodule.md
View File

@ -17,7 +17,7 @@ making some of them public so external components can use them.
And there are many more options covered here. And there are many more options covered here.
Before reading this page, read the Before reading this page, read the
[The Root Module](appmodule.html) page, which introduces NgModules and the essentials [The Root Module](guide/appmodule) page, which introduces NgModules and the essentials
of creating and maintaining a single root `AppModule` for the entire application. of creating and maintaining a single root `AppModule` for the entire application.
This page covers NgModules in greater depth. This page covers NgModules in greater depth.
@ -29,21 +29,21 @@ This page covers NgModules in greater depth.
- some pages don't have tables of contents - some pages don't have tables of contents
I didn't make changes here as I'm not sure what the correct style is. I didn't make changes here as I'm not sure what the correct style is.
--> -->
* [Angular modularity](#angular-modularity "Add structure to the app with NgModule") * [Angular modularity](guide/ngmodule#angular-modularity "Add structure to the app with NgModule")
* [The application root module](#root-module "The startup module that every app requires") * [The application root module](guide/ngmodule#root-module "The startup module that every app requires")
* [Bootstrap](#bootstrap "Launch the app in a browser with the root module as the entry point") the root module * [Bootstrap](guide/ngmodule#bootstrap "Launch the app in a browser with the root module as the entry point") the root module
* [Declarations](#declarations "Declare the components, directives, and pipes that belong to a module") * [Declarations](guide/ngmodule#declarations "Declare the components, directives, and pipes that belong to a module")
* [Providers](#providers "Extend the app with additional services") * [Providers](guide/ngmodule#providers "Extend the app with additional services")
* [Imports](#imports "Import components, directives, and pipes for use in component templates") * [Imports](guide/ngmodule#imports "Import components, directives, and pipes for use in component templates")
* [Resolve conflicts](#resolve-conflicts "When two directives have the same selector") * [Resolve conflicts](guide/ngmodule#resolve-conflicts "When two directives have the same selector")
<!-- CF: See my comment in the "Resolve diretive conflicts" section below proposing renaming or reorganizing that section. --> <!-- CF: See my comment in the "Resolve diretive conflicts" section below proposing renaming or reorganizing that section. -->
* [Feature modules](#feature-modules "Partition the app into feature modules") * [Feature modules](guide/ngmodule#feature-modules "Partition the app into feature modules")
* [Lazy loaded modules](#lazy-load "Load modules asynchronously") with the router * [Lazy loaded modules](guide/ngmodule#lazy-load "Load modules asynchronously") with the router
* [Shared modules](#shared-module "Create modules for commonly used components, directives, and pipes") * [Shared modules](guide/ngmodule#shared-module "Create modules for commonly used components, directives, and pipes")
* [The Core module](#core-module "Create a core module with app-wide singleton services and single-use components") * [The Core module](guide/ngmodule#core-module "Create a core module with app-wide singleton services and single-use components")
* [Configure core services with _forRoot_](#core-for-root "Configure providers during module import") * [Configure core services with _forRoot_](guide/ngmodule#core-for-root "Configure providers during module import")
* [Prevent reimport of the _CoreModule_](#prevent-reimport "because bad things happen if a lazy loaded module imports Core") * [Prevent reimport of the _CoreModule_](guide/ngmodule#prevent-reimport "because bad things happen if a lazy loaded module imports Core")
* [NgModule metadata properties](#ngmodule-properties "A technical summary of the @NgModule metadata properties") * [NgModule metadata properties](guide/ngmodule#ngmodule-properties "A technical summary of the @NgModule metadata properties")
<!-- CF: This link goes to the top of this page. I would expect it to go to an "NgModule metadata properties" <!-- CF: This link goes to the top of this page. I would expect it to go to an "NgModule metadata properties"
section at the end of this page, but that section doesn't exist. --> section at the end of this page, but that section doesn't exist. -->
@ -61,7 +61,7 @@ Here's an index to live examples at key moments in the evolution of the sample:
This page covers NgModule concepts in a tutorial fashion. This page covers NgModule concepts in a tutorial fashion.
The companion [NgModule FAQs](../cookbook/ngmodule-faq.html "NgModule FAQs") cookbook The companion [NgModule FAQs](cookbook/ngmodule-faq) cookbook
offers answers to specific design and implementation questions. offers answers to specific design and implementation questions.
Read this page before reading those FAQs. Read this page before reading those FAQs.
@ -119,7 +119,7 @@ Later in this page, you'll read about this process. For now, you'll start with t
Every Angular app has a *root module* class. Every Angular app has a *root module* class.
By convention, the *root module* class is called `AppModule` and it exists in a file named `app.module.ts`. By convention, the *root module* class is called `AppModule` and it exists in a file named `app.module.ts`.
The `AppModule` from the QuickStart seed on the [Setup](setup.html) page is as minimal as possible: The `AppModule` from the QuickStart seed on the [Setup](guide/setup) page is as minimal as possible:
{@example 'setup/ts/src/app/app.module.ts'} {@example 'setup/ts/src/app/app.module.ts'}
@ -153,7 +153,7 @@ Angular offers a variety of bootstrapping options targeting multiple platforms.
This page describes two options, both targeting the browser. This page describes 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)
compiles the application in the browser and then launches the app. compiles the application in the browser and then launches the app.
@ -206,7 +206,7 @@ This is the last time you'll look at `main.ts`.
## Declare directives and components ## Declare directives and components
As the app evolves, As the app evolves,
the first addition is a `HighlightDirective`, an [attribute directive](attribute-directives.html) the first addition is a `HighlightDirective`, an [attribute directive](guide/attribute-directives)
that sets the background color of the attached element. that sets the background color of the attached element.
{@example 'ngmodule/ts/src/app/highlight.directive.ts'} {@example 'ngmodule/ts/src/app/highlight.directive.ts'}
@ -251,9 +251,9 @@ Import the `TitleComponent` class and add it to the module's `declarations`:
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) page describes The [Dependency Injection](guide/dependency-injection) 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](guide/dependency-injection) at different levels of the
application's component tree. application's component tree.
A module can add providers to the application's root dependency injector, making those services A module can add providers to the application's root dependency injector, making those services
@ -306,7 +306,7 @@ More accurately, `NgIf` is declared in `CommonModule` from `@angular/common`.
`CommonModule` contributes many of the common directives that applications need, including `ngIf` and `ngFor`. `CommonModule` contributes many of the common directives that applications need, including `ngIf` and `ngFor`.
`BrowserModule` imports `CommonModule` and [re-exports](../cookbook/ngmodule-faq.html#q-re-export) it. `BrowserModule` imports `CommonModule` and [re-exports](cookbook/ngmodule-faq) it.
The net effect is that an importer of `BrowserModule` gets `CommonModule` directives automatically.Many familiar Angular directives don't belong to `CommonModule`. The net effect is that an importer of `BrowserModule` gets `CommonModule` directives automatically.Many familiar Angular directives don't belong to `CommonModule`.
For example, `NgModel` and `RouterLink` belong to Angular's `FormsModule` and `RouterModule` respectively. For example, `NgModel` and `RouterLink` belong to Angular's `FormsModule` and `RouterModule` respectively.
You must import those modules before you can use their directives. You must import those modules before you can use their directives.
@ -316,16 +316,16 @@ a form component that imports form support from the Angular `FormsModule`.
### Add the _ContactComponent_ ### Add the _ContactComponent_
[Angular forms](forms.html) are a great way to manage user data entry. [Angular forms](guide/forms) are a great way to manage user data entry.
The `ContactComponent` presents a "contact editor," The `ContactComponent` presents a "contact editor,"
implemented with Angular forms in the [template-driven form](forms.html#template-driven) style. implemented with Angular forms in the [template-driven form](guide/forms) style.
### Angular form styles ### Angular form styles
You can write Angular form components in You can write Angular form components in
template-driven or template-driven or
[reactive](../cookbook/dynamic-form.html) style. [reactive](cookbook/dynamic-form) style.
<!-- CF: this link goes to a page titled "Dynamic Forms". Should the link text be "dynamic" instead of "reactive"? --> <!-- CF: this link goes to a page titled "Dynamic Forms". Should the link text be "dynamic" instead of "reactive"? -->
The following sample imports the `FormsModule` from `@angular/forms` because The following sample imports the `FormsModule` from `@angular/forms` because
@ -338,7 +338,7 @@ Add an element with that name to the `AppComponent` template, just below the `<a
{@example 'ngmodule/ts/src/app/app.component.1b.ts' region='template'} {@example 'ngmodule/ts/src/app/app.component.1b.ts' region='template'}
Form components are often complex. The `ContactComponent` has its own `ContactService` Form components are often complex. The `ContactComponent` has its own `ContactService`
and [custom pipe](pipes.html#custom-pipes) (called `Awesome`), and [custom pipe](guide/pipes) (called `Awesome`),
and an alternative version of the `HighlightDirective`. and an alternative version of the `HighlightDirective`.
To make it manageable, place all contact-related material in an `src/app/contact` folder To make it manageable, place all contact-related material in an `src/app/contact` folder
@ -434,7 +434,7 @@ To work around this, create an alias for the contact version using the `as` Java
This solves the immediate issue of referencing both directive _types_ in the same file but This solves the immediate issue of referencing both directive _types_ in the same file but
leaves another issue unresolved. leaves another issue unresolved.
You'll learn more about that issue later in this page, in [Resolve directive conflicts](#resolve-conflicts). You'll learn more about that issue later in this page, in [Resolve directive conflicts](guide/ngmodule#resolve-conflicts).
### Provide the _ContactService_ ### Provide the _ContactService_
The `ContactComponent` displays contacts retrieved by the `ContactService`, The `ContactComponent` displays contacts retrieved by the `ContactService`,
which Angular injects into its constructor. which Angular injects into its constructor.
@ -473,8 +473,8 @@ Now you can inject `ContactService` (like `UserService`) into any component in t
To inject `ContactService`, you must first import its _type_. To inject `ContactService`, you must first import its _type_.
Only Contact components should import the `ContactService` type. Only Contact components should import the `ContactService` type.
Read more in the [How do I restrict service scope to a module?](../cookbook/ngmodule-faq.html#q-component-scoped-providers) section Read more in the [How do I restrict service scope to a module?](cookbook/ngmodule-faq) section
of the [NgModule FAQs](../cookbook/ngmodule-faq.html) page. of the [NgModule FAQs](cookbook/ngmodule-faq) page.
### Run the app ### Run the app
Everything is in place to run the application with its contact editor. Everything is in place to run the application with its contact editor.
@ -549,7 +549,7 @@ Try the example:
This section seems like more of an introduction to the next section, "Feature modules". This section seems like more of an introduction to the next section, "Feature modules".
Consider moving this section to be a child section of "Feature modules", or striking "Resolve" from this title. --> Consider moving this section to be a child section of "Feature modules", or striking "Resolve" from this title. -->
An issue arose [earlier](#import-name-conflict) when you declared the contact's `HighlightDirective` because An issue arose [earlier](guide/ngmodule#import-name-conflict) when you declared the contact's `HighlightDirective` because
you already had a `HighlightDirective` class at the application level. you already had a `HighlightDirective` class at the application level.
The selectors of the two directives both highlight the attached element with a different color. The selectors of the two directives both highlight the attached element with a different color.
@ -670,8 +670,8 @@ Before `ContactComponent` can bind with `[(ngModel)]`, its `ContactModule` must
~~~ ~~~
You also replaced `BrowserModule` by `CommonModule`, for reasons explained in the You also replaced `BrowserModule` by `CommonModule`, for reasons explained in the
[Should I import BrowserModule or CommonModule?](../cookbook/ngmodule-faq.html#q-browser-vs-common-module) [Should I import BrowserModule or CommonModule?](cookbook/ngmodule-faq)
section of the [NgModule FAQs](../cookbook/ngmodule-faq.html) page. section of the [NgModule FAQs](cookbook/ngmodule-faq) page.
You _declare_ the contact component, directive, and pipe in the module `declarations`. You _declare_ the contact component, directive, and pipe in the module `declarations`.
@ -762,14 +762,14 @@ The module does _not_ import `HeroModule` or `CrisisModule`.
They'll be fetched and mounted asynchronously when the user navigates to one of their routes. They'll be fetched and mounted asynchronously when the user navigates to one of their routes.
The significant change from version 2 is the addition of the *AppRoutingModule* to the module `imports`. The significant change from version 2 is the addition of the *AppRoutingModule* to the module `imports`.
The `AppRoutingModule` is a [routing module](../guide/router.html#routing-module) The `AppRoutingModule` is a [routing module](guide/router)
that handles the app's routing concerns. that handles the app's routing concerns.
### App routing ### App routing
{@example 'ngmodule/ts/src/app/app-routing.module.ts'} {@example 'ngmodule/ts/src/app/app-routing.module.ts'}
The router is the subject of the [Routing & Navigation](router.html) page, so this section skips many of the details and The router is the subject of the [Routing & Navigation](guide/router) page, so this section skips many of the details and
concentrates on the intersection of NgModules and routing. concentrates on the intersection of NgModules and routing.
The `app-routing.module.ts` file defines three routes. The `app-routing.module.ts` file defines three routes.
@ -839,8 +839,8 @@ _forRoot_ and _forChild_ are conventional names for methods that
deliver different `import` values to root and feature modules. deliver different `import` values to root and feature modules.
Angular doesn't recognize them but Angular developers do. Angular doesn't recognize them but Angular developers do.
[Follow this convention](../cookbook/ngmodule-faq.html#q-for-root) if you write a similar module [Follow this convention](cookbook/ngmodule-faq) if you write a similar module
that has both shared [declarables](../cookbook/ngmodule-faq.html#q-declarable) and services. that has both shared [declarables](cookbook/ngmodule-faq) and services.
~~~ ~~~
@ -866,7 +866,7 @@ that has both shared [declarables](../cookbook/ngmodule-faq.html#q-declarable) a
Now that you navigate to `ContactComponent` with the router, there's no reason to make it public. Now that you navigate to `ContactComponent` with the router, there's no reason to make it public.
Also, `ContactComponent` doesn't need a selector. Also, `ContactComponent` doesn't need a selector.
No template will ever again reference this `ContactComponent`. No template will ever again reference this `ContactComponent`.
It's gone from the [AppComponent template](#app-component-template). It's gone from the [AppComponent template](guide/ngmodule#app-component-template).
{@a hero-module} {@a hero-module}
@ -923,15 +923,15 @@ a more interesting and useful example. Its file structure is as follows:
</aio-filetree> </aio-filetree>
This is the child routing scenario familiar to readers of the This is the child routing scenario familiar to readers of the
[Child routing component](router.html#child-routing-component) section of the [Child routing component](guide/router) section of the
[Routing & Navigation](router.html#child-routing-component) page. [Routing & Navigation](guide/router) 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`).
Both components delegate to the `HeroService` to fetch and save data. Both components delegate to the `HeroService` to fetch and save data.
Yet another `HighlightDirective` colors elements in yet a different shade. Yet another `HighlightDirective` colors elements in yet a different shade.
In the next section, [Shared modules](#shared-module "Shared modules"), you'll resolve the repetition and inconsistencies. In the next section, [Shared modules](guide/ngmodule#shared-module "Shared modules"), you'll resolve the repetition and inconsistencies.
The `HeroModule` is a feature module like any other. The `HeroModule` is a feature module like any other.
@ -1006,7 +1006,7 @@ and only one provider of it.
`UserService` is an application-wide singleton. `UserService` is an application-wide singleton.
You don't want each module to have its own separate instance. You don't want each module to have its own separate instance.
Yet there is [a real danger](../cookbook/ngmodule-faq.html#q-why-it-is-bad) of that happening Yet there is [a real danger](cookbook/ngmodule-faq) of that happening
<!-- CF: This link goes to the top of the NgModule FAQs page. <!-- CF: This link goes to the top of the NgModule FAQs page.
It looks like it is supposed to go to a specific question/section within the page. --> It looks like it is supposed to go to a specific question/section within the page. -->
if the `SharedModule` provides the `UserService`. if the `SharedModule` provides the `UserService`.
@ -1140,7 +1140,7 @@ A module that adds providers to the application can offer a facility for configu
By convention, the `forRoot` static method both provides and configures services at the same time. By convention, the `forRoot` static method both provides and configures services at the same time.
It takes a service configuration object and returns a It takes a service configuration object and returns a
[ModuleWithProviders](../api/core/index/ModuleWithProviders-interface.html), which is [ModuleWithProviders](api/core/index/ModuleWithProviders-interface), which is
a simple object with the following properties: a simple object with the following properties:
* `ngModule`: the `CoreModule` class * `ngModule`: the `CoreModule` class
* `providers`: the configured providers * `providers`: the configured providers
@ -1189,7 +1189,7 @@ Remember to _import_ the result; don't add it to any other `@NgModule` list.
## Prevent reimport of the _CoreModule_ ## Prevent reimport of the _CoreModule_
Only the root `AppModule` should import the `CoreModule`. Only the root `AppModule` should import the `CoreModule`.
[Bad things happen](../cookbook/ngmodule-faq.html#q-why-it-is-bad) if a lazy-loaded module imports it. [Bad things happen](cookbook/ngmodule-faq) if a lazy-loaded module imports it.
<!-- CF: Again, this link goes to the top of the NgModule FAQs page. <!-- CF: Again, this link goes to the top of the NgModule FAQs page.
It looks like it is supposed to go to a specific question/section within the page. --> It looks like it is supposed to go to a specific question/section within the page. -->
@ -1226,5 +1226,5 @@ You made it! You can examine and download the complete source for this final ver
### Frequently asked questions ### Frequently asked questions
Now that you understand NgModules, you may be interested Now that you understand NgModules, you may be interested
in the companion [NgModule FAQs](../cookbook/ngmodule-faq.html "NgModule FAQs") page in the companion [NgModule FAQs](cookbook/ngmodule-faq) page
with its ready answers to specific design and implementation questions. with its ready answers to specific design and implementation questions.

16
aio/content/guide/npm-packages.md
View File

@ -19,7 +19,7 @@ Older versions produce errors.
Consider using [nvm](https://github.com/creationix/nvm) for managing multiple Consider using [nvm](https://github.com/creationix/nvm) for managing multiple
versions of node and npm. You may need [nvm](https://github.com/creationix/nvm) if 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. you already have projects running on your machine that use other versions of node and npm.
During [Setup](setup.html), a <a href="https://docs.npmjs.com/files/package.json" target="_blank">package.json</a> During [Setup](guide/setup), a <a href="https://docs.npmjs.com/files/package.json" target="_blank">package.json</a>
file is installed with a comprehensive starter set of file is installed with a comprehensive starter set of
packages as specified in the `dependencies` and `devDependencies` sections. packages as specified in the `dependencies` and `devDependencies` sections.
@ -34,7 +34,7 @@ This page explains what each package does. You can make substitutions later to s
## *dependencies* and *devDependencies* ## *dependencies* and *devDependencies*
The `package.json` includes two sets of packages, The `package.json` includes two sets of packages,
[dependencies](#dependencies) and [devDependencies](#dev-dependencies). [dependencies](guide/npm-packages#dependencies) and [devDependencies](guide/npm-packages#dev-dependencies).
The *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.
@ -73,8 +73,8 @@ the pieces that help render into the DOM.
This package also includes the `bootstrapStatic()` method This package also includes the `bootstrapStatic()` method
for bootstrapping applications for production builds that pre-compile templates offline. for bootstrapping applications for production builds that pre-compile templates offline.
***@angular/platform-browser-dynamic***: Includes [Providers](../api/core/index/Provider-type-alias.html) ***@angular/platform-browser-dynamic***: Includes [Providers](api/core/index/Provider-type-alias)
and a [bootstrap](ngmodule.html#bootstrap) method for applications that and a [bootstrap](guide/ngmodule) method for applications that
compile templates on the client. Don’t use offline compilation. compile templates on the client. Don’t use offline compilation.
Use this package for bootstrapping during development and for bootstrapping plunker samples. Use this package for bootstrapping during development and for bootstrapping plunker samples.
@ -102,7 +102,7 @@ Install these polyfills using the npm packages that Angular lists in the *peerDe
You must list these packages in the `dependencies` section of your own `package.json`. You must list these packages in the `dependencies` section of your own `package.json`.
For background on this requirement, see [Why peerDependencies?](#why-peer-dependencies).***core-js***: Patches the global context (window) with essential features of ES2015 (ES6). For background on this requirement, see [Why peerDependencies?](guide/npm-packages#why-peer-dependencies).***core-js***: Patches the global context (window) with essential features of ES2015 (ES6).
You may substitute an alternative polyfill that provides the same core APIs. You may substitute an alternative polyfill that provides the same core APIs.
When these APIs are implemented by the major browsers, this dependency will become unnecessary. When these APIs are implemented by the major browsers, this dependency will become unnecessary.
@ -124,7 +124,7 @@ without waiting for Angular updates.
***angular-in-memory-web-api***: An Angular-supported library that simulates a remote server's web api ***angular-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, samples, and early stage development (before you even have a server). Good for demos, samples, and early stage development (before you even have a server).
Read about it in the [HTTP Client](server-communication.html#in-mem-web-api) page. Read about it in the [HTTP Client](guide/server-communication) 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 samples improve their appearance with *bootstrap*. Some of the samples improve their appearance with *bootstrap*.
@ -147,7 +147,7 @@ with excellent support for Angular apps that use routing.
the TypeScript language server, including the *tsc* TypeScript compiler. the TypeScript language server, including the *tsc* TypeScript compiler.
***@types/\****: TypeScript definition files. ***@types/\****: TypeScript definition files.
Learn more about it in the [TypeScript Configuration](typescript-configuration.html#typings) guide. Learn more about it in the [TypeScript Configuration](guide/typescript-configuration) guide.
@ -158,7 +158,7 @@ There isn't a [*peerDependencies*](https://nodejs.org/en/blog/npm/peer-dependenc
But Angular has a *peerDependencies* section in But Angular has a *peerDependencies* section in
*its* `package.json`, which has important consequences for your application. *its* `package.json`, which has important consequences for your application.
This section explains why you load the [polyfill](#polyfills) *dependency* This section explains why you load the [polyfill](guide/npm-packages#polyfills) *dependency*
packages in the QuickStart application's `package.json`, packages in the QuickStart application's `package.json`,
and why you'll need those packages in your own applications. and why you'll need those packages in your own applications.

82
aio/content/guide/reactive-forms.md
View File

@ -12,23 +12,23 @@ This guide explains reactive forms as you follow the steps to build a "Hero Deta
{@a toc} {@a toc}
## Contents ## Contents
- [Introduction to reactive forms](#intro) - [Introduction to reactive forms](guide/reactive-forms#intro)
- [Setup](#setup) - [Setup](guide/reactive-forms#setup)
- [Create a data model](#data-model) - [Create a data model](guide/reactive-forms#data-model)
- [Create a _reactive forms_ component](#create-component) - [Create a _reactive forms_ component](guide/reactive-forms#create-component)
- [Create its template file](#create-template) - [Create its template file](guide/reactive-forms#create-template)
- [Import the _ReactiveFormsModule_](#import) - [Import the _ReactiveFormsModule_](guide/reactive-forms#import)
- [Display the _HeroDetailComponent_](#update) - [Display the _HeroDetailComponent_](guide/reactive-forms#update)
- [Add a FormGroup](#formgroup) - [Add a FormGroup](guide/reactive-forms#formgroup)
- [Taking a look at the form model](#json) - [Taking a look at the form model](guide/reactive-forms#json)
- [Introduction to _FormBuilder_](#formbuilder) - [Introduction to _FormBuilder_](guide/reactive-forms#formbuilder)
- [Validators.required](#validators) - [Validators.required](guide/reactive-forms#validators)
- [Nested FormGroups](#grouping) - [Nested FormGroups](guide/reactive-forms#grouping)
- [Inspect _FormControl_ properties](#properties) - [Inspect _FormControl_ properties](guide/reactive-forms#properties)
- [Set form model data using _setValue_ and _patchValue_](#set-data) - [Set form model data using _setValue_ and _patchValue_](guide/reactive-forms#set-data)
- [Use _FormArray_ to present an array of _FormGroups_](#form-array) - [Use _FormArray_ to present an array of _FormGroups_](guide/reactive-forms#form-array)
- [Observe control changes](#observe-control) - [Observe control changes](guide/reactive-forms#observe-control)
- [Save form data](#save) - [Save form data](guide/reactive-forms#save)
Try the <live-example plnkr="final" title="Reactive Forms (final) in Plunker">Reactive Forms live-example</live-example>. Try the <live-example plnkr="final" title="Reactive Forms (final) in Plunker">Reactive Forms live-example</live-example>.
@ -65,7 +65,7 @@ the form controls and pull user-changed values back out. The component can
observe changes in form control state and react to those changes. observe changes in form control state and react to those changes.
One advantage of working with form control objects directly is that value and validity updates One advantage of working with form control objects directly is that value and validity updates
are [always synchronous and under your control](#async-vs-sync "Async vs sync"). are [always synchronous and under your control](guide/reactive-forms#async-vs-sync "Async vs sync").
You won't encounter the timing issues that sometimes plague a template-driven form You won't encounter the timing issues that sometimes plague a template-driven form
and reactive forms can be easier to unit test. and reactive forms can be easier to unit test.
@ -82,7 +82,7 @@ but it does facilitate the reactive programming approach should you choose to us
### _Template-driven_ forms ### _Template-driven_ forms
_Template-driven_ forms, introduced in the [Template guide](forms.html), take a completely different approach. _Template-driven_ forms, introduced in the [Template guide](guide/forms), take a completely different approach.
You place HTML form controls (such as `<input>` and `<select>`) in the component template and You place HTML form controls (such as `<input>` and `<select>`) in the component template and
bind them to _data model_ properties in the component, using directives bind them to _data model_ properties in the component, using directives
@ -96,7 +96,7 @@ Angular updates the mutable _data model_ with user changes as they happen.
For this reason, the `ngModel` directive is not part of the ReactiveFormsModule. For this reason, the `ngModel` directive is not part of the ReactiveFormsModule.
While this means less code in the component class, While this means less code in the component class,
[template-driven forms are asynchronous](#async-vs-sync "Async vs sync") [template-driven forms are asynchronous](guide/reactive-forms#async-vs-sync "Async vs sync")
which may complicate development in more advanced scenarios. which may complicate development in more advanced scenarios.
@ -116,7 +116,7 @@ That means you must wait a tick before manipulating any of the controls
from within the component class. from within the component class.
For example, if you inject the form control with a `@ViewChild(NgForm)` query and examine it in the For example, if you inject the form control with a `@ViewChild(NgForm)` query and examine it in the
[`ngAfterViewInit` lifecycle hook](lifecycle-hooks.html#afterview "Lifecycle hooks guide: AfterView"), [`ngAfterViewInit` lifecycle hook](guide/lifecycle-hooks),
you'll discover that it has no children. you'll discover that it has no children.
You must wait a tick, using `setTimeout`, before you can You must wait a tick, using `setTimeout`, before you can
extract a value from a control, test its validity, or set it to a new value. extract a value from a control, test its validity, or set it to a new value.
@ -136,17 +136,17 @@ You may decide to use both in the same application.
The balance of this _reactive forms_ guide explores the _reactive_ paradigm and The balance of this _reactive forms_ guide explores the _reactive_ paradigm and
concentrates exclusively on reactive forms techniques. concentrates exclusively on reactive forms techniques.
For information on _template-driven forms_, see the [_Forms_](forms.html) guide. For information on _template-driven forms_, see the [_Forms_](guide/forms) guide.
In the next section, you'll set up your project for the reactive form demo. In the next section, you'll set up your project for the reactive form demo.
Then you'll learn about the [Angular form classes](#essentials) and how to use them in a reactive form. Then you'll learn about the [Angular form classes](guide/reactive-forms#essentials) and how to use them in a reactive form.
{@a setup} {@a setup}
## Setup ## Setup
Follow the steps in the [_Setup_ guide](../setup.html "Setup guide") Follow the steps in the [_Setup_ guide](setup)
for creating a new project folder (perhaps called `reactive-forms`) for creating a new project folder (perhaps called `reactive-forms`)
based on the _QuickStart seed_. based on the _QuickStart seed_.
@ -181,7 +181,7 @@ Now enter the `@Component` decorator that specifies the `HeroDetailComponent` me
{@example 'reactive-forms/ts/src/app/hero-detail.component.ts' region='metadata'} {@example 'reactive-forms/ts/src/app/hero-detail.component.ts' region='metadata'}
The `moduleId: module.id` lets you use The `moduleId: module.id` lets you use
[component-relative paths](../cookbook/component-relative-paths.html) in file URLs [component-relative paths](cookbook/component-relative-paths) in file URLs
such as when specifying the `templateUrl`. such as when specifying the `templateUrl`.
Next, create an exported `HeroDetailComponent` class with a `FormControl`. Next, create an exported `HeroDetailComponent` class with a `FormControl`.
@ -202,7 +202,7 @@ This simple control doesn't have data or validators.
In real apps, most form controls have both. In real apps, most form controls have both.
This guide touches only briefly on `Validators`. For an in-depth look at them, This guide touches only briefly on `Validators`. For an in-depth look at them,
read the [Form Validation](../cookbook/form-validation.html) cookbook. read the [Form Validation](cookbook/form-validation) cookbook.
@ -256,21 +256,21 @@ Revise the `AppComponent` template so it displays the `HeroDetailComponent`.
### Essential form classes ### Essential form classes
It may be helpful to read a brief description of the core form classes. It may be helpful to read a brief description of the core form classes.
* [_AbstractControl_](../api/forms/index/AbstractControl-class.html "API Reference: AbstractControl") * [_AbstractControl_](api/forms/index/AbstractControl-class)
is the abstract base class for the three concrete form control classes: is the abstract base class for the three concrete form control classes:
`FormControl`, `FormGroup`, and `FormArray`. `FormControl`, `FormGroup`, and `FormArray`.
It provides their common behaviors and properties, some of which are _observable_. It provides their common behaviors and properties, some of which are _observable_.
* [_FormControl_](../api/forms/index/FormControl-class.html "API Reference: FormControl") * [_FormControl_](api/forms/index/FormControl-class)
tracks the value and validity status of an _individual_ form control. tracks the value and validity status of an _individual_ form control.
It corresponds to an HTML form control such as an input box or selector. It corresponds to an HTML form control such as an input box or selector.
* [_FormGroup_](../api/forms/index/FormGroup-class.html "API Reference: FormGroup") * [_FormGroup_](api/forms/index/FormGroup-class)
tracks the value and validity state of a _group_ of `AbstractControl` instances. tracks the value and validity state of a _group_ of `AbstractControl` instances.
The group's properties include its child controls. The group's properties include its child controls.
The top-level form in your component is a `FormGroup`. The top-level form in your component is a `FormGroup`.
* [_FormArray_](../api/forms/index/FormArray-class.html "API Reference: FormArray") * [_FormArray_](api/forms/index/FormArray-class)
tracks the value and validity state of a numerically indexed _array_ of `AbstractControl` instances. tracks the value and validity state of a numerically indexed _array_ of `AbstractControl` instances.
You'll learn more about these classes as you work through this guide. You'll learn more about these classes as you work through this guide.
@ -440,7 +440,7 @@ Using `Validators.required` is optional for the rest of the guide.
It remains in each of the following examples with the same configuration. It remains in each of the following examples with the same configuration.
For more on validating Angular forms, see the For more on validating Angular forms, see the
[Form Validation](../cookbook/form-validation.html) guide. [Form Validation](cookbook/form-validation) guide.
### More FormControls ### More FormControls
A hero has more than a name. A hero has more than a name.
A hero has an address, a super power and sometimes a sidekick too. A hero has an address, a super power and sometimes a sidekick too.
@ -487,9 +487,9 @@ You tie these controls to the template HTML elements in the same way,
specifiying the `FormControl` name with the `formControlName` directive. specifiying the `FormControl` name with the `formControlName` directive.
See the API reference for more information about See the API reference for more information about
[radio buttons](../api/forms/index/RadioControlValueAccessor-directive.html "API: RadioControlValueAccessor"), [radio buttons](api/forms/index/RadioControlValueAccessor-directive),
[selects](../api/forms/index/SelectControlValueAccessor-directive.html "API: SelectControlValueAccessor"), and [selects](api/forms/index/SelectControlValueAccessor-directive), and
[checkboxes](../api/forms/index/CheckboxControlValueAccessor-directive.html "API: CheckboxControlValueAccessor"). [checkboxes](api/forms/index/CheckboxControlValueAccessor-directive).
@ -654,12 +654,12 @@ such as one of the following:
</table> </table>
Learn about other `FormControl` properties in the Learn about other `FormControl` properties in the
[_AbstractControl_](../api/forms/index/AbstractControl-class.html) API reference. [_AbstractControl_](api/forms/index/AbstractControl-class) API reference.
One common reason for inspecting `FormControl` properties is to One common reason for inspecting `FormControl` properties is to
make sure the user entered valid values. make sure the user entered valid values.
Read more about validating Angular forms in the Read more about validating Angular forms in the
[Form Validation](../cookbook/form-validation.html) guide. [Form Validation](cookbook/form-validation) guide.
@ -704,7 +704,7 @@ There are two significant differences between these models:
1. The `Hero` has an `id`. The form model does not because you generally don't show primary keys to users. 1. The `Hero` has an `id`. The form model does not because you generally don't show primary keys to users.
1. The `Hero` has an array of addresses. This form model presents only one address, 1. The `Hero` has an array of addresses. This form model presents only one address,
a choice [revisited below](#form-array "Form arrays"). a choice [revisited below](guide/reactive-forms#form-array "Form arrays").
Nonetheless, the two models are pretty close in shape and you'll see in a moment how this alignment facilitates copying the _data model_ properties Nonetheless, the two models are pretty close in shape and you'll see in a moment how this alignment facilitates copying the _data model_ properties
to the _form model_ with the `patchValue` and `setValue` methods. to the _form model_ with the `patchValue` and `setValue` methods.
@ -767,7 +767,7 @@ values and does not throw helpful errors.
Now you know _how_ to set the _form model_ values. But _when_ do you set them? Now you know _how_ to set the _form model_ values. But _when_ do you set them?
The answer depends upon when the component gets the _data model_ values. The answer depends upon when the component gets the _data model_ values.
The `HeroDetailComponent` in this reactive forms sample is nested within a _master/detail_ `HeroListComponent` ([discussed below](#hero-list)). The `HeroDetailComponent` in this reactive forms sample is nested within a _master/detail_ `HeroListComponent` ([discussed below](guide/reactive-forms#hero-list)).
The `HeroListComponent` displays hero names to the user. The `HeroListComponent` displays hero names to the user.
When the user clicks on a hero, the list component passes the selected hero into the `HeroDetailComponent` When the user clicks on a hero, the list component passes the selected hero into the `HeroDetailComponent`
by binding to its `hero` input property. by binding to its `hero` input property.
@ -777,7 +777,7 @@ by binding to its `hero` input property.
In this approach, the value of `hero` in the `HeroDetailComponent` changes In this approach, the value of `hero` in the `HeroDetailComponent` changes
every time the user selects a new hero. every time the user selects a new hero.
You should call _setValue_ in the [ngOnChanges](lifecyle-hooks.html#onchanges) You should call _setValue_ in the [ngOnChanges](guide/lifecyle-hooks)
hook, which Angular calls whenever the input `hero` property changes hook, which Angular calls whenever the input `hero` property changes
as the following steps demonstrate. as the following steps demonstrate.
@ -839,11 +839,11 @@ A "Refresh" button clears the hero list and the current selected hero before ref
The remaining `HeroListComponent` and `HeroService` implementation details are not relevant to understanding reactive forms. The remaining `HeroListComponent` and `HeroService` implementation details are not relevant to understanding reactive forms.
The techniques involved are covered elsewhere in the documentation, including the _Tour of Heroes_ The techniques involved are covered elsewhere in the documentation, including the _Tour of Heroes_
[here](../tutorial/toh-pt3.html "ToH: Multiple Components") and [here](../tutorial/toh-pt4.html "ToH: Services"). [here](tutorial/toh-pt3) and [here](tutorial/toh-pt4).
If you're coding along with the steps in this reactive forms tutorial, If you're coding along with the steps in this reactive forms tutorial,
create the pertinent files based on the create the pertinent files based on the
[source code displayed below](#source-code "Reactive Forms source code"). [source code displayed below](guide/reactive-forms#source-code "Reactive Forms source code").
Notice that `hero-list.component.ts` imports `Observable` and `finally` while `hero.service.ts` imports `Observable`, `of`, Notice that `hero-list.component.ts` imports `Observable` and `finally` while `hero.service.ts` imports `Observable`, `of`,
and `delay` from `rxjs`. and `delay` from `rxjs`.
Then return here to learn about _form array_ properties. Then return here to learn about _form array_ properties.

252
aio/content/guide/router.md
View File

@ -5,7 +5,7 @@ Routing & Navigation
Discover the basics of screen navigation with the Angular Router. Discover the basics of screen navigation with the Angular Router.
@description @description
The Angular **`Router`** enables navigation from one [view](./glossary.html#view) to the next The Angular **`Router`** enables navigation from one [view](guide/glossary) to the next
as users perform application tasks. as users perform application tasks.
This guide covers the router's primary features, illustrating them through the evolution This guide covers the router's primary features, illustrating them through the evolution
@ -30,85 +30,85 @@ or in response to some other stimulus from any source. And the router logs activ
in the browser's history journal so the back and forward buttons work as well. in the browser's history journal so the back and forward buttons work as well.
# Contents # Contents
* [The Basics](#basics) * [The Basics](guide/router#basics)
- [`<base href>`](#basics-base-href) - [`<base href>`](guide/router#basics-base-href)
- [Router imports](#basics-router-imports) - [Router imports](guide/router#basics-router-imports)
- [Configuration](#basics-config) - [Configuration](guide/router#basics-config)
- [Router outlet](#basics-router-outlet) - [Router outlet](guide/router#basics-router-outlet)
- [Router links](#basics-router-links) - [Router links](guide/router#basics-router-links)
- [Router state](#basics-router-state) - [Router state](guide/router#basics-router-state)
- [Summary](#basics-summary) - [Summary](guide/router#basics-summary)
* [The sample application](#sample-app-intro) * [The sample application](guide/router#sample-app-intro)
* [Milestone 1: Getting started with the router](#getting-started) * [Milestone 1: Getting started with the router](guide/router#getting-started)
- [Setting the base href](#base-href) - [Setting the base href](guide/router#base-href)
- [Importing from the router library](#import) - [Importing from the router library](guide/router#import)
- [Define routes](#route-config) - [Define routes](guide/router#route-config)
- [The `AppComponent` shell](#shell) - [The `AppComponent` shell](guide/router#shell)
- [RouterOutlet](#router-outlet) - [RouterOutlet](guide/router#router-outlet)
- [`RouterLink binding`](#router-link) - [`RouterLink binding`](guide/router#router-link)
- [`RouterLinkActive` binding](#router-link-active) - [`RouterLinkActive` binding](guide/router#router-link-active)
- [Wildcard route](#wildcard) - [Wildcard route](guide/router#wildcard)
- [The default route to heroes](#default-route) - [The default route to heroes](guide/router#default-route)
* [Milestone 2: Routing module](#routing-module) * [Milestone 2: Routing module](guide/router#routing-module)
- [Refactor the routing configuration into a routing module](#routing-refactor) - [Refactor the routing configuration into a routing module](guide/router#routing-refactor)
- [Do you need a Routing Module?](#why-routing-module) - [Do you need a Routing Module?](guide/router#why-routing-module)
* [Milestone 3: Heroes feature](#heroes-feature) * [Milestone 3: Heroes feature](guide/router#heroes-feature)
- [Add heroes functionality](#heroes-functionality) - [Add heroes functionality](guide/router#heroes-functionality)
- [Hero feature routing requirements](#hero-routing-requirements) - [Hero feature routing requirements](guide/router#hero-routing-requirements)
- [Hero feature route configuration](#hero-routing-module) - [Hero feature route configuration](guide/router#hero-routing-module)
- [Add the routing module to the _HeroesModule_](#adding-routing-module) - [Add the routing module to the _HeroesModule_](guide/router#adding-routing-module)
- [Remove duplicate hero routes](#remove-duplicate-hero-routes) - [Remove duplicate hero routes](guide/router#remove-duplicate-hero-routes)
- [Import hero module into AppModule](#merge-hero-routes) - [Import hero module into AppModule](guide/router#merge-hero-routes)
- [Module import order matters](#routing-module-order) - [Module import order matters](guide/router#routing-module-order)
- [Route Definition with a parameter](#route-def-with-parameter) - [Route Definition with a parameter](guide/router#route-def-with-parameter)
- [Navigate to hero detail imperatively](#navigate) - [Navigate to hero detail imperatively](guide/router#navigate)
- [Setting the route parameters in the list view](#route-parameters) - [Setting the route parameters in the list view](guide/router#route-parameters)
- [ActivatedRoute: the one-stop-shop for route information](#activated-route) - [ActivatedRoute: the one-stop-shop for route information](guide/router#activated-route)
- [Observable params and component reuse](#reuse) - [Observable params and component reuse](guide/router#reuse)
- [Snapshot: the _no-observable_ alternative](#snapshot) - [Snapshot: the _no-observable_ alternative](guide/router#snapshot)
- [Navigating back to the list component](#nav-to-list) - [Navigating back to the list component](guide/router#nav-to-list)
- [Route Parameters: Required or optional?](#optional-route-parameters) - [Route Parameters: Required or optional?](guide/router#optional-route-parameters)
- [Heroes list: optionally selecting a hero](#optionally-selecting) - [Heroes list: optionally selecting a hero](guide/router#optionally-selecting)
- [Route parameters in the *ActivatedRoute* service](#route-parameters-activated-route) - [Route parameters in the *ActivatedRoute* service](guide/router#route-parameters-activated-route)
- [Adding animations to the routed component](#route-animation) - [Adding animations to the routed component](guide/router#route-animation)
- [Milestone 3 wrap up](#milestone-3-wrap-up) - [Milestone 3 wrap up](guide/router#milestone-3-wrap-up)
* [Milestone 4: Crisis center feature](#milestone-4) * [Milestone 4: Crisis center feature](guide/router#milestone-4)
- [A crisis center with child routes](#crisis-child-routes) - [A crisis center with child routes](guide/router#crisis-child-routes)
- [Child routing component](#child-routing-component) - [Child routing component](guide/router#child-routing-component)
- [Child route configuration](#child-route-config) - [Child route configuration](guide/router#child-route-config)
- [Import crisis center module into the _AppModule_ routes](#import-crisis-module) - [Import crisis center module into the _AppModule_ routes](guide/router#import-crisis-module)
- [Relative navigation](#relative-navigation) - [Relative navigation](guide/router#relative-navigation)
- [Navigate to crisis detail with a relative URL](#nav-to-crisis) - [Navigate to crisis detail with a relative URL](guide/router#nav-to-crisis)
- [Displaying multiple routes in named outlets](#named-outlets) - [Displaying multiple routes in named outlets](guide/router#named-outlets)
- [Secondary routes](#secondary-routes) - [Secondary routes](guide/router#secondary-routes)
- [Add a secondary route](#add-secondary-route) - [Add a secondary route](guide/router#add-secondary-route)
- [Secondary route navigation: merging routes during navigation](#secondary-route-navigation) - [Secondary route navigation: merging routes during navigation](guide/router#secondary-route-navigation)
- [Clearing secondary routes](#clear-secondary-routes) - [Clearing secondary routes](guide/router#clear-secondary-routes)
* [Milestone 5: Route guards](#guards) * [Milestone 5: Route guards](guide/router#guards)
- [`CanActivate`: requiring authentication](#can-activate-guard) - [`CanActivate`: requiring authentication](guide/router#can-activate-guard)
- [Component-less route: grouping routes without a component](#component-less-route) - [Component-less route: grouping routes without a component](guide/router#component-less-route)
- [Guard the admin feature](#guard-admin-feature) - [Guard the admin feature](guide/router#guard-admin-feature)
- [Teach *AuthGuard* to authenticate](#teach-auth) - [Teach *AuthGuard* to authenticate](guide/router#teach-auth)
- [Add the login component](#add-login-component) - [Add the login component](guide/router#add-login-component)
- [`CanActivateChild`: guarding child routes](#can-activate-child-guard) - [`CanActivateChild`: guarding child routes](guide/router#can-activate-child-guard)
- [`CanDeactivate`: handling unsaved changes](#can-deactivate-guard) - [`CanDeactivate`: handling unsaved changes](guide/router#can-deactivate-guard)
- [Cancel and save](#cancel-save) - [Cancel and save](guide/router#cancel-save)
- [`Resolve`: pre-fetching component data](#resolve-guard) - [`Resolve`: pre-fetching component data](guide/router#resolve-guard)
- [Fetch data before navigating](#fetch-before-navigating ) - [Fetch data before navigating](guide/router#fetch-before-navigating )
- [Query parameters and fragments](#query-parameters) - [Query parameters and fragments](guide/router#query-parameters)
* [Milestone 6: Asynchronous routing](#asynchronous-routing) * [Milestone 6: Asynchronous routing](guide/router#asynchronous-routing)
- [Lazy loading route configuration](#lazy-loading-route-config) - [Lazy loading route configuration](guide/router#lazy-loading-route-config)
- [CanLoad Guard: guarding unauthorized loading of feature modules](#can-load-guard) - [CanLoad Guard: guarding unauthorized loading of feature modules](guide/router#can-load-guard)
- [Preloading: background loading of feature areas](#preloading) - [Preloading: background loading of feature areas](guide/router#preloading)
- [How preloading works](#how-preloading) - [How preloading works](guide/router#how-preloading)
- [Lazy load the crisis center](#lazy-load-crisis-center) - [Lazy load the crisis center](guide/router#lazy-load-crisis-center)
- [_CanLoad_ blocks preload](#preload-canload) - [_CanLoad_ blocks preload](guide/router#preload-canload)
- [Custom Preloading Strategy](#custom-preloading) - [Custom Preloading Strategy](guide/router#custom-preloading)
- [Inspect the router's configuration](#inspect-config) - [Inspect the router's configuration](guide/router#inspect-config)
- [Wrap up and final app](#final-app) - [Wrap up and final app](guide/router#final-app)
* [Appendices](#appendices) * [Appendices](guide/router#appendices)
- [Appendix: link parameters array](#link-parameters-array) - [Appendix: link parameters array](guide/router#link-parameters-array)
- [Appendix: *LocationStrategy* and browser URL styles](#location-strategy) - [Appendix: *LocationStrategy* and browser URL styles](guide/router#location-strategy)
@ -140,7 +140,7 @@ The Angular Router is an optional service that presents a particular component v
It is not part of the Angular core. It is in its own library package, `@angular/router`. It is not part of the Angular core. It is in its own library package, `@angular/router`.
Import what you need from it as you would from any other Angular package. Import what you need from it as you would from any other Angular package.
You'll learn about more options in the [details below](#browser-url-styles). You'll learn about more options in the [details below](guide/router#browser-url-styles).
{@a basics-config} {@a basics-config}
@ -172,7 +172,7 @@ You'll learn more about route parameters later in this guide.
The `data` property in the third route is a place to store arbitrary data associated with The `data` property in the third route is a place to store arbitrary data associated with
this specific route. The data property is accessible within each activated route. Use it to store this specific route. The data property is accessible within each activated route. Use it to store
items such as page titles, breadcrumb text, and other read-only, _static_ data. items such as page titles, breadcrumb text, and other read-only, _static_ data.
You'll use the [resolve guard](#resolve-guard) to retrieve _dynamic_ data later in the guide. You'll use the [resolve guard](guide/router#resolve-guard) to retrieve _dynamic_ data later in the guide.
The `empty path` in the fourth route represents the default path for the application, The `empty path` in the fourth route represents the default path for the application,
the place to go when the path in the URL is empty, as it typically is at the start. the place to go when the path in the URL is empty, as it typically is at the start.
@ -562,7 +562,7 @@ Modern HTML5 browsers were the first to support `pushState` which is why many pe
"HTML5 style" URLs. "HTML5 style" URLs.
HTML5 style navigation is the router default. HTML5 style navigation is the router default.
In the [LocationStrategy and browser URL styles](#browser-url-styles) Appendix, In the [LocationStrategy and browser URL styles](guide/router#browser-url-styles) Appendix,
learn why HTML5 style is preferred, how to adjust its behavior, and how to switch to the learn why HTML5 style is preferred, how to adjust its behavior, and how to switch to the
older hash (#) style, if necessary. older hash (#) style, if necessary.
You must **add a You must **add a
@ -617,7 +617,7 @@ A router must be configured with a list of route definitions.
The first configuration defines an array of two routes with simple paths leading to the The first configuration defines an array of two routes with simple paths leading to the
`CrisisListComponent` and `HeroListComponent`. `CrisisListComponent` and `HeroListComponent`.
Each definition translates to a [Route](../api/router/index/Route-interface.html) object which has two things: a Each definition translates to a [Route](api/router/index/Route-interface) object which has two things: a
`path`, the URL path segment for this route; and a `path`, the URL path segment for this route; and a
`component`, the component associated with this route. `component`, the component associated with this route.
@ -638,7 +638,7 @@ Once the application is bootstrapped, the `Router` performs the initial navigati
Adding the configured `RouterModule` to the `AppModule` is sufficient for simple route configurations. Adding the configured `RouterModule` to the `AppModule` is sufficient for simple route configurations.
As the application grows, you'll want to refactor the routing configuration into a separate file As the application grows, you'll want to refactor the routing configuration into a separate file
and create a **[Routing Module](#routing-module)**, a special type of `Service Module` dedicated to the purpose and create a **[Routing Module](guide/router#routing-module)**, a special type of `Service Module` dedicated to the purpose
of routing in feature modules. of routing in feature modules.
Providing the `RouterModule` in the `AppModule` makes the Router available everywhere in the application. Providing the `RouterModule` in the `AppModule` makes the Router available everywhere in the application.
@ -674,7 +674,7 @@ immediately _after_ the `<router-outlet>`.
### *RouterLink* binding ### *RouterLink* binding
Above the outlet, within the anchor tags, you see Above the outlet, within the anchor tags, you see
[attribute bindings](template-syntax.html#attribute-binding) to [attribute bindings](guide/template-syntax) to
the `RouterLink` directive that look like `routerLink="..."`. the `RouterLink` directive that look like `routerLink="..."`.
The links in this example each have a string path, the path of a route that The links in this example each have a string path, the path of a route that
@ -684,13 +684,13 @@ You can also add more contextual information to the `RouterLink` by providing qu
or a URL fragment for jumping to different areas on the page. Query string parameters or a URL fragment for jumping to different areas on the page. Query string parameters
are provided through the `[queryParams]` binding which takes an object (e.g. `{ name: 'value' }`), while the URL fragment are provided through the `[queryParams]` binding which takes an object (e.g. `{ name: 'value' }`), while the URL fragment
takes a single value bound to the `[fragment]` input binding. takes a single value bound to the `[fragment]` input binding.
Learn about the how you can also use the _link parameters array_ in the [appendix below](#link-parameters-array). Learn about the how you can also use the _link parameters array_ in the [appendix below](guide/router#link-parameters-array).
{@a router-link-active} {@a router-link-active}
### *RouterLinkActive* binding ### *RouterLinkActive* binding
On each anchor tag, you also see [property bindings](template-syntax.html#property-binding) to On each anchor tag, you also see [property bindings](guide/template-syntax) to
the `RouterLinkActive` directive that look like `routerLinkActive="..."`. the `RouterLinkActive` directive that look like `routerLinkActive="..."`.
The template expression to the right of the equals (=) contains a space-delimited string of CSS classes The template expression to the right of the equals (=) contains a space-delimited string of CSS classes
@ -722,9 +722,9 @@ Any other URL causes the router to throw an error and crash the app.
Add a **wildcard** route to intercept invalid URLs and handle them gracefully. Add a **wildcard** route to intercept invalid URLs and handle them gracefully.
A _wildcard_ route has a path consisting of two asterisks. It matches _every_ URL. A _wildcard_ route has a path consisting of two asterisks. It matches _every_ URL.
The router will select _this_ route if it can't match a route earlier in the configuration. The router will select _this_ route if it can't match a route earlier in the configuration.
A wildcard route can navigate to a custom "404 Not Found" component or [redirect](#redirect) to an existing route. A wildcard route can navigate to a custom "404 Not Found" component or [redirect](guide/router#redirect) to an existing route.
The router selects the route with a [_first match wins_](#example-config) strategy. The router selects the route with a [_first match wins_](guide/router#example-config) strategy.
Wildcard routes are the least specific routes in the route configuration. Wildcard routes are the least specific routes in the route configuration.
Be sure it is the _last_ route in the configuration. Be sure it is the _last_ route in the configuration.
To test this feature, add a button with a `RouterLink` to the `HeroListComponent` template and set the link to `"/sidekicks"`. The application will fail if the user clicks that button because you haven't defined a `"/sidekicks"` route yet. To test this feature, add a button with a `RouterLink` to the `HeroListComponent` template and set the link to `"/sidekicks"`. The application will fail if the user clicks that button because you haven't defined a `"/sidekicks"` route yet.
@ -936,7 +936,7 @@ The **Routing Module** has several characteristics:
* Separates routing concerns from other application concerns. * Separates routing concerns from other application concerns.
* Provides a module to replace or remove when testing the application. * Provides a module to replace or remove when testing the application.
* Provides a well-known location for routing service providers including guards and resolvers. * Provides a well-known location for routing service providers including guards and resolvers.
* Does **not** [declare components](../cookbook/ngmodule-faq.html#routing-module). * Does **not** [declare components](cookbook/ngmodule-faq).
{@a routing-refactor} {@a routing-refactor}
@ -966,8 +966,8 @@ then replacing `RouterModule.forRoot` in the `imports` array with the `AppRoutin
{@example 'router/ts/src/app/app.module.2.ts'} {@example 'router/ts/src/app/app.module.2.ts'}
Later in this guide you will create [multiple routing modules](#hero-routing-module) and discover that Later in this guide you will create [multiple routing modules](guide/router#hero-routing-module) and discover that
you must import those routing modules [in the correct order](#routing-module-order). you must import those routing modules [in the correct order](guide/router#routing-module-order).
The application continues to work just the same, and you can use `AppRoutingModule` as The application continues to work just the same, and you can use `AppRoutingModule` as
the central place to maintain future routing configuration. the central place to maintain future routing configuration.
@ -1003,7 +1003,7 @@ Now you'll learn the following:
* Pass required and optional information in route parameters. * Pass required and optional information in route parameters.
This example recreates the heroes feature in the "Services" episode of the This example recreates the heroes feature in the "Services" episode of the
[Tour of Heroes tutorial](../tutorial/toh-pt4.html "Tour of Heroes: Services"), [Tour of Heroes tutorial](tutorial/toh-pt4),
and you'll be copying much of the code and you'll be copying much of the code
from the <live-example name="toh-4" title="Tour of Heroes: Services example code"></live-example>. from the <live-example name="toh-4" title="Tour of Heroes: Services example code"></live-example>.
@ -1189,7 +1189,7 @@ The order of route configuration matters.
The router accepts the first route that matches a navigation request path. The router accepts the first route that matches a navigation request path.
When all routes were in one `AppRoutingModule`, When all routes were in one `AppRoutingModule`,
you put the default and [wildcard](#wildcard) routes last, after the `/heroes` route, you put the default and [wildcard](guide/router#wildcard) routes last, after the `/heroes` route,
so that the router had a chance to match a URL to the `/heroes` route _before_ so that the router had a chance to match a URL to the `/heroes` route _before_
hitting the wildcard route and navigating to "Page not found". hitting the wildcard route and navigating to "Page not found".
@ -1205,7 +1205,7 @@ will intercept the attempt to navigate to a hero route.
Reverse the routing modules and see for yourself that Reverse the routing modules and see for yourself that
a click of the heroes link results in "Page not found". a click of the heroes link results in "Page not found".
Learn about inspecting the runtime router configuration Learn about inspecting the runtime router configuration
[below](#inspect-config "Inspect the router config"). [below](guide/router#inspect-config "Inspect the router config").
{@a route-def-with-parameter} {@a route-def-with-parameter}
@ -1258,8 +1258,8 @@ to navigate to the hero detail view for the selected hero.
Start in the `HeroListComponent`. Start in the `HeroListComponent`.
Revise its constructor so that it acquires the `Router` and the `HeroService` by dependency injection: Revise its constructor so that it acquires the `Router` and the `HeroService` by dependency injection:
Make the following few changes to the component's template: Make the following few changes to the component's template:
The template defines an `*ngFor` repeater such as [you've seen before](displaying-data.html#ngFor). The template defines an `*ngFor` repeater such as [you've seen before](guide/displaying-data).
There's a `(click)` [event binding](template-syntax.html#event-binding) to the component's There's a `(click)` [event binding](guide/template-syntax) to the component's
`onSelect` method which you implement as follows: `onSelect` method which you implement as follows:
The component's `onSelect` calls the router's **`navigate`** method with a _link parameters array_. The component's `onSelect` calls the router's **`navigate`** method with a _link parameters array_.
You can use this same syntax in a `RouterLink` if you decide later to navigate in HTML template rather than in component code. You can use this same syntax in a `RouterLink` if you decide later to navigate in HTML template rather than in component code.
@ -1288,28 +1288,28 @@ the `HeroDetailComponent` via the `ActivatedRoute` service.
### ActivatedRoute: the one-stop-shop for route information ### ActivatedRoute: the one-stop-shop for route information
The route path and parameters are available through an injected router service called the The route path and parameters are available through an injected router service called the
[ActivatedRoute](../api/router/index/ActivatedRoute-interface.html). [ActivatedRoute](api/router/index/ActivatedRoute-interface).
It has a great deal of useful information including: It has a great deal of useful information including:
**`url`**: An `Observable` of the route path(s), represented as an array of strings for each part of the route path. **`url`**: An `Observable` of the route path(s), represented as an array of strings for each part of the route path.
**`data`**: An `Observable` that contains the `data` object provided for the route. Also contains any resolved values from the [resolve guard](#resolve-guard). **`data`**: An `Observable` that contains the `data` object provided for the route. Also contains any resolved values from the [resolve guard](guide/router#resolve-guard).
**`params`**: An `Observable` that contains the required and [optional parameters](#optional-route-parameters) specific to the route. **`params`**: An `Observable` that contains the required and [optional parameters](guide/router#optional-route-parameters) specific to the route.
**`queryParams`**: An `Observable` that contains the [query parameters](#query-parameters) available to all routes. **`queryParams`**: An `Observable` that contains the [query parameters](guide/router#query-parameters) available to all routes.
**`fragment`**: An `Observable` of the URL [fragment](#fragment) available to all routes. **`fragment`**: An `Observable` of the URL [fragment](guide/router#fragment) available to all routes.
**`outlet`**: The name of the `RouterOutlet` used to render the route. For an unnamed outlet, the outlet name is _primary_. **`outlet`**: The name of the `RouterOutlet` used to render the route. For an unnamed outlet, the outlet name is _primary_.
**`routeConfig`**: The route configuration used for the route that contains the origin path. **`routeConfig`**: The route configuration used for the route that contains the origin path.
**`parent`**: an `ActivatedRoute` that contains the information from the parent route when using [child routes](#child-routing-component). **`parent`**: an `ActivatedRoute` that contains the information from the parent route when using [child routes](guide/router#child-routing-component).
**`firstChild`**: contains the first `ActivatedRoute` in the list of child routes. **`firstChild`**: contains the first `ActivatedRoute` in the list of child routes.
**`children`**: contains all the [child routes](#child-routing-component) activated under the current route. **`children`**: contains all the [child routes](guide/router#child-routing-component) activated under the current route.
Import the `Router`, `ActivatedRoute`, and `Params` tokens from the router package. Import the `Router`, `ActivatedRoute`, and `Params` tokens from the router package.
Import the `switchMap` operator because you need it later to process the `Observable` route parameters. Import the `switchMap` operator because you need it later to process the `Observable` route parameters.
@ -1324,7 +1324,7 @@ Put this data access logic in the `ngOnInit` method rather than inside the const
Angular calls the `ngOnInit` method shortly after creating an instance of the `HeroDetailComponent` Angular calls the `ngOnInit` method shortly after creating an instance of the `HeroDetailComponent`
so the hero will be retrieved in time to use it. so the hero will be retrieved in time to use it.
Learn more about the `ngOnInit` method and other component lifecycle hooks in the [Lifecycle Hooks](lifecycle-hooks.html) guide. Learn more about the `ngOnInit` method and other component lifecycle hooks in the [Lifecycle Hooks](guide/lifecycle-hooks) guide.
Since the parameters are provided as an `Observable`, you use the `switchMap` operator to Since the parameters are provided as an `Observable`, you use the `switchMap` operator to
provide them for the `id` parameter by name and tell the `HeroService` to fetch the hero with that `id`. provide them for the `id` parameter by name and tell the `HeroService` to fetch the hero with that `id`.
@ -1403,7 +1403,7 @@ It holds the _path to the `HeroListComponent`_:
### Route Parameters: Required or optional? ### Route Parameters: Required or optional?
Use [*route parameters*](#route-parameters) to specify a *required* parameter value *within* the route URL Use [*route parameters*](guide/router#route-parameters) to specify a *required* parameter value *within* the route URL
as you do when navigating to the `HeroDetailComponent` in order to view the hero with *id* 15: as you do when navigating to the `HeroDetailComponent` in order to view the hero with *id* 15:
<code-example format="nocode"> <code-example format="nocode">
@ -1445,7 +1445,7 @@ prefer an *optional parameter* when the value is optional, complex, and/or multi
### Heroes list: optionally selecting a hero ### Heroes list: optionally selecting a hero
When navigating to the `HeroDetailComponent` you specified the _required_ `id` of the hero-to-edit in the When navigating to the `HeroDetailComponent` you specified the _required_ `id` of the hero-to-edit in the
*route parameter* and made it the second item of the [_link parameters array_](#link-parameters-array). *route parameter* and made it the second item of the [_link parameters array_](guide/router#link-parameters-array).
The router embedded the `id` value in the navigation URL because you had defined it The router embedded the `id` value in the navigation URL because you had defined it
as a route parameter with an `:id` placeholder token in the route `path`: as a route parameter with an `:id` placeholder token in the route `path`:
When the user clicks the back button, the `HeroDetailComponent` constructs another _link parameters array_ When the user clicks the back button, the `HeroDetailComponent` constructs another _link parameters array_
@ -1514,7 +1514,7 @@ and get the heroes.
All route/query parameters are strings. All route/query parameters are strings.
The (+) in front of the `params['id']` expression is a JavaScript trick to convert the string to an integer.Add an `isSelected` method that returns `true` when a hero's `id` matches the selected `id`. The (+) in front of the `params['id']` expression is a JavaScript trick to convert the string to an integer.Add an `isSelected` method that returns `true` when a hero's `id` matches the selected `id`.
Finally, update the template with a [class binding](template-syntax.html#class-binding) to that `isSelected` method. Finally, update the template with a [class binding](guide/template-syntax) to that `isSelected` method.
The binding adds the `selected` CSS class when the method returns `true` and removes it when `false`. The binding adds the `selected` CSS class when the method returns `true` and removes it when `false`.
Look for it within the repeated `<li>` tag as shown here: Look for it within the repeated `<li>` tag as shown here:
When the user navigates from the heroes list to the "Magneta" hero and back, "Magneta" appears selected: When the user navigates from the heroes list to the "Magneta" hero and back, "Magneta" appears selected:
@ -1529,7 +1529,7 @@ The optional `foo` route parameter is harmless and continues to be ignored.
### Adding animations to the routed component ### Adding animations to the routed component
The heroes feature module is almost complete, but what is a feature without some smooth transitions? The heroes feature module is almost complete, but what is a feature without some smooth transitions?
This section shows you how to add some [animations](../guide/animations.html) This section shows you how to add some [animations](guide/animations)
to the `HeroDetailComponent`. to the `HeroDetailComponent`.
Create an `animations.ts` file in the root `src/app/` folder. The contents look like this:This file does the following: Create an `animations.ts` file in the root `src/app/` folder. The contents look like this:This file does the following:
@ -1815,7 +1815,7 @@ of the `CrisisCenterComponent`, not in the `RouterOutlet` of the `AppComponent`
The `CrisisListComponent` contains the crisis list and a `RouterOutlet` to The `CrisisListComponent` contains the crisis list and a `RouterOutlet` to
display the `Crisis Center Home` and `Crisis Detail` route components. display the `Crisis Center Home` and `Crisis Detail` route components.
The `Crisis Detail` route is a child of the `Crisis List`. Since the router [reuses components](#reuse) The `Crisis Detail` route is a child of the `Crisis List`. Since the router [reuses components](guide/router#reuse)
by default, the `Crisis Detail` component will be re-used as you select different crises. by default, the `Crisis Detail` component will be re-used as you select different crises.
In contrast, back in the `Hero Detail` route, the component was recreated each time you selected a different hero. In contrast, back in the `Hero Detail` route, the component was recreated each time you selected a different hero.
@ -1968,7 +1968,7 @@ There are two noteworthy differences.
Note that the `send()` method simulates latency by waiting a second before "sending" the message and closing the popup. Note that the `send()` method simulates latency by waiting a second before "sending" the message and closing the popup.
The `closePopup()` method closes the popup view by navigating to the popup outlet with a `null`. The `closePopup()` method closes the popup view by navigating to the popup outlet with a `null`.
That's a peculiarity covered [below](#clear-secondary-routes). That's a peculiarity covered [below](guide/router#clear-secondary-routes).
As with other application components, you add the `ComposeMessageComponent` to the `declarations` of an `NgModule`. As with other application components, you add the `ComposeMessageComponent` to the `declarations` of an `NgModule`.
Do so in the `AppModule`. Do so in the `AppModule`.
@ -2049,7 +2049,7 @@ Changing a current route that displays in the primary outlet has no effect on th
That's why the popup stays visible as you navigate among the crises and heroes. That's why the popup stays visible as you navigate among the crises and heroes.
Clicking the "send" or "cancel" buttons _does_ clear the popup view. Clicking the "send" or "cancel" buttons _does_ clear the popup view.
To see how, look at the `closePopup()` method again:It navigates imperatively with the `Router.navigate()` method, passing in a [link parameters array](#link-parameters-array). To see how, look at the `closePopup()` method again:It navigates imperatively with the `Router.navigate()` method, passing in a [link parameters array](guide/router#link-parameters-array).
Like the array bound to the _Contact_ `RouterLink` in the `AppComponent`, Like the array bound to the _Contact_ `RouterLink` in the `AppComponent`,
this one includes an object with an `outlets` property. this one includes an object with an `outlets` property.
@ -2089,15 +2089,15 @@ router will wait for the observable to resolve to `true` or `false`.
The router supports multiple kinds of guards: The router supports multiple kinds of guards:
1. [`CanActivate`](../api/router/index/CanActivate-interface.html) to mediate navigation *to* a route. 1. [`CanActivate`](api/router/index/CanActivate-interface) to mediate navigation *to* a route.
2. [`CanActivateChild()`](../api/router/index/CanActivateChild-interface.html) to mediate navigation *to* a child route. 2. [`CanActivateChild()`](api/router/index/CanActivateChild-interface) to mediate navigation *to* a child route.
3. [`CanDeactivate`](../api/router/index/CanDeactivate-interface.html) to mediate navigation *away* from the current route. 3. [`CanDeactivate`](api/router/index/CanDeactivate-interface) to mediate navigation *away* from the current route.
4. [`Resolve`](../api/router/index/Resolve-interface.html) to perform route data retrieval *before* route activation. 4. [`Resolve`](api/router/index/Resolve-interface) to perform route data retrieval *before* route activation.
5. [`CanLoad`](../api/router/index/CanLoad-interface.html) to mediate navigation *to* a feature module loaded _asynchronously_. 5. [`CanLoad`](api/router/index/CanLoad-interface) to mediate navigation *to* a feature module loaded _asynchronously_.
You can have multiple guards at every level of a routing hierarchy. You can have multiple guards at every level of a routing hierarchy.
The router checks the `CanDeactivate()` and `CanActivateChild()` guards first, from the deepest child route to the top. The router checks the `CanDeactivate()` and `CanActivateChild()` guards first, from the deepest child route to the top.
Then it checks the `CanActivate()` guards from the top down to the deepest child route. If the feature module Then it checks the `CanActivate()` guards from the top down to the deepest child route. If the feature module
@ -2217,7 +2217,7 @@ You've defined a _component-less_ route.
The goal is to group the `Crisis Center` management routes under the `admin` path. The goal is to group the `Crisis Center` management routes under the `admin` path.
You don't need a component to do it. You don't need a component to do it.
A _component-less_ route makes it easier to [guard child routes](#can-activate-child-guard). A _component-less_ route makes it easier to [guard child routes](guide/router#can-activate-child-guard).
Next, import the `AdminModule` into `app.module.ts` and add it to the `imports` array Next, import the `AdminModule` into `app.module.ts` and add it to the `imports` array
to register the admin routes. to register the admin routes.
Add an "Admin" link to the `AppComponent` shell so that users can get to this feature. Add an "Admin" link to the `AppComponent` shell so that users can get to this feature.
@ -2307,7 +2307,7 @@ Import and add the `LoginRoutingModule` to the `AppModule` imports as well.
Guards and the service providers they require _must_ be provided at the module-level. This allows Guards and the service providers they require _must_ be provided at the module-level. This allows
the Router access to retrieve these services from the `Injector` during the navigation process. the Router access to retrieve these services from the `Injector` during the navigation process.
The same rule applies for feature modules loaded [asynchronously](#asynchronous-routing). The same rule applies for feature modules loaded [asynchronously](guide/router#asynchronous-routing).
{@a can-activate-child-guard} {@a can-activate-child-guard}
@ -2557,7 +2557,7 @@ The relevant *Crisis Center* code for this milestone follows.
{@a fragment} {@a fragment}
### Query parameters and fragments ### Query parameters and fragments
In the [route parameters](#optional-route-parameters) example, you only dealt with parameters specific to In the [route parameters](guide/router#optional-route-parameters) example, you only dealt with parameters specific to
the route, but what if you wanted optional parameters available to all routes? the route, but what if you wanted optional parameters available to all routes?
This is where query parameters come into play. This is where query parameters come into play.
@ -2716,7 +2716,7 @@ The `Router` offers two preloading strategies out of the box:
* Preloading of all lazy loaded feature areas. * Preloading of all lazy loaded feature areas.
Out of the box, the router either never preloads, or preloads every lazy load module. Out of the box, the router either never preloads, or preloads every lazy load module.
The `Router` also supports [custom preloading strategies](#custom-preloading) for The `Router` also supports [custom preloading strategies](guide/router#custom-preloading) for
fine control over which modules to preload and when. fine control over which modules to preload and when.
In this next section, you'll update the `CrisisCenterModule` to load lazily In this next section, you'll update the `CrisisCenterModule` to load lazily
@ -2776,7 +2776,7 @@ Surprisingly, the `AdminModule` does _not_ preload. Something is blocking it.
{@a preload-canload} {@a preload-canload}
#### CanLoad blocks preload #### CanLoad blocks preload
The `PreloadAllModules` strategy does not load feature areas protected by a [CanLoad](#can-load-guard) guard. The `PreloadAllModules` strategy does not load feature areas protected by a [CanLoad](guide/router#can-load-guard) guard.
This is by design. This is by design.
You added a `CanLoad` guard to the route in the `AdminModule` a few steps back You added a `CanLoad` guard to the route in the `AdminModule` a few steps back
@ -2784,7 +2784,7 @@ to block loading of that module until the user is authorized.
That `CanLoad` guard takes precedence over the preload strategy. That `CanLoad` guard takes precedence over the preload strategy.
If you want to preload a module _and_ guard against unauthorized access, If you want to preload a module _and_ guard against unauthorized access,
drop the `canLoad` guard and rely on the [CanActivate](#can-activate-guard) guard alone. drop the `canLoad` guard and rely on the [CanActivate](guide/router#can-activate-guard) guard alone.
{@a custom-preloading} {@a custom-preloading}
@ -2840,7 +2840,7 @@ It's also logged to the browser's console.
## Inspect the router's configuration ## Inspect the router's configuration
You put a lot of effort into configuring the router in several routing module files You put a lot of effort into configuring the router in several routing module files
and were careful to list them [in the proper order](#routing-module-order). and were careful to list them [in the proper order](guide/router#routing-module-order).
Are routes actually evaluated as you planned? Are routes actually evaluated as you planned?
How is the router really configured? How is the router really configured?
@ -2951,7 +2951,7 @@ making it the default strategy.
You can switch to the `HashLocationStrategy` with an override during the bootstrapping process if you prefer it. You can switch to the `HashLocationStrategy` with an override during the bootstrapping process if you prefer it.
Learn about providers and the bootstrap process in the Learn about providers and the bootstrap process in the
[Dependency Injection guide](dependency-injection.html#bootstrap). [Dependency Injection guide](guide/dependency-injection).
### Which strategy is best? ### Which strategy is best?
You must choose a strategy and you need to make the right call early in the project. You must choose a strategy and you need to make the right call early in the project.

10
aio/content/guide/security.md
View File

@ -18,7 +18,7 @@ You can run the <live-example></live-example> in Plunker and download the code f
Reporting vulnerabilities Reporting vulnerabilities
</h2> </h2>
To report vulnerabilities in Angular itself, email us at [security@angular.io](mailto:security@angular.io). To report vulnerabilities in Angular itself, email us at [security@angular.io](guide/mailto:security@angular).
For more information about how Google handles security issues, see [Google's security For more information about how Google handles security issues, see [Google's security
philosophy](https://www.google.com/about/appsecurity/). philosophy](https://www.google.com/about/appsecurity/).
@ -39,7 +39,7 @@ important security fixes and enhancements. Instead, share your Angular improveme
community and make a pull request. community and make a pull request.
* **Avoid Angular APIs marked in the documentation as “_Security Risk_.”** * **Avoid Angular APIs marked in the documentation as “_Security Risk_.”**
For more information, see the [Trusting safe values](#bypass-security-apis) section of this page. For more information, see the [Trusting safe values](guide/security#bypass-security-apis) section of this page.
<h2 id='xss'> <h2 id='xss'>
@ -68,7 +68,7 @@ _Angular templates are the same as executable code_: HTML, attributes, and bindi
prevent values that an attacker can control from ever making it into the source code of a prevent values that an attacker can control from ever making it into the source code of a
template. Never generate template source code by concatenating user input and templates. template. Never generate template source code by concatenating user input and templates.
To prevent these vulnerabilities, use To prevent these vulnerabilities, use
the [offline template compiler](#offline-template-compiler), also known as _template injection_. the [offline template compiler](guide/security#offline-template-compiler), also known as _template injection_.
### Sanitization and security contexts ### Sanitization and security contexts
@ -124,7 +124,7 @@ and greatly improves application performance. Use the offline template compiler
deployments; don't dynamically generate templates. Angular trusts template code, so generating deployments; don't dynamically generate templates. Angular trusts template code, so generating
templates, in particular templates containing user data, circumvents Angular's built-in protections. templates, in particular templates containing user data, circumvents Angular's built-in protections.
For information about dynamically constructing forms in a safe way, see the For information about dynamically constructing forms in a safe way, see the
[Dynamic Forms](../cookbook/dynamic-form.html) cookbook page. [Dynamic Forms](cookbook/dynamic-form) cookbook page.
### Server-side XSS protection ### Server-side XSS protection
@ -142,5 +142,5 @@ carries a high risk of introducing template-injection vulnerabilities.
Angular applications must follow the same security principles as regular web applications, and Angular applications must follow the same security principles as regular web applications, and
must be audited as such. Angular-specific APIs that should be audited in a security review, must be audited as such. Angular-specific APIs that should be audited in a security review,
such as the [_bypassSecurityTrust_](#bypass-security-apis) methods, are marked in the documentation such as the [_bypassSecurityTrust_](guide/security#bypass-security-apis) methods, are marked in the documentation
as security sensitive. as security sensitive.

78
aio/content/guide/server-communication.md
View File

@ -14,43 +14,43 @@ it isn't covered in this page.Modern browsers support two HTTP-based APIs:
The !{_Angular_http_library} simplifies application programming with the **XHR** and **JSONP** APIs. The !{_Angular_http_library} simplifies application programming with the **XHR** and **JSONP** APIs.
# Contents # Contents
* [Demos](#demos) * [Demos](guide/server-communication#demos)
* [Providing HTTP Services](#http-providers) * [Providing HTTP Services](guide/server-communication#http-providers)
* [The Tour of Heroes *HTTP* client demo](#http-client) * [The Tour of Heroes *HTTP* client demo](guide/server-communication#http-client)
- [The `HeroListComponent` class](#HeroListComponent) - [The `HeroListComponent` class](guide/server-communication#HeroListComponent)
* [Fetch data with `http.get()`](#fetch-data) * [Fetch data with `http.get()`](guide/server-communication#fetch-data)
<li if-docs="ts"> [RxJS library](#rxjs-library) <li if-docs="ts"> [RxJS library](guide/server-communication#rxjs-library)
<ul> <ul>
<li> [Enable RxJS operators](#enable-rxjs-operators)</li> <li> [Enable RxJS operators](guide/server-communication#enable-rxjs-operators)</li>
</ul> </ul>
</li> </li>
* [Process the response object](#extract-data) * [Process the response object](guide/server-communication#extract-data)
- [Parse to `JSON`](#parse-to-json) - [Parse to `JSON`](guide/server-communication#parse-to-json)
- [Do not return the response object](#no-return-response-object) - [Do not return the response object](guide/server-communication#no-return-response-object)
- [Always handle errors](#error-handling) - [Always handle errors](guide/server-communication#error-handling)
- [`HeroListComponent` error handling](#hero-list-component) - [`HeroListComponent` error handling](guide/server-communication#hero-list-component)
* [Send data to the server](#update) * [Send data to the server](guide/server-communication#update)
- [Headers](#headers) - [Headers](guide/server-communication#headers)
- [JSON results](#json-results) - [JSON results](guide/server-communication#json-results)
<ul><li if-docs="ts"> [Fall back to promises](#promises)</ul> <ul><li if-docs="ts"> [Fall back to promises](guide/server-communication#promises)</ul>
* [Cross-Origin Requests: Wikipedia example](#cors) * [Cross-Origin Requests: Wikipedia example](guide/server-communication#cors)
<ul if-docs="ts"> <ul if-docs="ts">
<li> [Search Wikipedia](#search-wikipedia)</li> <li> [Search Wikipedia](guide/server-communication#search-wikipedia)</li>
<li> [Search parameters](#search-parameters)</li> <li> [Search parameters](guide/server-communication#search-parameters)</li>
<li> [The WikiComponent](#wikicomponent)</li> <li> [The WikiComponent](guide/server-communication#wikicomponent)</li>
</ul> </ul>
* [A wasteful app](#wasteful-app) * [A wasteful app](guide/server-communication#wasteful-app)
<li if-docs="ts"> [More fun with Observables](#more-observables) <li if-docs="ts"> [More fun with Observables](guide/server-communication#more-observables)
<ul> <ul>
<li> [Create a stream of search terms](#create-stream)</li> <li> [Create a stream of search terms](guide/server-communication#create-stream)</li>
<li> [Listen for search terms](#listen-for-search-terms)</li> <li> [Listen for search terms](guide/server-communication#listen-for-search-terms)</li>
</ul> </ul>
</li> </li>
* [Guarding against Cross-Site Request Forgery](#xsrf) * [Guarding against Cross-Site Request Forgery](guide/server-communication#xsrf)
* [Override default request headers (and other request options)](#override-default-request-options) * [Override default request headers (and other request options)](guide/server-communication#override-default-request-options)
* [Appendix: Tour of Heroes _in-memory web api_](#in-mem-web-api) * [Appendix: Tour of Heroes _in-memory web api_](guide/server-communication#in-mem-web-api)
A <live-example>live example</live-example> illustrates these topics. A <live-example>live example</live-example> illustrates these topics.
@ -73,7 +73,7 @@ The !{_Angular_Http} client communicates with the server using a familiar HTTP r
The `!{_Http}` client is one of a family of services in the !{_Angular_http_library}. The `!{_Http}` client is one of a family of services in the !{_Angular_http_library}.
Before you can use the `!{_Http}` client, you need to register it as a service provider with the dependency injection system. Before you can use the `!{_Http}` client, you need to register it as a service provider with the dependency injection system.
Read about providers in the [Dependency Injection](dependency-injection.html) page. Read about providers in the [Dependency Injection](guide/dependency-injection) page.
Register providers by importing other NgModules to the root NgModule in `app.module.ts`. Register providers by importing other NgModules to the root NgModule in `app.module.ts`.
@ -86,7 +86,7 @@ there is a JSONP demo later in this page.
Loading its module now saves time. Loading its module now saves time.
## The Tour of Heroes HTTP client demo ## The Tour of Heroes HTTP client demo
The first demo is a mini-version of the [tutorial](../tutorial)'s "Tour of Heroes" (ToH) application. The first demo is a mini-version of the [tutorial](tutorial)'s "Tour of Heroes" (ToH) application.
This version gets some heroes from the server, displays them in a list, lets the user add new heroes, and saves them to the server. This version gets some heroes from the server, displays them in a list, lets the user add new heroes, and saves them to the server.
The app uses the !{_Angular_Http} client to communicate via `XMLHttpRequest (XHR)`. The app uses the !{_Angular_Http} client to communicate via `XMLHttpRequest (XHR)`.
@ -102,7 +102,7 @@ This demo has a single component, the `HeroListComponent`. Here's its template:
It presents the list of heroes with an `ngFor`. It presents the list of heroes with an `ngFor`.
Below the list is an input box and an *Add Hero* button where you can enter the names of new heroes Below the list is an input box and an *Add Hero* button where you can enter the names of new heroes
and add them to the database. and add them to the database.
A [template reference variable](template-syntax.html#ref-vars), `newHeroName`, accesses the A [template reference variable](guide/template-syntax), `newHeroName`, accesses the
value of the input box in the `(click)` event binding. value of the input box in the `(click)` event binding.
When the user clicks the button, that value passes to the component's `addHero` method and then When the user clicks the button, that value passes to the component's `addHero` method and then
the event binding clears it to make it ready for a new hero name. the event binding clears it to make it ready for a new hero name.
@ -119,7 +119,7 @@ Here's the component class:
{@example 'server-communication/ts/src/app/toh/hero-list.component.ts' region='component'} {@example 'server-communication/ts/src/app/toh/hero-list.component.ts' region='component'}
Angular [injects](dependency-injection.html) a `HeroService` into the constructor Angular [injects](guide/dependency-injection) a `HeroService` into the constructor
and the component calls that service to fetch and save data. and the component calls that service to fetch and save data.
The component **does not talk directly to the !{_Angular_Http} client**. The component **does not talk directly to the !{_Angular_Http} client**.
@ -130,7 +130,7 @@ This is a golden rule: **always delegate data access to a supporting service cla
Although _at runtime_ the component requests heroes immediately after creation, Although _at runtime_ the component requests heroes immediately after creation,
you **don't** call the service's `get` method in the component's constructor. you **don't** call the service's `get` method in the component's constructor.
Instead, call it inside the `ngOnInit` [lifecycle hook](lifecycle-hooks.html) Instead, call it inside the `ngOnInit` [lifecycle hook](guide/lifecycle-hooks)
and rely on Angular to call `ngOnInit` when it instantiates this component. and rely on Angular to call `ngOnInit` when it instantiates this component.
This is a *best practice*. This is a *best practice*.
Components are easier to test and debug when their constructors are simple, and all real work Components are easier to test and debug when their constructors are simple, and all real work
@ -151,7 +151,7 @@ You can revise that `HeroService` to get the heroes from the server using the !{
{@example 'server-communication/ts/src/app/toh/hero.service.ts' region='v1'} {@example 'server-communication/ts/src/app/toh/hero.service.ts' region='v1'}
Notice that the !{_Angular_Http} client service is Notice that the !{_Angular_Http} client service is
[injected](dependency-injection.html) into the `HeroService` constructor. [injected](guide/dependency-injection) into the `HeroService` constructor.
{@example 'server-communication/ts/src/app/toh/hero.service.ts' region='ctor'} {@example 'server-communication/ts/src/app/toh/hero.service.ts' region='ctor'}
@ -161,7 +161,7 @@ Look closely at how to call `!{_priv}http.get`:
You pass the resource URL to `get` and it calls the server which returns heroes. You pass the resource URL to `get` and it calls the server which returns heroes.
The server returns heroes once you've set up the [in-memory web api](#in-mem-web-api) The server returns heroes once you've set up the [in-memory web api](guide/server-communication#in-mem-web-api)
described in the appendix below. described in the appendix below.
Alternatively, you can temporarily target a JSON file by changing the endpoint URL: Alternatively, you can temporarily target a JSON file by changing the endpoint URL:
@ -254,7 +254,7 @@ just the name of a new hero and returns an `Observable` of `Hero`. It begins lik
To implement it, you must know the server's API for creating heroes. To implement it, you must know the server's API for creating heroes.
[This sample's data server](#in-mem-web-api) follows typical REST guidelines. [This sample's data server](guide/server-communication#in-mem-web-api) follows typical REST guidelines.
It expects a [`POST`](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5) request It expects a [`POST`](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5) request
at the same endpoint as `GET` heroes. at the same endpoint as `GET` heroes.
It expects the new hero data to arrive in the body of the request, It expects the new hero data to arrive in the body of the request,
@ -285,7 +285,7 @@ In the `headers` object, the `Content-Type` specifies that the body represents J
{@a json-results} {@a json-results}
### JSON results ### JSON results
As with `getHeroes()`, use the `!{_priv}extractData()` helper to [extract the data](#extract-data) As with `getHeroes()`, use the `!{_priv}extractData()` helper to [extract the data](guide/server-communication#extract-data)
from the response. from the response.
@ -305,7 +305,7 @@ This is called the [same-origin policy](https://en.wikipedia.org/wiki/Same-origi
Modern browsers do allow `XHR` requests to servers from a different origin if the server supports the Modern browsers do allow `XHR` requests to servers from a different origin if the server supports the
[CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) protocol. [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) protocol.
If the server requires user credentials, enable them in the [request headers](#headers). If the server requires user credentials, enable them in the [request headers](guide/server-communication#headers).
Some servers do not support CORS but do support an older, read-only alternative called [JSONP](https://en.wikipedia.org/wiki/JSONP). Some servers do not support CORS but do support an older, read-only alternative called [JSONP](https://en.wikipedia.org/wiki/JSONP).
Wikipedia is one such server. Wikipedia is one such server.
This [Stack Overflow answer](http://stackoverflow.com/questions/2067472/what-is-jsonp-all-about/2067584#2067584) covers many details of JSONP. This [Stack Overflow answer](http://stackoverflow.com/questions/2067472/what-is-jsonp-all-about/2067584#2067584) covers many details of JSONP.
@ -337,7 +337,7 @@ generated authentication token in a cookie named `XSRF-TOKEN`.
The HTTP client adds an `X-XSRF-TOKEN` header with that token value to subsequent requests. The HTTP client adds an `X-XSRF-TOKEN` header with that token value to subsequent requests.
The server receives both the cookie and the header, compares them, and processes the request only if the cookie and header match. The server receives both the cookie and the header, compares them, and processes the request only if the cookie and header match.
See the [XSRF topic on the Security page](security.html#xsrf) for more information about XSRF and Angular's `XSRFStrategy` counter measures. See the [XSRF topic on the Security page](guide/security) for more information about XSRF and Angular's `XSRFStrategy` counter measures.
{@a override-default-request-options} {@a override-default-request-options}
@ -370,7 +370,7 @@ Remember to include this provider during setup when unit testing the app's HTTP
{@example 'server-communication/ts/src/app/toh/hero.service.ts' region='addhero'} {@example 'server-communication/ts/src/app/toh/hero.service.ts' region='addhero'}
You can confirm that `DefaultRequestOptions` is working by examing HTTP requests in the browser developer tools' network tab. You can confirm that `DefaultRequestOptions` is working by examing HTTP requests in the browser developer tools' network tab.
If you're short-circuiting the server call with something like the [_in-memory web api_](#in-mem-web-api), If you're short-circuiting the server call with something like the [_in-memory web api_](guide/server-communication#in-mem-web-api),
try commenting-out the `addHero` header option, try commenting-out the `addHero` header option,
set a breakpoint on the POST call, and step through the request processing set a breakpoint on the POST call, and step through the request processing
to verify the header is there. to verify the header is there.

4
aio/content/guide/set-document-title.md
View File

@ -51,7 +51,7 @@ inside a Web Worker to improve your app's responsiveness by using multiple threa
means that you could run your app inside Electron.js or Windows Universal to deliver it to the desktop. means that you could run your app inside Electron.js or Windows Universal to deliver it to the desktop.
## Use the *Title* service ## Use the *Title* service
Fortunately, Angular bridges the gap by providing a `Title` service as part of the *Browser platform*. Fortunately, Angular bridges the gap by providing a `Title` service as part of the *Browser platform*.
The [Title](../api/platform-browser/index/Title-class.html) service is a simple class that provides an API The [Title](api/platform-browser/index/Title-class) service is a simple class that provides an API
for getting and setting the current HTML document title: for getting and setting the current HTML document title:
* `getTitle() : string` &mdash; Gets the title of the current HTML document. * `getTitle() : string` &mdash; Gets the title of the current HTML document.
@ -100,4 +100,4 @@ That's exactly what we're doing.
The `Title` service is part of the Angular *browser platform*. The `Title` service is part of the Angular *browser platform*.
If we bootstrap our application into a different platform, If we bootstrap our application into a different platform,
we'll have to provide a different `Title` service that understands the concept of a "document title" for that specific platform. we'll have to provide a different `Title` service that understands the concept of a "document title" for that specific platform.
Ideally the application itself neither knows nor cares about the runtime environment.[Back to top](#top) Ideally the application itself neither knows nor cares about the runtime environment.[Back to top](guide/set-document-title#top)

20
aio/content/guide/setup.md
View File

@ -13,16 +13,16 @@ Install the Angular QuickStart seed for faster, more efficient development on yo
<span if-docs="ts"> <span if-docs="ts">
The <live-example name=quickstart>QuickStart live-coding</live-example> example is an Angular _playground_. The <live-example name=quickstart>QuickStart live-coding</live-example> example is an Angular _playground_.
It's not where you'd develop a real application. It's not where you'd develop a real application.
You [should develop locally](#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular. You [should develop locally](guide/setup#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular.
</span> </span>
Setting up a new project on your machine is quick and easy with the **QuickStart seed**, Setting up a new project on your machine is quick and easy with the **QuickStart seed**,
maintained [on github](!{_qsRepo} "Install the github QuickStart repo"). maintained [on github](guide/!{_qsRepo} "Install the github QuickStart repo").
Make sure you have [!{_prereq} installed](#install-prerequisites "What if you don't have !{_prereq}?"). Make sure you have [!{_prereq} installed](guide/setup#install-prerequisites "What if you don't have !{_prereq}?").
Then ... Then ...
1. Create a project folder (you can call it `quickstart` and rename it later). 1. Create a project folder (you can call it `quickstart` and rename it later).
1. [Clone](#clone "Clone it from github") or [download](#download "download it from github") the **QuickStart seed** into your project folder. 1. [Clone](guide/setup#clone "Clone it from github") or [download](guide/setup#download "download it from github") the **QuickStart seed** into your project folder.
1. !{_Install} [!{_npm}](#install-prerequisites "What if you don't have !{_prereq}?") packages. 1. !{_Install} [!{_npm}](guide/setup#install-prerequisites "What if you don't have !{_prereq}?") packages.
1. Run `!{_npm} !{_start}` to launch the sample application. 1. Run `!{_npm} !{_start}` to launch the sample application.
@ -180,7 +180,7 @@ The following are all in `src/`
<td> <td>
Defines `AppModule`, the [root module](appmodule.html "AppModule: the root module") that tells Angular how to assemble the application. Defines `AppModule`, the [root module](guide/appmodule) that tells Angular how to assemble the application.
Right now it declares only the `AppComponent`. Right now it declares only the `AppComponent`.
Soon there will be more components to declare. Soon there will be more components to declare.
</td> </td>
@ -197,12 +197,12 @@ The following are all in `src/`
<td> <td>
Compiles the application with the [JIT compiler](../glossary.html#jit) and Compiles the application with the [JIT compiler](glossary) and
[bootstraps](appmodule.html#main "bootstrap the application") [bootstraps](guide/appmodule)
the application's main module (`AppModule`) to run in the browser. the application's main module (`AppModule`) to run in the browser.
The JIT compiler is a reasonable choice during the development of most projects and The JIT compiler is a reasonable choice during the development of most projects and
it's the only viable choice for a sample running in a _live-coding_ environment like Plunker. it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
You'll learn about alternative compiling and [deployment](deployment.html) options later in the documentation. You'll learn about alternative compiling and [deployment](guide/deployment) options later in the documentation.
</td> </td>
@ -215,7 +215,7 @@ The following are all in `src/`
### Next Step ### Next Step
If you're new to Angular, we recommend staying on the [learning path](learning-angular.html "Angular learning path"). If you're new to Angular, we recommend staying on the [learning path](guide/learning-angular).
<br></br><br></br> <br></br><br></br>
{@a install-prerequisites} {@a install-prerequisites}

84
aio/content/guide/structural-directives.md
View File

@ -17,18 +17,18 @@ how you can write your own structural directives to do the same thing.
### Table of contents ### Table of contents
- [What are structural directives?](#definition) - [What are structural directives?](guide/structural-directives#definition)
- [*NgIf* case study](#ngIf) - [*NgIf* case study](guide/structural-directives#ngIf)
- [The asterisk (*) prefix](#asterisk) - [The asterisk (*) prefix](guide/structural-directives#asterisk)
- [Inside *NgFor*](#ngFor) - [Inside *NgFor*](guide/structural-directives#ngFor)
- [microsyntax](#microsyntax) - [microsyntax](guide/structural-directives#microsyntax)
- [template input variables](#template-input-variable) - [template input variables](guide/structural-directives#template-input-variable)
- [one structural directive per element](#one-per-element) - [one structural directive per element](guide/structural-directives#one-per-element)
- [Inside the *NgSwitch* directives](#ngSwitch) - [Inside the *NgSwitch* directives](guide/structural-directives#ngSwitch)
- [Prefer the (*) prefix](#prefer-asterisk) - [Prefer the (*) prefix](guide/structural-directives#prefer-asterisk)
- [The &lt;template> element](#template) - [The &lt;template> element](guide/structural-directives#template)
- [Group sibling elements with &lt;ng-container&gt;](#ng-container) - [Group sibling elements with &lt;ng-container&gt;](guide/structural-directives#ng-container)
- [Write a structural directive](#unless) - [Write a structural directive](guide/structural-directives#unless)
Try the <live-example></live-example>. Try the <live-example></live-example>.
@ -48,19 +48,19 @@ Structural directives are easy to recognize.
An asterisk (*) precedes the directive attribute name as in this example. An asterisk (*) precedes the directive attribute name as in this example.
No brackets. No parentheses. Just `*ngIf` set to a string. No brackets. No parentheses. Just `*ngIf` set to a string.
You'll learn in this guide that the [asterisk (*) is a convenience notation](#asterisk) You'll learn in this guide that the [asterisk (*) is a convenience notation](guide/structural-directives#asterisk)
and the string is a [_microsyntax_](#microsyntax) rather than the usual and the string is a [_microsyntax_](guide/structural-directives#microsyntax) rather than the usual
[template expression](template-syntax.html#template-expressions). [template expression](guide/template-syntax).
Angular desugars this notation into a marked-up `<template>` that surrounds the Angular desugars this notation into a marked-up `<template>` that surrounds the
host element and its descendents. host element and its descendents.
Each structural directive does something different with that template. Each structural directive does something different with that template.
Three of the common, built-in structural directives&mdash;[NgIf](template-syntax.html#ngIf), Three of the common, built-in structural directives&mdash;[NgIf](guide/template-syntax),
[NgFor](template-syntax.html#ngFor), and [NgSwitch...](template-syntax.html#ngSwitch)&mdash;are [NgFor](guide/template-syntax), and [NgSwitch...](guide/template-syntax)&mdash;are
described in the [_Template Syntax_](template-syntax.html) guide and seen in samples throughout the Angular documentation. described in the [_Template Syntax_](guide/template-syntax) guide and seen in samples throughout the Angular documentation.
Here's an example of them in a template: Here's an example of them in a template:
This guide won't repeat how to _use_ them. But it does explain _how they work_ This guide won't repeat how to _use_ them. But it does explain _how they work_
and how to [write your own](#unless) structural directive. and how to [write your own](guide/structural-directives#unless) structural directive.
~~~ {.callout.is-helpful} ~~~ {.callout.is-helpful}
@ -91,13 +91,13 @@ There are two other kinds of Angular directives, described extensively elsewhere
A *component* manages a region of HTML in the manner of a native HTML element. A *component* manages a region of HTML in the manner of a native HTML element.
Technically it's a directive with a template. Technically it's a directive with a template.
An [*attribute* directive](attribute-directives.html) changes the appearance or behavior An [*attribute* directive](guide/attribute-directives) changes the appearance or behavior
of an element, component, or another directive. of an element, component, or another directive.
For example, the built-in [`NgStyle`](template-syntax.html#ngStyle) directive For example, the built-in [`NgStyle`](guide/template-syntax) directive
changes several element styles at the same time. changes several element styles at the same time.
You can apply many _attribute_ directives to one host element. You can apply many _attribute_ directives to one host element.
You can [only apply one](#one-per-element) _structural_ directive to a host element. You can [only apply one](guide/structural-directives#one-per-element) _structural_ directive to a host element.
{@a ngIf} {@a ngIf}
@ -114,7 +114,7 @@ Confirm that fact using browser developer tools to inspect the DOM.
</figure> </figure>
The top paragraph is in the DOM. The bottom, disused paragraph is not; The top paragraph is in the DOM. The bottom, disused paragraph is not;
in its place is a comment about "template bindings" (more about that [later](#asterisk)). in its place is a comment about "template bindings" (more about that [later](guide/structural-directives#asterisk)).
When the condition is false, `NgIf` removes its host element from the DOM, When the condition is false, `NgIf` removes its host element from the DOM,
detaches it from DOM events (the attachments that it made), detaches it from DOM events (the attachments that it made),
@ -179,7 +179,7 @@ Only the finished product ends up in the DOM.
Angular consumed the `<template>` content during its actual rendering and Angular consumed the `<template>` content during its actual rendering and
replaced the `<template>` with a diagnostic comment. replaced the `<template>` with a diagnostic comment.
The [`NgFor`](#ngFor) and [`NgSwitch...`](#ngSwitch) directives follow the same pattern. The [`NgFor`](guide/structural-directives#ngFor) and [`NgSwitch...`](guide/structural-directives#ngSwitch) directives follow the same pattern.
{@a ngFor} {@a ngFor}
@ -194,7 +194,7 @@ This is manifestly more complicated than `ngIf` and rightly so.
The `NgFor` directive has more features, both required and optional, than the `NgIf` shown in this guide. The `NgFor` directive has more features, both required and optional, than the `NgIf` shown in this guide.
At minimum `NgFor` needs a looping variable (`let hero`) and a list (`heroes`). At minimum `NgFor` needs a looping variable (`let hero`) and a list (`heroes`).
You enable these features in the string assigned to `ngFor`, which you write in Angular's [microsyntax](#microsyntax). You enable these features in the string assigned to `ngFor`, which you write in Angular's [microsyntax](guide/structural-directives#microsyntax).
~~~ {.alert.is-helpful} ~~~ {.alert.is-helpful}
@ -214,7 +214,7 @@ In this example, the `[ngClass]="odd"` stays on the `<div>`.
The Angular microsyntax lets you configure a directive in a compact, friendly string. The Angular microsyntax lets you configure a directive in a compact, friendly string.
The microsyntax parser translates that string into attributes on the `<template>`: The microsyntax parser translates that string into attributes on the `<template>`:
* The `let` keyword declares a [_template input variable_](#template-input-variable) * The `let` keyword declares a [_template input variable_](guide/structural-directives#template-input-variable)
that you reference within the template. The input variables in this example are `hero`, `i`, and `odd`. that you reference within the template. The input variables in this example are `hero`, `i`, and `odd`.
The parser translates `let hero`, `let i`, and `let odd` into variables named, The parser translates `let hero`, `let i`, and `let odd` into variables named,
`let-hero`, `let-i`, and `let-odd`. `let-hero`, `let-i`, and `let-odd`.
@ -235,7 +235,7 @@ It's intended source is implicit.
Angular sets `let-hero` to the value of the context's `$implicit` property Angular sets `let-hero` to the value of the context's `$implicit` property
which `NgFor` has initialized with the hero for the current iteration. which `NgFor` has initialized with the hero for the current iteration.
* The [API guide](../api/common/index/NgFor-directive.html "API: NgFor") * The [API guide](api/common/index/NgFor-directive)
describes additional `NgFor` directive properties and context properties. describes additional `NgFor` directive properties and context properties.
These microsyntax mechanisms are available to you when you write your own structural directives. These microsyntax mechanisms are available to you when you write your own structural directives.
@ -254,7 +254,7 @@ There are several such variables in this example: `hero`, `i`, and `odd`.
All are preceded by the keyword `let`. All are preceded by the keyword `let`.
A _template input variable_ is **_not_** the same as a A _template input variable_ is **_not_** the same as a
[template _reference_ variable](template-syntax.html#ref-vars), [template _reference_ variable](guide/template-syntax),
neither _semantically_ nor _syntactically_. neither _semantically_ nor _syntactically_.
You declare a template _input_ variable using the `let` keyword (`let hero`). You declare a template _input_ variable using the `let` keyword (`let hero`).
@ -283,7 +283,7 @@ If so (and it seems like it should be so), how should Angular generalize the abi
There are no easy answers to these questions. Prohibiting multiple structural directives makes them moot. There are no easy answers to these questions. Prohibiting multiple structural directives makes them moot.
There's an easy solution for this use case: put the `*ngIf` on a container element that wraps the `*ngFor` element. There's an easy solution for this use case: put the `*ngIf` on a container element that wraps the `*ngFor` element.
One or both elements can be an [`ng-container`](#ngcontainer) so you don't have to introduce extra levels of HTML. One or both elements can be an [`ng-container`](guide/structural-directives#ngcontainer) so you don't have to introduce extra levels of HTML.
{@a ngSwitch} {@a ngSwitch}
@ -317,12 +317,12 @@ That, in turn, can be desugared into the `<template>` element form.
## Prefer the asterisk (*) syntax. ## Prefer the asterisk (*) syntax.
The asterisk (*) syntax is more clear than the other desugared forms. The asterisk (*) syntax is more clear than the other desugared forms.
Use [&lt;ng-container&gt;](#ng-container) when there's no single element Use [&lt;ng-container&gt;](guide/structural-directives#ng-container) when there's no single element
to host the directive. to host the directive.
While there's rarely a good reason to apply a structural directive in template _attribute_ or _element_ form, While there's rarely a good reason to apply a structural directive in template _attribute_ or _element_ form,
it's still important to know that Angular creates a `<template>` and to understand how it works. it's still important to know that Angular creates a `<template>` and to understand how it works.
You'll refer to the `<template>` when you [write your own structural directive](#unless). You'll refer to the `<template>` when you [write your own structural directive](guide/structural-directives#unless).
{@a template} {@a template}
@ -344,7 +344,7 @@ Angular erases the middle "Hip!", leaving the cheer a bit less enthusiastic.
</figure> </figure>
A structural directive puts a `<template>` to work A structural directive puts a `<template>` to work
as you'll see when you [write your own structural directive](#unless). as you'll see when you [write your own structural directive](guide/structural-directives#unless).
{@a ngcontainer} {@a ngcontainer}
@ -451,21 +451,21 @@ The directive _attribute name_ should be spelled in _lowerCamelCase_ and begin w
Don't use `ng`. That prefix belongs to Angular. Don't use `ng`. That prefix belongs to Angular.
Pick something short that fits you or your company. Pick something short that fits you or your company.
In this example, the prefix is `my`. In this example, the prefix is `my`.
The directive _class_ name ends in `Directive` per the [style guide](style-guide.html#02-03 "Angular Style Guide"). The directive _class_ name ends in `Directive` per the [style guide](guide/style-guide).
Angular's own directives do not. Angular's own directives do not.
### _TemplateRef_ and _ViewContainerRef_ ### _TemplateRef_ and _ViewContainerRef_
A simple structural directive like this one creates an A simple structural directive like this one creates an
[_embedded view_](../api/core/index/EmbeddedViewRef-class.html "API: EmbeddedViewRef") [_embedded view_](api/core/index/EmbeddedViewRef-class)
from the Angular-generated `<template>` and inserts that view in a from the Angular-generated `<template>` and inserts that view in a
[_view container_](../api/core/index/ViewContainerRef-class.html "API: ViewContainerRef") [_view container_](api/core/index/ViewContainerRef-class)
adjacent to the directive's original `<p>` host element. adjacent to the directive's original `<p>` host element.
You'll acquire the `<template>` contents with a You'll acquire the `<template>` contents with a
[`TemplateRef`](../api/core/index/TemplateRef-class.html "API: TemplateRef") [`TemplateRef`](api/core/index/TemplateRef-class)
and access the _view container_ through a and access the _view container_ through a
[`ViewContainerRef`](../api/core/index/ViewContainerRef-class.html "API: ViewContainerRef"). [`ViewContainerRef`](api/core/index/ViewContainerRef-class).
You inject both in the directive constructor as private variables of the class. You inject both in the directive constructor as private variables of the class.
### The _myUnless_ property ### The _myUnless_ property
@ -473,7 +473,7 @@ You inject both in the directive constructor as private variables of the class.
The directive consumer expects to bind a true/false condition to `[myUnless]`. The directive consumer expects to bind a true/false condition to `[myUnless]`.
That means the directive needs a `myUnless` property, decorated with `@Input` That means the directive needs a `myUnless` property, decorated with `@Input`
Read about `@Input` in the [_Template Syntax_](template-syntax.html#inputs-outputs) guide. Read about `@Input` in the [_Template Syntax_](guide/template-syntax) guide.
Angular sets the `myUnless` property whenever the value of the condition changes. Angular sets the `myUnless` property whenever the value of the condition changes.
Because the `myUnless` property does work, it needs a setter. Because the `myUnless` property does work, it needs a setter.
@ -548,8 +548,8 @@ Here is the source from the `src/app/` folder.
You learned You learned
* that structural directives manipulate HTML layout. * that structural directives manipulate HTML layout.
* to use [`<ng-container>`](#ngcontainer) as a grouping element when there is no suitable host element. * to use [`<ng-container>`](guide/structural-directives#ngcontainer) as a grouping element when there is no suitable host element.
* that the Angular desugars [asterisk (*) syntax](#asterisk) into a `<template>`. * that the Angular desugars [asterisk (*) syntax](guide/structural-directives#asterisk) into a `<template>`.
* how that works for the `NgIf`, `NgFor` and `NgSwitch` built-in directives. * how that works for the `NgIf`, `NgFor` and `NgSwitch` built-in directives.
* about the [_microsyntax_](#microsyntax) that expands into a [`<template>`](#template). * about the [_microsyntax_](guide/structural-directives#microsyntax) that expands into a [`<template>`](guide/structural-directives#template).
* to write a [custom structural directive](#unless), `UnlessDirective`. * to write a [custom structural directive](guide/structural-directives#unless), `UnlessDirective`.

22
aio/content/guide/style-guide.md
View File

@ -60,16 +60,16 @@ The guideline will use the shortcut `hero.component.ts|html|css|spec` to represe
{@a toc} {@a toc}
## Table of contents ## Table of contents
1. [Single responsibility](#single-responsibility) 1. [Single responsibility](guide/style-guide#single-responsibility)
1. [Naming](#naming) 1. [Naming](guide/style-guide#naming)
1. [Coding conventions](#coding-conventions) 1. [Coding conventions](guide/style-guide#coding-conventions)
1. [App structure and Angular modules](#application-structure-and-angular-modules) 1. [App structure and Angular modules](guide/style-guide#application-structure-and-angular-modules)
1. [Components](#components) 1. [Components](guide/style-guide#components)
1. [Directives](#directives) 1. [Directives](guide/style-guide#directives)
1. [Services](#services) 1. [Services](guide/style-guide#services)
1. [Data services](#data-services) 1. [Data services](guide/style-guide#data-services)
1. [Lifecycle hooks](#lifecycle-hooks) 1. [Lifecycle hooks](guide/style-guide#lifecycle-hooks)
1. [Appendix](#appendix) 1. [Appendix](guide/style-guide#appendix)
## Single responsibility ## Single responsibility
@ -3225,7 +3225,7 @@ A typical *lazy loaded folder* contains a *routing component*, its child compone
<div class='s-why' class='s-why-last'> <div class='s-why' class='s-why-last'>
**Why?** Angular allows for an [alternative syntax](template-syntax.html#binding-syntax) `on-*`. If the event itself was prefixed with `on` this would result in an `on-onEvent` binding expression. **Why?** Angular allows for an [alternative syntax](guide/template-syntax) `on-*`. If the event itself was prefixed with `on` this would result in an `on-onEvent` binding expression.
</div> </div>

170
aio/content/guide/template-syntax.md
View File

@ -25,31 +25,31 @@ In Angular, the component plays the part of the controller/viewmodel, and the te
This guide covers the basic elements of the Angular template syntax, elements you'll need to construct the view: This guide covers the basic elements of the Angular template syntax, elements you'll need to construct the view:
* [HTML in templates](#html) * [HTML in templates](guide/template-syntax#html)
* [Interpolation ( <span class="syntax">{&#xfeff;{...}}</span> )](#interpolation) * [Interpolation ( <span class="syntax">{&#xfeff;{...}}</span> )](guide/template-syntax#interpolation)
* [Template expressions](#template-expressions) * [Template expressions](guide/template-syntax#template-expressions)
* [Template statements](#template-statements) * [Template statements](guide/template-syntax#template-statements)
* [Binding syntax](#binding-syntax) * [Binding syntax](guide/template-syntax#binding-syntax)
* [Property binding ( <span class="syntax">[property]</span> )](#property-binding) * [Property binding ( <span class="syntax">[property]</span> )](#property-binding)
* [Attribute, class, and style bindings](#other-bindings) * [Attribute, class, and style bindings](guide/template-syntax#other-bindings)
* [Event binding ( <span class="syntax">(event)</span> )](#event-binding) * [Event binding ( <span class="syntax">(event)</span> )](guide/template-syntax#event-binding)
* [Two-way data binding ( <span class="syntax">[(...)]</span> )](#two-way) * [Two-way data binding ( <span class="syntax">[(...)]</span> )](#two-way)
* [Built-in directives](#directives) * [Built-in directives](guide/template-syntax#directives)
* [Built-in attribute directives](#attribute-directives) * [Built-in attribute directives](guide/template-syntax#attribute-directives)
* [NgClass](#ngClass) * [NgClass](guide/template-syntax#ngClass)
* [NgStyle](#ngStyle) * [NgStyle](guide/template-syntax#ngStyle)
* [NgModel (<span class="syntax">[(ngModel)]</span>) ](#ngModel) * [NgModel (<span class="syntax">[(ngModel)]</span>) ](#ngModel)
* [Built-in structural directives](#structural-directives) * [Built-in structural directives](guide/template-syntax#structural-directives)
* [NgIf](#ngIf) * [NgIf](guide/template-syntax#ngIf)
* [NgFor](#ngFor) * [NgFor](guide/template-syntax#ngFor)
* [Template input variables](#template-input-variables) * [Template input variables](guide/template-syntax#template-input-variables)
* [Microsyntax](#microsyntax) * [Microsyntax](guide/template-syntax#microsyntax)
* [The NgSwitch directives](#ngSwitch) * [The NgSwitch directives](guide/template-syntax#ngSwitch)
* [Template reference variables ( <span class="syntax">#var</span> )](#ref-vars) * [Template reference variables ( <span class="syntax">#var</span> )](guide/template-syntax#ref-vars)
* [Input and output properties ( <span class="syntax">@Input</span> and <span class="syntax">@Output</span> )](#inputs-outputs) * [Input and output properties ( <span class="syntax">@Input</span> and <span class="syntax">@Output</span> )](guide/template-syntax#inputs-outputs)
* [Template expression operators](#expression-operators) * [Template expression operators](guide/template-syntax#expression-operators)
* [pipe ( <span class="syntax">|</span> )](#pipe) * [pipe ( <span class="syntax">|</span> )](guide/template-syntax#pipe)
* [safe navigation operator ( <span class="syntax">?.</span> )](#safe-navigation-operator) * [safe navigation operator ( <span class="syntax">?.</span> )](guide/template-syntax#safe-navigation-operator)
The <live-example></live-example> The <live-example></live-example>
demonstrates all of the syntax and code snippets described in this guide. demonstrates all of the syntax and code snippets described in this guide.
@ -68,7 +68,7 @@ Almost all HTML syntax is valid template syntax.
The `<script>` element is a notable exception; The `<script>` element is a notable exception;
it is forbidden, eliminating the risk of script injection attacks. it is forbidden, eliminating the risk of script injection attacks.
In practice, `<script>` is ignored and a warning appears in the browser console. In practice, `<script>` is ignored and a warning appears in the browser console.
See the [Security](security.html) page for details. See the [Security](guide/security) page for details.
Some legal HTML doesn't make much sense in a template. Some legal HTML doesn't make much sense in a template.
The `<html>`, `<body>`, and `<base>` elements have no useful role. The `<html>`, `<body>`, and `<base>` elements have no useful role.
@ -120,7 +120,7 @@ it assigns this composite interpolated result to an **element or directive prope
You appear to be inserting the result between element tags and assigning it to attributes. You appear to be inserting the result between element tags and assigning it to attributes.
It's convenient to think so, and you rarely suffer for this mistake. It's convenient to think so, and you rarely suffer for this mistake.
Though this is not exactly true. Interpolation is a special syntax that Angular converts into a Though this is not exactly true. Interpolation is a special syntax that Angular converts into a
[property binding](#property-binding), as is explained [below](#property-binding-or-interpolation-). [property binding](guide/template-syntax#property-binding), as is explained [below](guide/template-syntax#property-binding-or-interpolation-).
But first, let's take a closer look at template expressions and statements. But first, let's take a closer look at template expressions and statements.
<a href="#toc">back to top</a> <a href="#toc">back to top</a>
@ -138,7 +138,7 @@ Angular executes the expression and assigns it to a property of a binding target
the target might be an HTML element, a component, or a directive. the target might be an HTML element, a component, or a directive.
The interpolation braces in `{{1 + 1}}` surround the template expression `1 + 1`. The interpolation braces in `{{1 + 1}}` surround the template expression `1 + 1`.
In the [property binding](#property-binding) section below, In the [property binding](guide/template-syntax#property-binding) section below,
a template expression appears in quotes to the right of the&nbsp;`=` symbol as in `[property]="expression"`. a template expression appears in quotes to the right of the&nbsp;`=` symbol as in `[property]="expression"`.
You write these template expressions in a language that looks like #{_JavaScript}. You write these template expressions in a language that looks like #{_JavaScript}.
@ -154,7 +154,7 @@ including:
Other notable differences from #{_JavaScript} syntax include: Other notable differences from #{_JavaScript} syntax include:
* no support for the bitwise operators `|` and `&` * no support for the bitwise operators `|` and `&`
* new [template expression operators](#expression-operators), such as `|` and `?.` * new [template expression operators](guide/template-syntax#expression-operators), such as `|` and `?.`
{@a expression-context} {@a expression-context}
@ -168,8 +168,8 @@ In the following snippets, the `title` within double-curly braces and the
{@example 'template-syntax/ts/src/app/app.component.html' region='context-component-expression'} {@example 'template-syntax/ts/src/app/app.component.html' region='context-component-expression'}
An expression may also refer to properties of the _template's_ context An expression may also refer to properties of the _template's_ context
such as a [template input variable](#template-input-variable) (`let hero`) such as a [template input variable](guide/template-syntax#template-input-variable) (`let hero`)
or a [template reference variable](#ref-vars) (`#heroInput`). or a [template reference variable](guide/template-syntax#ref-vars) (`#heroInput`).
{@example 'template-syntax/ts/src/app/app.component.html' region='context-var'} {@example 'template-syntax/ts/src/app/app.component.html' region='context-var'}
@ -200,10 +200,10 @@ members of the expression context.
Template expressions can make or break an application. Template expressions can make or break an application.
Please follow these guidelines: Please follow these guidelines:
* [No visible side effects](#no-visible-side-effects) * [No visible side effects](guide/template-syntax#no-visible-side-effects)
* [Quick execution](#quick-execution) * [Quick execution](guide/template-syntax#quick-execution)
* [Simplicity](#simplicity) * [Simplicity](guide/template-syntax#simplicity)
* [Idempotence](#idempotence) * [Idempotence](guide/template-syntax#idempotence)
The only exceptions to these guidelines should be in specific circumstances that you thoroughly understand. The only exceptions to these guidelines should be in specific circumstances that you thoroughly understand.
@ -258,7 +258,7 @@ it returns the same object *reference* when called twice in a row.
A template **statement** responds to an **event** raised by a binding target A template **statement** responds to an **event** raised by a binding target
such as an element, component, or directive. such as an element, component, or directive.
You'll see template statements in the [event binding](#event-binding) section, You'll see template statements in the [event binding](guide/template-syntax#event-binding) section,
appearing in quotes to the right of the `=`&nbsp;symbol as in `(event)="statement"`. appearing in quotes to the right of the `=`&nbsp;symbol as in `(event)="statement"`.
@ -282,7 +282,7 @@ However, certain #{_JavaScript} syntax is not allowed:
* increment and decrement operators, `++` and `--` * increment and decrement operators, `++` and `--`
* operator assignment, such as `+=` and `-=` * operator assignment, such as `+=` and `-=`
* the bitwise operators `|` and `&` * the bitwise operators `|` and `&`
* the [template expression operators](#expression-operators) * the [template expression operators](guide/template-syntax#expression-operators)
### Statement context ### Statement context
@ -297,8 +297,8 @@ The *deleteHero* in `(click)="deleteHero()"` is a method of the data-bound compo
The statement context may also refer to properties of the template's own context. The statement context may also refer to properties of the template's own context.
In the following examples, the template `$event` object, In the following examples, the template `$event` object,
a [template input variable](#template-input-variable) (`let hero`), a [template input variable](guide/template-syntax#template-input-variable) (`let hero`),
and a [template reference variable](#ref-vars) (`#heroForm`) and a [template reference variable](guide/template-syntax#ref-vars) (`#heroForm`)
are passed to an event handling method of the component. are passed to an event handling method of the component.
@ -784,7 +784,7 @@ The following table summarizes:
## Property binding ( <span class="syntax">[property]</span> ) ## Property binding ( <span class="syntax">[property]</span> )
Write a template **property binding** to set a property of a view element. Write a template **property binding** to set a property of a view element.
The binding sets the property to the value of a [template expression](#template-expressions). The binding sets the property to the value of a [template expression](guide/template-syntax#template-expressions).
The most common property binding sets an element property to a component property value. An example is The most common property binding sets an element property to a component property value. An example is
binding the `src` property of an image element to a component's `heroImageUrl` property: binding the `src` property of an image element to a component's `heroImageUrl` property:
@ -818,13 +818,13 @@ You can't bind to a property of the target element to _read_ it. You can only _s
Similarly, you cannot use property binding to *call* a method on the target element. Similarly, you cannot use property binding to *call* a method on the target element.
If the element raises events, you can listen to them with an [event binding](#event-binding). If the element raises events, you can listen to them with an [event binding](guide/template-syntax#event-binding).
If you must read a target element property or call one of its methods, If you must read a target element property or call one of its methods,
you'll need a different technique. you'll need a different technique.
See the API reference for See the API reference for
[ViewChild](../api/core/index/ViewChild-decorator.html) and [ViewChild](api/core/index/ViewChild-decorator) and
[ContentChild](../api/core/index/ContentChild-decorator.html). [ContentChild](api/core/index/ContentChild-decorator).
### Binding target ### Binding target
An element property between enclosing square brackets identifies the target property. An element property between enclosing square brackets identifies the target property.
@ -849,7 +849,7 @@ as it is in the following example:
{@example 'template-syntax/ts/src/app/app.component.html' region='property-binding-3'} {@example 'template-syntax/ts/src/app/app.component.html' region='property-binding-3'}
Technically, Angular is matching the name to a directive [input](#inputs-outputs), Technically, Angular is matching the name to a directive [input](guide/template-syntax#inputs-outputs),
one of the property names listed in the directive's `inputs` array or a property decorated with `@Input()`. one of the property names listed in the directive's `inputs` array or a property decorated with `@Input()`.
Such inputs map to the directive's own properties. Such inputs map to the directive's own properties.
If the name fails to match a property of a known directive or element, Angular reports an “unknown directive” error. If the name fails to match a property of a known directive or element, Angular reports an “unknown directive” error.
@ -1062,7 +1062,7 @@ It removes the class when the expression is #{_falsy}.
While this is a fine way to toggle a single class name, While this is a fine way to toggle a single class name,
the [NgClass directive](#ngClass) is usually preferred when managing multiple class names at the same time. the [NgClass directive](guide/template-syntax#ngClass) is usually preferred when managing multiple class names at the same time.
<a href="#toc">back to top</a> <a href="#toc">back to top</a>
<div class='l-hr'> <div class='l-hr'>
@ -1087,11 +1087,11 @@ The following example conditionally sets the font size in “em” and “%”
While this is a fine way to set a single style, While this is a fine way to set a single style,
the [NgStyle directive](#ngStyle) is generally preferred when setting several inline styles at the same time. the [NgStyle directive](guide/template-syntax#ngStyle) is generally preferred when setting several inline styles at the same time.
Note that a _style property_ name can be written in either Note that a _style property_ name can be written in either
[dash-case](glossary.html#dash-case), as shown above, or [dash-case](guide/glossary), as shown above, or
[camelCase](glossary.html#camelcase), such as `fontSize`. [camelCase](guide/glossary), such as `fontSize`.
<a href="#toc">back to top</a> <a href="#toc">back to top</a>
<div class='l-hr'> <div class='l-hr'>
@ -1114,7 +1114,7 @@ You declare your interest in user actions through Angular event binding.
Event binding syntax consists of a **target event** name Event binding syntax consists of a **target event** name
within parentheses on the left of an equal sign, and a quoted within parentheses on the left of an equal sign, and a quoted
[template statement](#template-statements) on the right. [template statement](guide/template-syntax#template-statements) on the right.
The following event binding listens for the button's click events, calling The following event binding listens for the button's click events, calling
the component's `onSave()` method whenever a click occurs: the component's `onSave()` method whenever a click occurs:
@ -1142,7 +1142,7 @@ of a known directive, as it does in the following example:
The `myClick` directive is further described in the section The `myClick` directive is further described in the section
on [aliasing input/output properties](#aliasing-io). on [aliasing input/output properties](guide/template-syntax#aliasing-io).
If the name fails to match an element event or an output property of a known directive, If the name fails to match an element event or an output property of a known directive,
Angular reports an “unknown directive” error. Angular reports an “unknown directive” error.
@ -1160,7 +1160,7 @@ an **event object named `$event`**.
The shape of the event object is determined by the target event. The shape of the event object is determined by the target event.
If the target event is a native DOM element event, then `$event` is a If the target event is a native DOM element event, then `$event` is a
[DOM event object]( https://developer.mozilla.org/en-US/docs/Web/Events), [DOM event object](guide/ https:/developer.mozilla.org/en-US/docs/Web/Events),
with properties such as `target` and `target.value`. with properties such as `target` and `target.value`.
Consider this example: Consider this example:
@ -1185,7 +1185,7 @@ If the event belongs to a directive (recall that components are directives),
{@a custom-event} {@a custom-event}
### Custom events with <span class="syntax">EventEmitter</span> ### Custom events with <span class="syntax">EventEmitter</span>
Directives typically raise custom events with an Angular [EventEmitter](../api/core/index/EventEmitter-class.html). Directives typically raise custom events with an Angular [EventEmitter](api/core/index/EventEmitter-class).
The directive creates an `EventEmitter` and exposes it as a property. The directive creates an `EventEmitter` and exposes it as a property.
The directive calls `EventEmitter.emit(payload)` to fire an event, passing in a message payload, which can be anything. The directive calls `EventEmitter.emit(payload)` to fire an event, passing in a message payload, which can be anything.
Parent directives listen for the event by binding to this property and accessing the payload through the `$event` object. Parent directives listen for the event by binding to this property and accessing the payload through the `$event` object.
@ -1271,7 +1271,7 @@ Clearly the two-way binding syntax is a great convenience compared to separate p
It would be convenient to use two-way binding with HTML form elements like `<input>` and `<select>`. It would be convenient to use two-way binding with HTML form elements like `<input>` and `<select>`.
However, no native HTML element follows the `x` value and `xChange` event pattern. However, no native HTML element follows the `x` value and `xChange` event pattern.
Fortunately, the Angular [_NgModel_](#ngModel) directive is a bridge that enables two-way binding to form elements. Fortunately, the Angular [_NgModel_](guide/template-syntax#ngModel) directive is a bridge that enables two-way binding to form elements.
<a href="#toc">back to top</a> <a href="#toc">back to top</a>
<div class='l-hr'> <div class='l-hr'>
@ -1298,7 +1298,7 @@ Angular still ships with built-in directives; just not as many.
You'll write your own directives, just not as many. You'll write your own directives, just not as many.
This segment reviews some of the most frequently used built-in directives, This segment reviews some of the most frequently used built-in directives,
classified as either [_attribute_ directives](#attribute-directives) or [_structural_ directives](#structural-directives). classified as either [_attribute_ directives](guide/template-syntax#attribute-directives) or [_structural_ directives](guide/template-syntax#structural-directives).
<div class='l-hr'> <div class='l-hr'>
@ -1313,14 +1313,14 @@ Attribute directives listen to and modify the behavior of
other HTML elements, attributes, properties, and components. other HTML elements, attributes, properties, and components.
They are usually applied to elements as if they were HTML attributes, hence the name. They are usually applied to elements as if they were HTML attributes, hence the name.
Many details are covered in the [_Attribute Directives_](attribute-directives.html) guide. Many details are covered in the [_Attribute Directives_](guide/attribute-directives) guide.
Many Angular modules such as the [`RouterModule`](router.html "Routing and Navigation") Many Angular modules such as the [`RouterModule`](guide/router)
and the [`FormsModule`](forms.html "Forms") define their own attribute directives. and the [`FormsModule`](guide/forms) define their own attribute directives.
This section is an introduction to the most commonly used attribute directives: This section is an introduction to the most commonly used attribute directives:
* [`NgClass`](#ngClass) - add and remove a set of CSS classes * [`NgClass`](guide/template-syntax#ngClass) - add and remove a set of CSS classes
* [`NgStyle`](#ngStyle) - add and remove a set of HTML styles * [`NgStyle`](guide/template-syntax#ngStyle) - add and remove a set of HTML styles
* [`NgModel`](#ngModel) - two-way data binding to an HTML form element * [`NgModel`](guide/template-syntax#ngModel) - two-way data binding to an HTML form element
<a href="#toc">back to top</a> <a href="#toc">back to top</a>
<div class='l-hr'> <div class='l-hr'>
@ -1335,7 +1335,7 @@ You typically control how elements appear
by adding and removing CSS classes dynamically. by adding and removing CSS classes dynamically.
You can bind to the `ngClass` to add or remove several classes simultaneously. You can bind to the `ngClass` to add or remove several classes simultaneously.
A [class binding](#class-binding) is a good way to add or remove a *single* class. A [class binding](guide/template-syntax#class-binding) is a good way to add or remove a *single* class.
{@example 'template-syntax/ts/src/app/app.component.html' region='class-binding-3a'} {@example 'template-syntax/ts/src/app/app.component.html' region='class-binding-3a'}
@ -1372,7 +1372,7 @@ It's up to you to call `setCurrentClassess()`, both initially and when the depen
You can set inline styles dynamically, based on the state of the component. You can set inline styles dynamically, based on the state of the component.
With `NgStyle` you can set many inline styles simultaneously. With `NgStyle` you can set many inline styles simultaneously.
A [style binding](#style-binding) is an easy way to set a *single* style value. A [style binding](guide/template-syntax#style-binding) is an easy way to set a *single* style value.
{@example 'template-syntax/ts/src/app/app.component.html' region='NgStyle-1'} {@example 'template-syntax/ts/src/app/app.component.html' region='NgStyle-1'}
@ -1432,11 +1432,11 @@ The `ngModel` data property sets the element's value property and the `ngModelCh
listens for changes to the element's value. listens for changes to the element's value.
The details are specific to each kind of element and therefore the `NgModel` directive only works for an element The details are specific to each kind of element and therefore the `NgModel` directive only works for an element
supported by a [ControlValueAccessor](../api/forms/index/ControlValueAccessor-interface.html) supported by a [ControlValueAccessor](api/forms/index/ControlValueAccessor-interface)
that adapts an element to this protocol. that adapts an element to this protocol.
The `<input>` box is one of those elements. The `<input>` box is one of those elements.
Angular provides *value accessors* for all of the basic HTML form elements and the Angular provides *value accessors* for all of the basic HTML form elements and the
[_Forms_](forms.html) guide shows how to bind to them. [_Forms_](guide/forms) guide shows how to bind to them.
You can't apply `[(ngModel)]` to a non-form native element or a third-party custom component You can't apply `[(ngModel)]` to a non-form native element or a third-party custom component
until you write a suitable *value accessor*, until you write a suitable *value accessor*,
@ -1444,8 +1444,8 @@ a technique that is beyond the scope of this guide.
You don't need a _value accessor_ for an Angular component that you write because you You don't need a _value accessor_ for an Angular component that you write because you
can name the value and event properties can name the value and event properties
to suit Angular's basic [two-way binding syntax](#two-way) and skip `NgModel` altogether. to suit Angular's basic [two-way binding syntax](guide/template-syntax#two-way) and skip `NgModel` altogether.
The [`sizer` shown above](#two-way) is an example of this technique. The [`sizer` shown above](guide/template-syntax#two-way) is an example of this technique.
Separate `ngModel` bindings is an improvement over binding to the element's native properties. You can do better. Separate `ngModel` bindings is an improvement over binding to the element's native properties. You can do better.
You shouldn't have to mention the data property twice. Angular should be able to capture You shouldn't have to mention the data property twice. Angular should be able to capture
@ -1491,21 +1491,21 @@ They shape or reshape the DOM's _structure_, typically by adding, removing, and
the host elements to which they are attached. the host elements to which they are attached.
The deep details of structural directives are covered in the The deep details of structural directives are covered in the
[_Structural Directives_](structural-directives.html) guide [_Structural Directives_](guide/structural-directives) guide
where you'll learn: where you'll learn:
* why you * why you
[_prefix the directive name with an asterisk_ (\*)](structural-directives.html#asterisk "The * in *ngIf"). [_prefix the directive name with an asterisk_ (\*)](guide/structural-directives).
* to use [`<ng-container>`](structural-directives.html#ngcontainer "<ng-container>") * to use [`<ng-container>`](guide/structural-directives)
to group elements when there is no suitable host element for the directive. to group elements when there is no suitable host element for the directive.
* how to write your own structural directive. * how to write your own structural directive.
* that you can only apply [one structural directive](structural-directives.html#one-per-element "one per host element") to an element. * that you can only apply [one structural directive](guide/structural-directives) to an element.
_This_ section is an introduction to the common structural directives: _This_ section is an introduction to the common structural directives:
* [`NgIf`](#ngIf) - conditionally add or remove an element from the DOM * [`NgIf`](guide/template-syntax#ngIf) - conditionally add or remove an element from the DOM
* [`NgFor`](#ngFor) - repeat a template for each item in a list * [`NgFor`](guide/template-syntax#ngFor) - repeat a template for each item in a list
* [`NgSwitch`](#ngSwitch) - a set of directives that switch among alternative views * [`NgSwitch`](guide/template-syntax#ngSwitch) - a set of directives that switch among alternative views
<div class='l-hr'> <div class='l-hr'>
@ -1539,7 +1539,7 @@ from the DOM, destroying that component and all of its sub-components.
#### Show/hide is not the same thing #### Show/hide is not the same thing
You can control the visibility of an element with a You can control the visibility of an element with a
[class](#class-binding) or [style](#style-binding) binding: [class](guide/template-syntax#class-binding) or [style](guide/template-syntax#style-binding) binding:
{@example 'template-syntax/ts/src/app/app.component.html' region='NgIf-3'} {@example 'template-syntax/ts/src/app/app.component.html' region='NgIf-3'}
@ -1574,7 +1574,7 @@ The `nullHero` will never be displayed.
See also the See also the
[_safe navigation operator_](#safe-navigation-operator "Safe naviation operator (?.)") [_safe navigation operator_](guide/template-syntax#safe-navigation-operator "Safe naviation operator (?.)")
described below. described below.
<a href="#toc">back to top</a> <a href="#toc">back to top</a>
<div class='l-hr'> <div class='l-hr'>
@ -1615,7 +1615,7 @@ The text assigned to `*ngFor` is the instruction that guides the repeater proces
{@a microsyntax} {@a microsyntax}
#### *ngFor microsyntax #### *ngFor microsyntax
The string assigned to `*ngFor` is not a [template expression](#template-expressions). The string assigned to `*ngFor` is not a [template expression](guide/template-syntax#template-expressions).
It's a *microsyntax* &mdash; a little language of its own that Angular interprets. It's a *microsyntax* &mdash; a little language of its own that Angular interprets.
The string `"let hero of heroes"` means: The string `"let hero of heroes"` means:
@ -1626,7 +1626,7 @@ Angular translates this instruction into a `<template>` around the host element,
then uses this template repeatedly to create a new set of elements and bindings for each `hero` then uses this template repeatedly to create a new set of elements and bindings for each `hero`
in the list. in the list.
Learn about the _microsyntax_ in the [_Structural Directives_](structural-directives.html#microsyntax) guide. Learn about the _microsyntax_ in the [_Structural Directives_](guide/structural-directives) guide.
{@a template-input-variable} {@a template-input-variable}
@ -1648,7 +1648,7 @@ and then passed in a binding to the `hero` property of the `<hero-detail>` compo
{@example 'template-syntax/ts/src/app/app.component.html' region='NgFor-1-2'} {@example 'template-syntax/ts/src/app/app.component.html' region='NgFor-1-2'}
Learn more about _template input variables_ in the Learn more about _template input variables_ in the
[_Structural Directives_](structural-directives.html#template-input-variable) guide. [_Structural Directives_](guide/structural-directives) guide.
#### *ngFor with _index_ #### *ngFor with _index_
@ -1662,7 +1662,7 @@ The next example captures the `index` in a variable named `i` and displays it wi
Learn about the other `NgFor` context values such as `last`, `even`, Learn about the other `NgFor` context values such as `last`, `even`,
and `odd` in the [NgFor API reference](../api/common/index/NgFor-directive.html). and `odd` in the [NgFor API reference](api/common/index/NgFor-directive).
{@a trackBy} {@a trackBy}
@ -1747,7 +1747,7 @@ because they add or remove elements from the DOM.
The switch directives are particularly useful for adding and removing *component elements*. The switch directives are particularly useful for adding and removing *component elements*.
This example switches among four "emotional hero" components defined in the `hero-switch.components.ts` file. This example switches among four "emotional hero" components defined in the `hero-switch.components.ts` file.
Each component has a `hero` [input property](#inputs-outputs "Input property") Each component has a `hero` [input property](guide/template-syntax#inputs-outputs "Input property")
which is bound to the `currentHero` of the parent component. which is bound to the `currentHero` of the parent component.
Switch directives work as well with native elements and web components too. Switch directives work as well with native elements and web components too.
@ -1796,7 +1796,7 @@ The phone button click handler passes the _input_ value to the component's `call
But a directive can change that behavior and set the value to something else, such as itself. But a directive can change that behavior and set the value to something else, such as itself.
The `NgForm` directive does that. The `NgForm` directive does that.
The following is a *simplified* version of the form example in the [Forms](forms.html) guide. The following is a *simplified* version of the form example in the [Forms](guide/forms) guide.
{@example 'template-syntax/ts/src/app/hero-form.component.html'} {@example 'template-syntax/ts/src/app/hero-form.component.html'}
@ -1807,7 +1807,7 @@ What is the value of `heroForm`?
If Angular hadn't taken it over when you imported the `FormsModule`, If Angular hadn't taken it over when you imported the `FormsModule`,
it would be the [HTMLFormElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement). it would be the [HTMLFormElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement).
The `heroForm` is actually a reference to an Angular [NgForm](../api/forms/index/NgForm-directive.html "API: NgForm") The `heroForm` is actually a reference to an Angular [NgForm](api/forms/index/NgForm-directive)
directive with the ability to track the value and validity of every control in the form. directive with the ability to track the value and validity of every control in the form.
The native `<form>` element doesn't have a `form` property. The native `<form>` element doesn't have a `form` property.
@ -1818,8 +1818,8 @@ to the parent component's `onSubmit` method.
### Template reference variable warning notes ### Template reference variable warning notes
A template _reference_ variable (`#phone`) is _not_ the same as a template _input_ variable (`let phone`) A template _reference_ variable (`#phone`) is _not_ the same as a template _input_ variable (`let phone`)
such as you might see in an [`*ngFor`](#template-input-variable). such as you might see in an [`*ngFor`](guide/template-syntax#template-input-variable).
Learn the difference in the [_Structural Directives_](structural-directives.html#template-input-variable) guide. Learn the difference in the [_Structural Directives_](guide/structural-directives) guide.
The scope of a reference variable is the _entire template_. The scope of a reference variable is the _entire template_.
Do not define the same variable name more than once in the same template. Do not define the same variable name more than once in the same template.
@ -1931,7 +1931,7 @@ because events stream *out* of that property and toward the handler in a templat
Sometimes the public name of an input/output property should be different from the internal name. Sometimes the public name of an input/output property should be different from the internal name.
This is frequently the case with [attribute directives](attribute-directives.html). This is frequently the case with [attribute directives](guide/attribute-directives).
Directive consumers expect to bind to the name of the directive. Directive consumers expect to bind to the name of the directive.
For example, when you apply a directive with a `myClick` selector to a `<div>` tag, For example, when you apply a directive with a `myClick` selector to a `<div>` tag,
you expect to bind to an event property that is also called `myClick`. you expect to bind to an event property that is also called `myClick`.
@ -1981,7 +1981,7 @@ for specific scenarios. The next sections cover two of these operators: _pipe_ a
The result of an expression might require some transformation before you're ready to use it in a binding. The result of an expression might require some transformation before you're ready to use it in a binding.
For example, you might display a number as a currency, force text to uppercase, or filter a list and sort it. For example, you might display a number as a currency, force text to uppercase, or filter a list and sort it.
Angular [pipes](./pipes.html) are a good choice for small transformations such as these. Angular [pipes](guide/pipes) are a good choice for small transformations such as these.
Pipes are simple functions that accept an input value and return a transformed value. Pipes are simple functions that accept an input value and return a transformed value.
They're easy to apply within template expressions, using the **pipe operator (`|`)**: They're easy to apply within template expressions, using the **pipe operator (`|`)**:
@ -1995,7 +1995,7 @@ You can chain expressions through multiple pipes:
{@example 'template-syntax/ts/src/app/app.component.html' region='pipes-2'} {@example 'template-syntax/ts/src/app/app.component.html' region='pipes-2'}
And you can also [apply parameters](./pipes.html#parameterizing-a-pipe) to a pipe: And you can also [apply parameters](guide/pipes) to a pipe:
{@example 'template-syntax/ts/src/app/app.component.html' region='pipes-3'} {@example 'template-syntax/ts/src/app/app.component.html' region='pipes-3'}
@ -2066,7 +2066,7 @@ the null property path should display as blank just as the `title` property does
Unfortunately, the app crashes when the `currentHero` is null. Unfortunately, the app crashes when the `currentHero` is null.
You could code around that problem with [*ngIf](#ngIf). You could code around that problem with [*ngIf](guide/template-syntax#ngIf).
{@example 'template-syntax/ts/src/app/app.component.html' region='safe-4'} {@example 'template-syntax/ts/src/app/app.component.html' region='safe-4'}

58
aio/content/guide/ts-to-js.md
View File

@ -19,16 +19,16 @@ can read and write Angular apps in their preferred dialect.
{@a toc} {@a toc}
## Table of contents ## Table of contents
[_TypeScript_ to _ES6_ to _ES5_](#from-ts)<br> [_TypeScript_ to _ES6_ to _ES5_](guide/ts-to-js#from-ts)<br>
[Modularity: imports and exports](#modularity)<br> [Modularity: imports and exports](guide/ts-to-js#modularity)<br>
[Classes and Class Metadata](#class-metadata)<br> [Classes and Class Metadata](guide/ts-to-js#class-metadata)<br>
[_ES5_ DSL](#dsl)<br> [_ES5_ DSL](guide/ts-to-js#dsl)<br>
[Interfaces](#interfaces)<br> [Interfaces](guide/ts-to-js#interfaces)<br>
[Input and Output Metadata](#io-decorators)<br> [Input and Output Metadata](guide/ts-to-js#io-decorators)<br>
[Dependency Injection](#dependency-injection)<br> [Dependency Injection](guide/ts-to-js#dependency-injection)<br>
[Host Binding](#host-binding)<br> [Host Binding](guide/ts-to-js#host-binding)<br>
[View and Child Decorators](#view-child-decorators)<br> [View and Child Decorators](guide/ts-to-js#view-child-decorators)<br>
[AOT compilation in _TypeScript_ Only](#aot)<br> [AOT compilation in _TypeScript_ Only](guide/ts-to-js#aot)<br>
**Run and compare the live <live-example name="cb-ts-to-js">_TypeScript_</live-example> and <live-example name="cb-ts-to-js" lang="js">JavaScript</live-example> **Run and compare the live <live-example name="cb-ts-to-js">_TypeScript_</live-example> and <live-example name="cb-ts-to-js" lang="js">JavaScript</live-example>
code shown in this cookbook.** code shown in this cookbook.**
@ -81,7 +81,7 @@ To use decorators and annotations with Babel, install the
In both _TypeScript_ and _ES6_, you import Angular classes, functions, and other members with _ES6_ `import` statements. In both _TypeScript_ and _ES6_, you import Angular classes, functions, and other members with _ES6_ `import` statements.
In _ES5_, you access the Angular entities of the [the Angular packages](../glossary.html#scoped-package) In _ES5_, you access the Angular entities of the [the Angular packages](glossary)
through the global `ng` object. through the global `ng` object.
Anything you can import from `@angular` is a nested member of this `ng` object: Anything you can import from `@angular` is a nested member of this `ng` object:
@ -260,7 +260,7 @@ Use the constructor function pattern instead, adding methods to the prototype.
When writing in _TypeScript_ or _ES6-with-decorators_, When writing in _TypeScript_ or _ES6-with-decorators_,
provide configuration and metadata by adorning a class with one or more *decorators*. provide configuration and metadata by adorning a class with one or more *decorators*.
For example, you supply metadata to a component class by preceding its definition with a For example, you supply metadata to a component class by preceding its definition with a
[`@Component`](../api/core/index/Component-decorator.html) decorator function whose [`@Component`](api/core/index/Component-decorator) decorator function whose
argument is an object literal with metadata properties. argument is an object literal with metadata properties.
In _plain ES6_, you provide metadata by attaching an `annotations` array to the _class_. In _plain ES6_, you provide metadata by attaching an `annotations` array to the _class_.
@ -477,7 +477,7 @@ Just implement the methods and ignore interfaces when translating code samples f
### Input and Output Decorators ### Input and Output Decorators
In _TypeScript_ and _ES6-with-decorators_, you often add metadata to class _properties_ with _property decorators_. In _TypeScript_ and _ES6-with-decorators_, you often add metadata to class _properties_ with _property decorators_.
For example, you apply [`@Input` and `@Output` property decorators](../guide/template-syntax.html#inputs-outputs) For example, you apply [`@Input` and `@Output` property decorators](guide/template-syntax)
to public class properties that will be the target of data binding expressions in parent components. to public class properties that will be the target of data binding expressions in parent components.
There is no equivalent of a property decorator in _ES5_ or _plain ES6_. There is no equivalent of a property decorator in _ES5_ or _plain ES6_.
@ -529,7 +529,7 @@ you specify the special binding name in the argument to the property decorator.
In _ES5_ and _plain ES6_ code, convey this pairing with the `propertyName: bindingName` syntax in the class metadata. In _ES5_ and _plain ES6_ code, convey this pairing with the `propertyName: bindingName` syntax in the class metadata.
## Dependency Injection ## Dependency Injection
Angular relies heavily on [Dependency Injection](../guide/dependency-injection.html) to provide services to the objects it creates. Angular relies heavily on [Dependency Injection](guide/dependency-injection) to provide services to the objects it creates.
When Angular creates a new component, directive, pipe or another service, When Angular creates a new component, directive, pipe or another service,
it sets the class constructor parameters to instances of services provided by an _Injector_. it sets the class constructor parameters to instances of services provided by an _Injector_.
@ -642,12 +642,12 @@ You can qualify injection behavior with injection decorators from `@angular/core
In _TypeScript_ and _ES6-with-decorators_, In _TypeScript_ and _ES6-with-decorators_,
you precede the constructor parameters with injection qualifiers such as: you precede the constructor parameters with injection qualifiers such as:
* [`@Optional`](../api/core/index/Optional-decorator.html) sets the parameter to `null` if the service is missing * [`@Optional`](api/core/index/Optional-decorator) sets the parameter to `null` if the service is missing
* [`@Attribute`](../api/core/index/Attribute-interface.html) to inject a host element attribute value * [`@Attribute`](api/core/index/Attribute-interface) to inject a host element attribute value
* [`@ContentChild`](../api/core/index/ContentChild-decorator.html) to inject a content child * [`@ContentChild`](api/core/index/ContentChild-decorator) to inject a content child
* [`@ViewChild`](../api/core/index/ViewChild-decorator.html) to inject a view child * [`@ViewChild`](api/core/index/ViewChild-decorator) to inject a view child
* [`@Host`](../api/core/index/Host-decorator.html) to inject a service in this component or its host * [`@Host`](api/core/index/Host-decorator) to inject a service in this component or its host
* [`@SkipSelf`](../api/core/index/SkipSelf-decorator.html) to inject a service provided in an ancestor of this component * [`@SkipSelf`](api/core/index/SkipSelf-decorator) to inject a service provided in an ancestor of this component
In _plain ES6_ and _ES5_, create an instance of the equivalent injection qualifier in a nested array within the `parameters` array. In _plain ES6_ and _ES5_, create an instance of the equivalent injection qualifier in a nested array within the `parameters` array.
For example, you'd write `new Optional()` in _plain ES6_ and `new ng.core.Optional()` in _ES5_. For example, you'd write `new Optional()` in _plain ES6_ and `new ng.core.Optional()` in _ES5_.
@ -702,9 +702,9 @@ element whose tag matches the component selector.
In _TypeScript_ and _ES6-with-decorators_, you can use host property decorators to bind a host In _TypeScript_ and _ES6-with-decorators_, you can use host property decorators to bind a host
element to a component or directive. element to a component or directive.
The [`@HostBinding`](../api/core/index/HostBinding-interface.html) decorator The [`@HostBinding`](api/core/index/HostBinding-interface) decorator
binds host element properties to component data properties. binds host element properties to component data properties.
The [`@HostListener`](../api/core/index/HostListener-interface.html) decorator binds The [`@HostListener`](api/core/index/HostListener-interface) decorator binds
host element events to component event handlers. host element events to component event handlers.
In _plain ES6_ or _ES5_, add a `host` attribute to the component metadata to achieve the In _plain ES6_ or _ES5_, add a `host` attribute to the component metadata to achieve the
@ -778,8 +778,8 @@ Several _property_ decorators query a component's nested view and content compon
_View_ children are associated with element tags that appear _within_ the component's template. _View_ children are associated with element tags that appear _within_ the component's template.
_Content_ children are associated with elements that appear _between_ the component's element tags; _Content_ children are associated with elements that appear _between_ the component's element tags;
they are projected into an `<ng-content>` slot in the component's template. The [`@ViewChild`](../api/core/index/ViewChild-decorator.html) and they are projected into an `<ng-content>` slot in the component's template. The [`@ViewChild`](api/core/index/ViewChild-decorator) and
[`@ViewChildren`](../api/core/index/ViewChildren-decorator.html) property decorators [`@ViewChildren`](api/core/index/ViewChildren-decorator) property decorators
allow a component to query instances of other components that are used in allow a component to query instances of other components that are used in
its view. its view.
@ -813,13 +813,13 @@ The `queries` property value is a hash map.
</md-tab-group> </md-tab-group>
The [`@ContentChild`](../api/core/index/ContentChild-decorator.html) and The [`@ContentChild`](api/core/index/ContentChild-decorator) and
[`@ContentChildren`](../api/core/index/ContentChildren-decorator.html) property decorators [`@ContentChildren`](api/core/index/ContentChildren-decorator) property decorators
allow a component to query instances of other components that have been projected allow a component to query instances of other components that have been projected
into its view from elsewhere. into its view from elsewhere.
They can be added in the same way as [`@ViewChild`](../api/core/index/ViewChild-decorator.html) and They can be added in the same way as [`@ViewChild`](api/core/index/ViewChild-decorator) and
[`@ViewChildren`](../api/core/index/ViewChildren-decorator.html). [`@ViewChildren`](api/core/index/ViewChildren-decorator).
<md-tab-group> <md-tab-group>
@ -862,7 +862,7 @@ instead of the `@ViewChild` and `@ContentChild` property decorators.
## AOT Compilation in _TypeScript_ only ## AOT Compilation in _TypeScript_ only
Angular offers two modes of template compilation, JIT (_Just-in-Time_) and Angular offers two modes of template compilation, JIT (_Just-in-Time_) and
[AOT (_Ahead-of-Time_)](aot-compiler.html). [AOT (_Ahead-of-Time_)](guide/aot-compiler).
Currently the AOT compiler only works with _TypeScript_ applications because, in part, it generates Currently the AOT compiler only works with _TypeScript_ applications because, in part, it generates
_TypeScript_ files as an intermediate result. _TypeScript_ files as an intermediate result.
**AOT is not an option for pure JavaScript applications** at this time. **AOT is not an option for pure JavaScript applications** at this time.

106
aio/content/guide/upgrade.md
View File

@ -30,32 +30,32 @@ business, because the work can be done collaboratively and spread over
a period of time. The `upgrade` module in Angular has been designed to a period of time. The `upgrade` module in Angular has been designed to
make incremental upgrading seamless. make incremental upgrading seamless.
1. [Preparation](#preparation) 1. [Preparation](guide/upgrade#preparation)
1. [Follow the Angular Style Guide](#follow-the-angular-style-guide) 1. [Follow the Angular Style Guide](guide/upgrade#follow-the-angular-style-guide)
2. [Using a Module Loader](#using-a-module-loader) 2. [Using a Module Loader](guide/upgrade#using-a-module-loader)
3. [Migrating to TypeScript](#migrating-to-typescript) 3. [Migrating to TypeScript](guide/upgrade#migrating-to-typescript)
4. [Using Component Directives](#using-component-directives) 4. [Using Component Directives](guide/upgrade#using-component-directives)
2. [Upgrading with The Upgrade Module](#upgrading-with-the-upgrade-module) 2. [Upgrading with The Upgrade Module](guide/upgrade#upgrading-with-the-upgrade-module)
1. [How The Upgrade Module Works](#how-the-upgrade-module-works) 1. [How The Upgrade Module Works](guide/upgrade#how-the-upgrade-module-works)
2. [Bootstrapping hybrid](#bootstrapping-hybrid-applications) 2. [Bootstrapping hybrid](guide/upgrade#bootstrapping-hybrid-applications)
3. [Using Angular Components from AngularJS Code](#using-angular-components-from-angularjs-code) 3. [Using Angular Components from AngularJS Code](guide/upgrade#using-angular-components-from-angularjs-code)
4. [Using AngularJS Component Directives from Angular Code](#using-angularjs-component-directives-from-angular-code) 4. [Using AngularJS Component Directives from Angular Code](guide/upgrade#using-angularjs-component-directives-from-angular-code)
5. [Projecting AngularJS Content into Angular Components](#projecting-angularjs-content-into-angular-components) 5. [Projecting AngularJS Content into Angular Components](guide/upgrade#projecting-angularjs-content-into-angular-components)
6. [Transcluding Angular Content into AngularJS Component Directives](#transcluding-angular-content-into-angularjs-component-directives) 6. [Transcluding Angular Content into AngularJS Component Directives](guide/upgrade#transcluding-angular-content-into-angularjs-component-directives)
7. [Making AngularJS Dependencies Injectable to Angular](#making-angularjs-dependencies-injectable-to-angular) 7. [Making AngularJS Dependencies Injectable to Angular](guide/upgrade#making-angularjs-dependencies-injectable-to-angular)
8. [Making Angular Dependencies Injectable to AngularJS](#making-angular-dependencies-injectable-to-angularjs) 8. [Making Angular Dependencies Injectable to AngularJS](guide/upgrade#making-angular-dependencies-injectable-to-angularjs)
9. [Using Ahead-of-time compilation with hybrid apps](#using-ahead-of-time-compilation-with-hybrid-apps) 9. [Using Ahead-of-time compilation with hybrid apps](guide/upgrade#using-ahead-of-time-compilation-with-hybrid-apps)
10. [Dividing routes between Angular and AngularJS](#dividing-routes-between-angular-and-angularjs) 10. [Dividing routes between Angular and AngularJS](guide/upgrade#dividing-routes-between-angular-and-angularjs)
3. [PhoneCat Upgrade Tutorial](#phonecat-upgrade-tutorial) 3. [PhoneCat Upgrade Tutorial](guide/upgrade#phonecat-upgrade-tutorial)
1. [Switching to TypeScript](#switching-to-typescript) 1. [Switching to TypeScript](guide/upgrade#switching-to-typescript)
2. [Installing Angular](#installing-angular) 2. [Installing Angular](guide/upgrade#installing-angular)
3. [Bootstrapping a hybrid PhoneCat](#bootstrapping-a-hybrid-phonecat) 3. [Bootstrapping a hybrid PhoneCat](guide/upgrade#bootstrapping-a-hybrid-phonecat)
4. [Upgrading the Phone service](#upgrading-the-phone-service) 4. [Upgrading the Phone service](guide/upgrade#upgrading-the-phone-service)
5. [Upgrading Components](#upgrading-components) 5. [Upgrading Components](guide/upgrade#upgrading-components)
6. [AoT compile the hybrid app](#aot-compile-the-hybrid-app) 6. [AoT compile the hybrid app](guide/upgrade#aot-compile-the-hybrid-app)
7. [Adding The Angular Router And Bootstrap](#adding-the-angular-router-and-bootstrap) 7. [Adding The Angular Router And Bootstrap](guide/upgrade#adding-the-angular-router-and-bootstrap)
8. [Say Goodbye to AngularJS](#say-goodbye-to-angularjs) 8. [Say Goodbye to AngularJS](guide/upgrade#say-goodbye-to-angularjs)
3. [Appendix: Upgrading PhoneCat Tests](#appendix-upgrading-phonecat-tests) 3. [Appendix: Upgrading PhoneCat Tests](guide/upgrade#appendix-upgrading-phonecat-tests)
## Preparation ## Preparation
@ -207,7 +207,7 @@ using the component API:
Controller lifecycle hook methods `$onInit()`, `$onDestroy()`, and `$onChanges()` Controller lifecycle hook methods `$onInit()`, `$onDestroy()`, and `$onChanges()`
are another convenient feature that AngularJS 1.5 introduces. They all have nearly are another convenient feature that AngularJS 1.5 introduces. They all have nearly
exact [equivalents in Angular](lifecycle-hooks.html), so organizing component lifecycle exact [equivalents in Angular](guide/lifecycle-hooks), so organizing component lifecycle
logic around them will ease the eventual Angular upgrade process. logic around them will ease the eventual Angular upgrade process.
## Upgrading with The Upgrade Module ## Upgrading with The Upgrade Module
@ -266,7 +266,7 @@ frameworks in how it actually works.
<td> <td>
Tokens [can have different types](../guide/dependency-injection.html). Tokens [can have different types](guide/dependency-injection).
They are often classes. They may also be strings. They are often classes. They may also be strings.
</td> </td>
@ -283,7 +283,7 @@ frameworks in how it actually works.
<td> <td>
There is a [tree hierarchy of injectors](../guide/hierarchical-dependency-injection.html), There is a [tree hierarchy of injectors](guide/hierarchical-dependency-injection),
with a root injector and an additional injector for each component. with a root injector and an additional injector for each component.
</td> </td>
@ -379,7 +379,7 @@ bindings get updated.
In Angular things are different. While change detection still In Angular things are different. While change detection still
occurs after every event, no one needs to call `scope.$apply()` for occurs after every event, no one needs to call `scope.$apply()` for
that to happen. This is because all Angular code runs inside something that to happen. This is because all Angular code runs inside something
called the [Angular zone](../api/core/index/NgZone-class.html). Angular always called the [Angular zone](api/core/index/NgZone-class). Angular always
knows when the code finishes, so it also knows when it should kick off knows when the code finishes, so it also knows when it should kick off
change detection. The code itself doesn't have to call `scope.$apply()` change detection. The code itself doesn't have to call `scope.$apply()`
or anything like it. or anything like it.
@ -408,7 +408,7 @@ When we downgrade an Angular component and then use it from AngularJS,
the component's inputs will be watched using AngularJS change detection. the component's inputs will be watched using AngularJS change detection.
When those inputs change, the corresponding properties in the component When those inputs change, the corresponding properties in the component
are set. We can also hook into the changes by implementing the are set. We can also hook into the changes by implementing the
[OnChanges](../api/core/index/OnChanges-class.html) interface in the component, [OnChanges](api/core/index/OnChanges-class) interface in the component,
just like we could if it hadn't been downgraded. just like we could if it hadn't been downgraded.
Correspondingly, when we upgrade an AngularJS component and use it from Angular, Correspondingly, when we upgrade an AngularJS component and use it from Angular,
@ -432,7 +432,7 @@ That means that we need at least one module each from both AngularJS and Angular
We will import `UpgradeModule` inside our Angular module, and then use it for We will import `UpgradeModule` inside our Angular module, and then use it for
bootstrapping our AngularJS module. Let's see how. bootstrapping our AngularJS module. Let's see how.
Learn more about Angular modules at the [NgModule guide](ngmodule.html). Learn more about Angular modules at the [NgModule guide](guide/ngmodule).
### Bootstrapping hybrid applications ### Bootstrapping hybrid applications
The first step to upgrading an application using the `UpgradeModule` is The first step to upgrading an application using the `UpgradeModule` is
@ -460,7 +460,7 @@ will result in the same thing:
{@example 'upgrade-module/ts/src/app/ajs-bootstrap/app.module.ts' region='bootstrap'} {@example 'upgrade-module/ts/src/app/ajs-bootstrap/app.module.ts' region='bootstrap'}
Now introduce Angular to the project. Inspired by instructions in Now introduce Angular to the project. Inspired by instructions in
[the Setup](setup.html), you can selectively copy in material from the [the Setup](guide/setup), you can selectively copy in material from the
<a href="https://github.com/angular/quickstart" target="_blank">QuickStart github repository</a>. <a href="https://github.com/angular/quickstart" target="_blank">QuickStart github repository</a>.
Next, create an `app.module.ts` file and add the following `NgModule` class: Next, create an `app.module.ts` file and add the following `NgModule` class:
@ -615,7 +615,7 @@ Angular.
Not all kinds of AngularJS directives can be upgraded. The directive Not all kinds of AngularJS directives can be upgraded. The directive
really has to be a *component directive*, with the characteristics really has to be a *component directive*, with the characteristics
[described in the preparation guide above](#using-component-directives). [described in the preparation guide above](guide/upgrade#using-component-directives).
Our safest bet for ensuring compatibility is using the Our safest bet for ensuring compatibility is using the
[component API](https://docs.angularjs.org/api/ng/type/angular.Module) [component API](https://docs.angularjs.org/api/ng/type/angular.Module)
introduced in AngularJS 1.5. introduced in AngularJS 1.5.
@ -860,7 +860,7 @@ code. For example, we might have a service called `HeroesService` in AngularJS:
{@example 'upgrade-module/ts/src/app/ajs-to-a-providers/heroes.service.ts'} {@example 'upgrade-module/ts/src/app/ajs-to-a-providers/heroes.service.ts'}
We can upgrade the service using a Angular [Factory provider](./dependency-injection.html#factory-providers) We can upgrade the service using a Angular [Factory provider](guide/dependency-injection)
that requests the service from the AngularJS `$injector`. that requests the service from the AngularJS `$injector`.
We recommend declaring the Factory Provider in a separate `ajs-upgraded-providers.ts` file We recommend declaring the Factory Provider in a separate `ajs-upgraded-providers.ts` file
@ -929,7 +929,7 @@ After this, the service is injectable anywhere in our AngularJS code:
We can take advantage of Ahead-of-time (AoT) compilation on hybrid apps just like on any other We can take advantage of Ahead-of-time (AoT) compilation on hybrid apps just like on any other
Angular application. Angular application.
The setup for an hybrid app is mostly the same as described in The setup for an hybrid app is mostly the same as described in
[the Ahead-of-time Compilation chapter](../cookbook/aot-compiler.html) [the Ahead-of-time Compilation chapter](cookbook/aot-compiler)
save for differences in `index.html` and `main-aot.ts` save for differences in `index.html` and `main-aot.ts`
Our `index.html` will likely have script tags loading AngularJS files, so the `index.html` we Our `index.html` will likely have script tags loading AngularJS files, so the `index.html` we
@ -986,7 +986,7 @@ Next we declare both AngularJS and Angular routes as normal:
In our `app.module.ts` we need to add `AppComponent` to the declarations and boostrap array. In our `app.module.ts` we need to add `AppComponent` to the declarations and boostrap array.
Next we configure the router itself. Next we configure the router itself.
We want to use [hash navigation](./router.html#-hashlocationstrategy-) in Angular We want to use [hash navigation](guide/router) in Angular
because that's what we're also using in AngularJS. because that's what we're also using in AngularJS.
Lastly, and most importantly, we want to use a custom `UrlHandlingStrategy` that will tell Lastly, and most importantly, we want to use a custom `UrlHandlingStrategy` that will tell
@ -1008,7 +1008,7 @@ which is where many of us began our Angular adventures. Now we'll see how to
bring that application to the brave new world of Angular. bring that application to the brave new world of Angular.
During the process we'll learn how to apply the steps outlined in the During the process we'll learn how to apply the steps outlined in the
[preparation guide](#preparation) in practice: We'll align the application [preparation guide](guide/upgrade#preparation) in practice: We'll align the application
with Angular and also take TypeScript into use. with Angular and also take TypeScript into use.
To follow along with the tutorial, clone the To follow along with the tutorial, clone the
@ -1204,7 +1204,7 @@ In terms of project structure, this is where our work begins:
This is actually a pretty good starting point. The code uses the AngularJS 1.5 This is actually a pretty good starting point. The code uses the AngularJS 1.5
component API and the organization follows the component API and the organization follows the
[AngularJS Style Guide](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md), [AngularJS Style Guide](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md),
which is an important [preparation step](#following-the-angular-style-guide) before which is an important [preparation step](guide/upgrade#following-the-angular-style-guide) before
a successful upgrade. a successful upgrade.
* Each component, service, and filter is in its own source file, as per the * Each component, service, and filter is in its own source file, as per the
@ -1246,7 +1246,7 @@ Jasmine unit test framework.
We should also configure the TypeScript compiler so that it can understand our We should also configure the TypeScript compiler so that it can understand our
project. We'll add a `tsconfig.json` file to the project directory, just like we do project. We'll add a `tsconfig.json` file to the project directory, just like we do
in the documentation [setup](setup.html). It instructs the TypeScript compiler how in the documentation [setup](guide/setup). It instructs the TypeScript compiler how
to interpret our source files. to interpret our source files.
We are telling the TypeScript compiler to turn our TypeScript files to ES5 code We are telling the TypeScript compiler to turn our TypeScript files to ES5 code
bundled into CommonJS modules. bundled into CommonJS modules.
@ -1362,7 +1362,7 @@ We'll instead turn it directly into an Angular service.
Having completed our preparation work, let's get going with the Angular Having completed our preparation work, let's get going with the Angular
upgrade of PhoneCat. We'll do this incrementally with the help of the upgrade of PhoneCat. We'll do this incrementally with the help of the
[upgrade module](#upgrading-with-the-upgrade-module) that comes with Angular. [upgrade module](guide/upgrade#upgrading-with-the-upgrade-module) that comes with Angular.
By the time we're done, we'll be able to remove AngularJS from the project By the time we're done, we'll be able to remove AngularJS from the project
completely, but the key is to do this piece by piece without breaking the application. completely, but the key is to do this piece by piece without breaking the application.
@ -1374,7 +1374,7 @@ The project also contains some animations, which we are not yet upgrading in thi
~~~ ~~~
Let's install Angular into the project, along with the SystemJS module loader. Let's install Angular into the project, along with the SystemJS module loader.
Take a look at the results of the [Setup](setup.html) instructions Take a look at the results of the [Setup](guide/setup) instructions
and get the following configurations from there: and get the following configurations from there:
* Add Angular and the other new dependencies to `package.json` * Add Angular and the other new dependencies to `package.json`
@ -1411,7 +1411,7 @@ to load the actual application:
{@example 'upgrade-phonecat-2-hybrid/ts/index.html' region='angular'} {@example 'upgrade-phonecat-2-hybrid/ts/index.html' region='angular'}
We also need to make a couple of adjustments We also need to make a couple of adjustments
to the `systemjs.config.js` file installed during [setup](setup.html). to the `systemjs.config.js` file installed during [setup](guide/setup).
We want to point the browser to the project root when loading things through SystemJS, We want to point the browser to the project root when loading things through SystemJS,
instead of using the `<base>` URL. instead of using the `<base>` URL.
@ -1443,7 +1443,7 @@ What we'll do next is bootstrap the application as a *hybrid application*
that supports both AngularJS and Angular components. Once we've done that that supports both AngularJS and Angular components. Once we've done that
we can start converting the individual pieces to Angular. we can start converting the individual pieces to Angular.
To [bootstrap a hybrid application](#bootstrapping-hybrid-applications), To [bootstrap a hybrid application](guide/upgrade#bootstrapping-hybrid-applications),
we first need to import `UpgradeModule` in our `AppModule`, and override it's bootstrap method: we first need to import `UpgradeModule` in our `AppModule`, and override it's bootstrap method:
@ -1514,7 +1514,7 @@ service in `phone.service.ts` with a TypeScript class decorated as `@Injectable`
The `@Injectable` decorator will attach some dependency injection metadata The `@Injectable` decorator will attach some dependency injection metadata
to the class, letting Angular know about its dependencies. As described to the class, letting Angular know about its dependencies. As described
by our [Dependency Injection Guide](./dependency-injection.html), by our [Dependency Injection Guide](guide/dependency-injection),
this is a marker decorator we need to use for classes that have no other this is a marker decorator we need to use for classes that have no other
Angular decorators but still need to have their dependencies injected. Angular decorators but still need to have their dependencies injected.
@ -1614,7 +1614,7 @@ with Angular's two-way `[(ngModel)]` binding syntax:
{@example 'upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.template.html' region='controls'} {@example 'upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.template.html' region='controls'}
Replace the list's `ng-repeat` with an `*ngFor` as Replace the list's `ng-repeat` with an `*ngFor` as
[described in the Template Syntax page](../guide/template-syntax.html#directives). [described in the Template Syntax page](guide/template-syntax).
Replace the image tag's `ng-src` with a binding to the native `src` property. Replace the image tag's `ng-src` with a binding to the native `src` property.
@ -1662,7 +1662,7 @@ which was injected into `PhoneDetails` when it was still an AngularJS controller
We intend to inject it into the new `PhoneDetailsComponent`. We intend to inject it into the new `PhoneDetailsComponent`.
Unfortunately, AngularJS dependencies are not automatically available to Angular components. Unfortunately, AngularJS dependencies are not automatically available to Angular components.
We must use a [Factory provider](#making-angularjs-dependencies-injectable-to-angular) We must use a [Factory provider](guide/upgrade#making-angularjs-dependencies-injectable-to-angular)
to make `$routeParams` an Angular provider. to make `$routeParams` an Angular provider.
Do that in a new file called `ajs-upgraded-providers.ts` and import it in `app.module.ts`: Do that in a new file called `ajs-upgraded-providers.ts` and import it in `app.module.ts`:
@ -1684,7 +1684,7 @@ There are several notable changes here:
* Just like we did in the phone list, we've replaced `ng-src` with property * Just like we did in the phone list, we've replaced `ng-src` with property
bindings for the standard `src` property. bindings for the standard `src` property.
* We're using the property binding syntax around `ng-class`. Though Angular * We're using the property binding syntax around `ng-class`. Though Angular
does have [a very similar `ngClass`](../guide/template-syntax.html#directives) does have [a very similar `ngClass`](guide/template-syntax)
as AngularJS does, its value is not magically evaluated as an expression. as AngularJS does, its value is not magically evaluated as an expression.
In Angular we always specify in the template when an attribute's value is In Angular we always specify in the template when an attribute's value is
a property expression, as opposed to a literal string. a property expression, as opposed to a literal string.
@ -1727,7 +1727,7 @@ remove the filter &lt;script&gt; tag from `index.html`:
## AoT compile the hybrid app ## AoT compile the hybrid app
To use AoT with our hybrid app we have to first set it up like any other Angular application, To use AoT with our hybrid app we have to first set it up like any other Angular application,
as shown in [the Ahead-of-time Compilation chapter](../cookbook/aot-compiler.html). as shown in [the Ahead-of-time Compilation chapter](cookbook/aot-compiler).
Then we have to change `main-aot.ts` bootstrap also bootstrap the AngularJS app Then we have to change `main-aot.ts` bootstrap also bootstrap the AngularJS app
via `UpgradeModule`: via `UpgradeModule`:
@ -1764,7 +1764,7 @@ while keeping `/phones/:phoneId` in the AngularJS router.
#### Add the Angular router #### Add the Angular router
Angular has an [all-new router](router.html). Angular has an [all-new router](guide/router).
Like all routers, it needs a place in the UI to display routed views. Like all routers, it needs a place in the UI to display routed views.
For Angular that's the `<router-outlet>` and it belongs in a *root component* For Angular that's the `<router-outlet>` and it belongs in a *root component*
@ -1792,7 +1792,7 @@ It replaces the old AngularJS `ng-view` directive:
#### Create the _Routing Module_ #### Create the _Routing Module_
A router needs configuration whether it's the AngularJS or Angular or any other router. A router needs configuration whether it's the AngularJS or Angular or any other router.
The details of Angular router configuration are best left to the [Routing documentation](router.html) The details of Angular router configuration are best left to the [Routing documentation](guide/router)
which recommends that you create a `NgModule` dedicated to router configuration which recommends that you create a `NgModule` dedicated to router configuration
(called a _Routing Module_). (called a _Routing Module_).
@ -1838,7 +1838,7 @@ and let that directive construct the appropriate URL to the `PhoneDetailComponen
{@example 'upgrade-phonecat-3-router/ts/app/phone-list/phone-list.template.html' region='list'} {@example 'upgrade-phonecat-3-router/ts/app/phone-list/phone-list.template.html' region='list'}
See the [Routing](router.html) page for details. See the [Routing](guide/router) page for details.
We are now running both routers at the same time! We are now running both routers at the same time!
Angular is handling the initial `/` url, redirecting to `/phones`. Angular is handling the initial `/` url, redirecting to `/phones`.
Meanwhile when we click a link to the phone detail, AngularJS takes over. Meanwhile when we click a link to the phone detail, AngularJS takes over.
@ -1881,7 +1881,7 @@ to the Angular way.
{@example 'upgrade-phonecat-4-final/ts/app/main.ts'} {@example 'upgrade-phonecat-4-final/ts/app/main.ts'}
If you haven't already, remove all references to the `UpgradeModule` from `app.module.ts`, If you haven't already, remove all references to the `UpgradeModule` from `app.module.ts`,
as well as any [Factory provider](#making-angularjs-dependencies-injectable-to-angular) as well as any [Factory provider](guide/upgrade#making-angularjs-dependencies-injectable-to-angular)
for AngularJS services, and the `app/ajs-upgraded-providers.ts` file. for AngularJS services, and the `app/ajs-upgraded-providers.ts` file.
Also remove any `downgradeInjectable()` or `downgradeComponent()` you find, Also remove any `downgradeInjectable()` or `downgradeComponent()` you find,

10
aio/content/guide/user-input.md
View File

@ -13,13 +13,13 @@ event binding syntax.
Run the <live-example></live-example>. Run the <live-example></live-example>.
## Binding to user input events ## Binding to user input events
You can use [Angular event bindings](./template-syntax.html#event-binding) You can use [Angular event bindings](guide/template-syntax)
to respond to any [DOM event](https://developer.mozilla.org/en-US/docs/Web/Events). to respond to any [DOM event](https://developer.mozilla.org/en-US/docs/Web/Events).
Many DOM events are triggered by user input. Binding to these events provides a way to Many DOM events are triggered by user input. Binding to these events provides a way to
get input from the user. get input from the user.
To bind to a DOM event, surround the DOM event name in parentheses and assign a quoted To bind to a DOM event, surround the DOM event name in parentheses and assign a quoted
[template statement](./template-syntax.html#template-statements) to it. [template statement](guide/template-syntax) to it.
The following example shows an event binding that implements a click handler: The following example shows an event binding that implements a click handler:
@ -63,7 +63,7 @@ In this case, `target` refers to the [`<input>` element](https://developer.mozil
After each call, the `onKey()` method appends the contents of the input box value to the list After each call, the `onKey()` method appends the contents of the input box value to the list
in the component's `values` property, followed by a separator character (|). in the component's `values` property, followed by a separator character (|).
The [interpolation](./template-syntax.html#interpolation) The [interpolation](guide/template-syntax)
displays the accumulating input box changes from the `values` property. displays the accumulating input box changes from the `values` property.
Suppose the user enters the letters "abc", and then backspaces to remove them one by one. Suppose the user enters the letters "abc", and then backspaces to remove them one by one.
@ -114,7 +114,7 @@ The next section shows how to use template reference variables to address this p
## Get user input from a template reference variable ## Get user input from a template reference variable
There's another way to get the user data: use Angular There's another way to get the user data: use Angular
[**template reference variables**](./template-syntax.html#ref-vars). [**template reference variables**](guide/template-syntax).
These variables provide direct access to an element from within the template. These variables provide direct access to an element from within the template.
To declare a template reference variable, precede an identifier with a hash (or pound) character (#). To declare a template reference variable, precede an identifier with a hash (or pound) character (#).
@ -184,7 +184,7 @@ To fix this issue, listen to both the _Enter_ key and the _blur_ event.
## Put it all together ## Put it all together
The previous page showed how to [display data](./displaying-data.html). The previous page showed how to [display data](guide/displaying-data).
This page demonstrated event binding techniques. This page demonstrated event binding techniques.
Now, put it all together in a micro-app Now, put it all together in a micro-app

18
aio/content/guide/visual-studio-2015.md
View File

@ -21,15 +21,15 @@ then consider the _experimental_
Note that the resulting code does not map to the docs. Adjust accordingly. Note that the resulting code does not map to the docs. Adjust accordingly.
The steps are as follows: The steps are as follows:
- [Prerequisite](#prereq1): Install Node.js - [Prerequisite](guide/visual-studio-2015#prereq1): Install Node.js
- [Prerequisite](#prereq2): Install Visual Studio 2015 Update 3 - [Prerequisite](guide/visual-studio-2015#prereq2): Install Visual Studio 2015 Update 3
- [Prerequisite](#prereq3): Configure External Web tools - [Prerequisite](guide/visual-studio-2015#prereq3): Configure External Web tools
- [Prerequisite](#prereq4): Install TypeScript 2 for Visual Studio 2015 - [Prerequisite](guide/visual-studio-2015#prereq4): Install TypeScript 2 for Visual Studio 2015
- [Step 1](#download): Download the QuickStart files - [Step 1](guide/visual-studio-2015#download): Download the QuickStart files
- [Step 2](#create-project): Create the Visual Studio ASP.NET project - [Step 2](guide/visual-studio-2015#create-project): Create the Visual Studio ASP.NET project
- [Step 3](#copy): Copy the QuickStart files into the ASP.NET project folder - [Step 3](guide/visual-studio-2015#copy): Copy the QuickStart files into the ASP.NET project folder
- [Step 4](#restore): Restore required packages - [Step 4](guide/visual-studio-2015#restore): Restore required packages
- [Step 5](#build-and-run): Build and run the app - [Step 5](guide/visual-studio-2015#build-and-run): Build and run the app
<h2 id='prereq1'> <h2 id='prereq1'>

40
aio/content/guide/webpack.md
View File

@ -22,22 +22,22 @@ This guide offers a taste of Webpack and explains how to use it with Angular app
<a id="top"></a> <a id="top"></a>
## Table of contents ## Table of contents
[What is Webpack?](#what-is-webpack) [What is Webpack?](guide/webpack#what-is-webpack)
* [Entries and outputs](#entries-outputs) * [Entries and outputs](guide/webpack#entries-outputs)
* [Loaders](#loaders) * [Loaders](guide/webpack#loaders)
* [Plugins](#plugins) * [Plugins](guide/webpack#plugins)
[Configuring Webpack](#configure-webpack) [Configuring Webpack](guide/webpack#configure-webpack)
* [Common configuration](#common-configuration) * [Common configuration](guide/webpack#common-configuration)
* [Development configuration](#development-configuration) * [Development configuration](guide/webpack#development-configuration)
* [Production configuration](#production-configuration) * [Production configuration](guide/webpack#production-configuration)
* [Test configuration](#test-configuration) * [Test configuration](guide/webpack#test-configuration)
[Trying it out](#try) [Trying it out](guide/webpack#try)
[Conclusions](#conclusions) [Conclusions](guide/webpack#conclusions)
You can also <a href="/resources/zips/webpack/webpack.zip">download the final result.</a> You can also <a href="/resources/zips/webpack/webpack.zip">download the final result.</a>
@ -95,7 +95,7 @@ and emits *two* bundle files, one called `app.js` containing only the applicatio
another called `vendor.js` with all the vendor dependencies. another called `vendor.js` with all the vendor dependencies.
The `[name]` in the output name is a *placeholder* that a Webpack plugin replaces with the entry names, The `[name]` in the output name is a *placeholder* that a Webpack plugin replaces with the entry names,
`app` and `vendor`. Plugins are [covered later](#commons-chunk-plugin) in the guide. `app` and `vendor`. Plugins are [covered later](guide/webpack#commons-chunk-plugin) in the guide.
To tell Webpack what belongs in the vendor bundle, To tell Webpack what belongs in the vendor bundle,
add a `vendor.ts` file that only imports the application's third-party modules: add a `vendor.ts` file that only imports the application's third-party modules:
@ -191,8 +191,8 @@ Add these files:
Many of these files should be familiar from other Angular documentation guides, Many of these files should be familiar from other Angular documentation guides,
especially the [_Typescript configuration_](../guide/typescript-configuration.html) and especially the [_Typescript configuration_](guide/typescript-configuration) and
[_npm packages_](../guide/npm-packages.html) guides. [_npm packages_](guide/npm-packages) guides.
Webpack, the plugins, and the loaders are also installed as packages. Webpack, the plugins, and the loaders are also installed as packages.
They are listed in the updated `packages.json`. They are listed in the updated `packages.json`.
@ -209,7 +209,7 @@ Open a terminal window and (re)install the *npm* packages
### Polyfills ### Polyfills
You'll need polyfills to run an Angular application in most browsers as explained You'll need polyfills to run an Angular application in most browsers as explained
in the [_Browser Support_](browser-support.html) guide. in the [_Browser Support_](guide/browser-support) guide.
Polyfills should be bundled separately from the application and vendor bundles. Polyfills should be bundled separately from the application and vendor bundles.
Add a `polyfills.ts` like this one to the `src/` folder. Add a `polyfills.ts` like this one to the `src/` folder.
@ -253,10 +253,10 @@ Webpack is a NodeJS-based tool that reads configuration from a JavaScript _commo
The configuration imports dependencies with `require` statements The configuration imports dependencies with `require` statements
and exports several objects as properties of a `module.exports` object. and exports several objects as properties of a `module.exports` object.
* [`entries`](#common-entries) - the entry-point files that define the bundles. * [`entries`](guide/webpack#common-entries) - the entry-point files that define the bundles.
* [`resolve`](#common-resolve) - how to resolve file names when they lack extensions. * [`resolve`](guide/webpack#common-resolve) - how to resolve file names when they lack extensions.
* [`module.rules`](#common-rules) - `module` is an object with `rules` for deciding how files are loaded. * [`module.rules`](guide/webpack#common-rules) - `module` is an object with `rules` for deciding how files are loaded.
* [`plugins`](#common-plugins) - creates instances of the plugins. * [`plugins`](guide/webpack#common-plugins) - creates instances of the plugins.
{@a common-entries} {@a common-entries}
@ -567,4 +567,4 @@ for a small Angular application.
_You could always do more_. Search the web for expert advice and expand your Webpack knowledge. _You could always do more_. Search the web for expert advice and expand your Webpack knowledge.
[Back to top](#top) [Back to top](guide/webpack#top)

10
aio/content/tutorial/toh-pt1.md
View File

@ -8,7 +8,7 @@ We build a simple hero editor.
## Setup to develop locally ## Setup to develop locally
Real application development takes place in a local development environment like your machine. Real application development takes place in a local development environment like your machine.
Follow the [setup](../guide/setup.html) instructions for creating a new project Follow the [setup](guide/setup) instructions for creating a new project
named <ngio-ex path="angular-tour-of-heroes"></ngio-ex> named <ngio-ex path="angular-tour-of-heroes"></ngio-ex>
after which the file structure should look like this: after which the file structure should look like this:
@ -109,7 +109,7 @@ The browser should refresh and display our title and hero.
The double curly braces tell our app to read the `title` and `hero` properties from the component and render them. The double curly braces tell our app to read the `title` and `hero` properties from the component and render them.
This is the "interpolation" form of one-way data binding. This is the "interpolation" form of one-way data binding.
Learn more about interpolation in the [Displaying Data chapter](../guide/displaying-data.html).### Hero object Learn more about interpolation in the [Displaying Data chapter](guide/displaying-data).### Hero object
At the moment, our hero is just a name. Our hero needs more properties. At the moment, our hero is just a name. Our hero needs more properties.
Let's convert the `hero` from a literal string to a class. Let's convert the `hero` from a literal string to a class.
@ -189,8 +189,8 @@ Now we have included the forms package which includes `ngModel`.
Learn more about the `FormsModule` and `ngModel` in the Learn more about the `FormsModule` and `ngModel` in the
[Forms](../guide/forms.html#ngModel) and [Forms](guide/forms) and
[Template Syntax](../guide/template-syntax.html#ngModel) chapters. [Template Syntax](guide/template-syntax) chapters.
Let’s update the template to use the **`ngModel`** built-in directive for two-way binding. Let’s update the template to use the **`ngModel`** built-in directive for two-way binding.
Replace the `<input>` with the following HTML Replace the `<input>` with the following HTML
@ -226,4 +226,4 @@ Our Tour of Heroes only displays one hero and we really want to display a list o
We also want to allow the user to select a hero and display their details. We also want to allow the user to select a hero and display their details.
We’ll learn more about how to retrieve lists, bind them to the We’ll learn more about how to retrieve lists, bind them to the
template, and allow a user to select a hero in the template, and allow a user to select a hero in the
[next tutorial chapter](./toh-pt2.html). [next tutorial chapter](tutorial/toh-pt2).

18
aio/content/tutorial/toh-pt2.md
View File

@ -17,7 +17,7 @@ so we’ll need a way to do that.
## Where We Left Off ## Where We Left Off
Before we continue with Part 2 of the Tour of Heroes, Before we continue with Part 2 of the Tour of Heroes,
let’s verify we have the following structure after [Part 1](./toh-pt1.html). let’s verify we have the following structure after [Part 1](tutorial/toh-pt1).
If not, we’ll need to go back to Part 1 and figure out what we missed. If not, we’ll need to go back to Part 1 and figure out what we missed.
<aio-filetree> <aio-filetree>
@ -160,8 +160,8 @@ The `let` keyword before "hero" identifies `hero` as a template input variable.
We can reference this variable within the template to access a hero’s properties. We can reference this variable within the template to access a hero’s properties.
Learn more about `ngFor` and template input variables in the Learn more about `ngFor` and template input variables in the
[Displaying Data](../guide/displaying-data.html#ngFor) and [Displaying Data](guide/displaying-data) and
[Template Syntax](../guide/template-syntax.html#ngFor) chapters. [Template Syntax](guide/template-syntax) chapters.
Now we insert some content between the `<li>` tags Now we insert some content between the `<li>` tags
that uses the `hero` template variable to display the hero’s properties. that uses the `hero` template variable to display the hero’s properties.
@ -219,8 +219,8 @@ The expression to the right of the equal sign calls the `AppComponent` method,
passing the template input variable `hero` as an argument. passing the template input variable `hero` as an argument.
That’s the same `hero` variable we defined previously in the `ngFor`. That’s the same `hero` variable we defined previously in the `ngFor`.
Learn more about Event Binding in the Learn more about Event Binding in the
[User Input](../guide/user-input.html) and [User Input](guide/user-input) and
[Templating Syntax](../guide/template-syntax.html#event-binding) chapters.### Add the click handler [Templating Syntax](guide/template-syntax) chapters.### Add the click handler
Our event binding refers to an `onSelect` method that doesn’t exist yet. Our event binding refers to an `onSelect` method that doesn’t exist yet.
We’ll add that method to our component now. We’ll add that method to our component now.
@ -291,8 +291,8 @@ structure of portions of the DOM.
In other words, they give structure to the way Angular displays content in the DOM. In other words, they give structure to the way Angular displays content in the DOM.
Learn more about `ngIf`, `ngFor` and other structural directives in the Learn more about `ngIf`, `ngFor` and other structural directives in the
[Structural Directives](../guide/structural-directives.html) and [Structural Directives](guide/structural-directives) and
[Template Syntax](../guide/template-syntax.html#directives) chapters. [Template Syntax](guide/template-syntax) chapters.
The browser refreshes and we see the list of heroes but not the selected hero detail. The browser refreshes and we see the list of heroes but not the selected hero detail.
The `ngIf` keeps it out of the DOM as long as the `selectedHero` is undefined. The `ngIf` keeps it out of the DOM as long as the `selectedHero` is undefined.
When we click on a hero in the list, the selected hero displays in the hero details. When we click on a hero in the list, the selected hero displays in the hero details.
@ -323,7 +323,7 @@ from the data source (the expression `hero === selectedHero`) to a property of `
{@example 'toh-2/ts-snippets/app.component.snippets.pt2.ts' region='class-selected-2'} {@example 'toh-2/ts-snippets/app.component.snippets.pt2.ts' region='class-selected-2'}
Learn more about [property bindings](../guide/template-syntax.html#property-binding) Learn more about [property bindings](guide/template-syntax)
in the Template Syntax chapter. in the Template Syntax chapter.
The browser reloads our app. The browser reloads our app.
We select the hero Magneta and the selection is clearly identified by the background color. We select the hero Magneta and the selection is clearly identified by the background color.
@ -353,4 +353,4 @@ Run the <live-example></live-example> for this part.
Our Tour of Heroes has grown, but it’s far from complete. Our Tour of Heroes has grown, but it’s far from complete.
We can't put the entire app into a single component. We can't put the entire app into a single component.
We need to break it up into sub-components and teach them to work together We need to break it up into sub-components and teach them to work together
as we learn in the [next chapter](toh-pt3.html). as we learn in the [next chapter](tutorial/toh-pt3).

10
aio/content/tutorial/toh-pt3.md
View File

@ -117,8 +117,8 @@ Notice that we have an `AppComponent` in a file named `app.component.ts` and ou
All of our component names end in "Component". All of our component file names end in ".component". All of our component names end in "Component". All of our component file names end in ".component".
We spell our file names in lower **[dash case](../guide/glossary.html#dash-case)** We spell our file names in lower **[dash case](guide/glossary)**
(AKA **[kebab-case](../guide/glossary.html#kebab-case)**) so we don't worry about (AKA **[kebab-case](guide/glossary)**) so we don't worry about
case sensitivity on the server or in source control. case sensitivity on the server or in source control.
<!-- TODO <!-- TODO
@ -182,7 +182,7 @@ Notice that the `hero` property is the ***target*** of a property binding &mdash
Angular insists that we declare a ***target*** property to be an ***input*** property. Angular insists that we declare a ***target*** property to be an ***input*** property.
If we don't, Angular rejects the binding and throws an error. If we don't, Angular rejects the binding and throws an error.
We explain input properties in more detail [here](../guide/attribute-directives.html#why-input) We explain input properties in more detail [here](guide/attribute-directives)
where we also explain why *target* properties require this special treatment and where we also explain why *target* properties require this special treatment and
*source* properties do not.There are a couple of ways we can declare that `hero` is an *input*. *source* properties do not.There are a couple of ways we can declare that `hero` is an *input*.
We'll do it the way we *prefer*, by annotating the `hero` property with the `@Input` decorator that we imported earlier. We'll do it the way we *prefer*, by annotating the `hero` property with the `@Input` decorator that we imported earlier.
@ -191,7 +191,7 @@ We'll do it the way we *prefer*, by annotating the `hero` property with the `@In
Learn more about the `@Input()` decorator in the Learn more about the `@Input()` decorator in the
[Attribute Directives](../guide/attribute-directives.html#input) chapter. [Attribute Directives](guide/attribute-directives) chapter.
## Refresh the AppModule ## Refresh the AppModule
We return to the `AppModule`, the application's root module, and teach it to use the `HeroDetailComponent`. We return to the `AppModule`, the application's root module, and teach it to use the `HeroDetailComponent`.
@ -362,4 +362,4 @@ That's not sustainable.
We should refactor data access to a separate service We should refactor data access to a separate service
and share it among the components that need data. and share it among the components that need data.
We’ll learn to create services in the [next tutorial](toh-pt4.html) chapter. We’ll learn to create services in the [next tutorial](tutorial/toh-pt4) chapter.

10
aio/content/tutorial/toh-pt4.md
View File

@ -127,7 +127,7 @@ share that service with all components that need heroes.
### Create the HeroService ### Create the HeroService
Create a file in the `app` folder called `hero.service.ts`. Create a file in the `app` folder called `hero.service.ts`.
We've adopted a convention in which we spell the name of a service in lowercase followed by `.service`. We've adopted a convention in which we spell the name of a service in lowercase followed by `.service`.
If the service name were multi-word, we'd spell the base filename in lower [dash-case](../guide/glossary.html#dash-case). If the service name were multi-word, we'd spell the base filename in lower [dash-case](guide/glossary).
The `SpecialSuperHeroService` would be defined in the `special-super-hero.service.ts` file.We name the class `HeroService` and export it for others to import. The `SpecialSuperHeroService` would be defined in the `special-super-hero.service.ts` file.We name the class `HeroService` and export it for others to import.
@ -234,7 +234,7 @@ Here's the constructor:
The constructor itself does nothing. The parameter simultaneously The constructor itself does nothing. The parameter simultaneously
defines a private `heroService` property and identifies it as a `HeroService` injection site.Now Angular will know to supply an instance of the `HeroService` when it creates a new `AppComponent`. defines a private `heroService` property and identifies it as a `HeroService` injection site.Now Angular will know to supply an instance of the `HeroService` when it creates a new `AppComponent`.
Learn more about Dependency Injection in the [Dependency Injection](../guide/dependency-injection.html) chapter.The *injector* does not know yet how to create a `HeroService`. Learn more about Dependency Injection in the [Dependency Injection](guide/dependency-injection) chapter.The *injector* does not know yet how to create a `HeroService`.
If we ran our code now, Angular would fail with an error: If we ran our code now, Angular would fail with an error:
<code-example format="nocode"> <code-example format="nocode">
EXCEPTION: No provider for HeroService! (AppComponent -> HeroService) EXCEPTION: No provider for HeroService! (AppComponent -> HeroService)
@ -272,7 +272,7 @@ Angular offers a number of interfaces for tapping into critical moments in the c
at creation, after each change, and at its eventual destruction. at creation, after each change, and at its eventual destruction.
Each interface has a single method. When the component implements that method, Angular calls it at the appropriate time. Each interface has a single method. When the component implements that method, Angular calls it at the appropriate time.
Learn more about lifecycle hooks in the [Lifecycle Hooks](../guide/lifecycle-hooks.html) chapter.Here's the essential outline for the `OnInit` interface: Learn more about lifecycle hooks in the [Lifecycle Hooks](guide/lifecycle-hooks) chapter.Here's the essential outline for the `OnInit` interface:
{@example 'toh-4/ts/src/app/app.component.1.ts' region='on-init'} {@example 'toh-4/ts/src/app/app.component.1.ts' region='on-init'}
@ -332,7 +332,7 @@ in the callback is more succinct than the equivalent function expression and gra
Our app should still be running, still showing a list of heroes, and still Our app should still be running, still showing a list of heroes, and still
responding to a name selection with a detail view. responding to a name selection with a detail view.
Checkout the "[Take it slow](#slow)" appendix to see what the app might be like with a poor connection.### Review the App Structure Checkout the "[Take it slow](tutorial/toh-pt4#slow)" appendix to see what the app might be like with a poor connection.### Review the App Structure
Let’s verify that we have the following structure after all of our good refactoring in this chapter: Let’s verify that we have the following structure after all of our good refactoring in this chapter:
<aio-filetree> <aio-filetree>
@ -456,7 +456,7 @@ Our Tour of Heroes has become more reusable using shared components and services
We want to create a dashboard, add menu links that route between the views, and format data in a template. We want to create a dashboard, add menu links that route between the views, and format data in a template.
As our app evolves, we’ll learn how to design it to make it easier to grow and maintain. As our app evolves, we’ll learn how to design it to make it easier to grow and maintain.
We learn about Angular Component Router and navigation among the views in the [next tutorial](toh-pt5.html) chapter. We learn about Angular Component Router and navigation among the views in the [next tutorial](tutorial/toh-pt5) chapter.
<a id="slow"></a>### Appendix: Take it slow <a id="slow"></a>### Appendix: Take it slow

16
aio/content/tutorial/toh-pt5.md
View File

@ -20,7 +20,7 @@ When we’re done, users will be able to navigate the app like this:
We'll add Angular’s *Router* to our app to satisfy these requirements. We'll add Angular’s *Router* to our app to satisfy these requirements.
The [Routing and Navigation](../guide/router.html) chapter covers the router The [Routing and Navigation](guide/router) chapter covers the router
in more detail than we will in this tutorial. in more detail than we will in this tutorial.
Run the <live-example></live-example> for this part. Run the <live-example></live-example> for this part.
@ -107,7 +107,7 @@ at the top of the `<head>` section.
base href is essential base href is essential
</header> </header>
See the *base href* section of the [router](../guide/router.html#base-href) See the *base href* section of the [router](guide/router)
guide to learn why this matters, and what to add if the `base` guide to learn why this matters, and what to add if the `base`
element is missing. element is missing.
@ -131,7 +131,7 @@ This *route definition* has the following parts:
it *must* begin with a capital letter to avoid confusion with the *path* (`Heroes`).</li> it *must* begin with a capital letter to avoid confusion with the *path* (`Heroes`).</li>
- **component**: the component that the router should create when navigating to this route (`HeroesComponent`). - **component**: the component that the router should create when navigating to this route (`HeroesComponent`).
Learn more about defining routes with `!{_RoutesVsAtRouteConfig}` in the [Routing](../guide/router.html) chapter. Learn more about defining routes with `!{_RoutesVsAtRouteConfig}` in the [Routing](guide/router) chapter.
### Router Outlet ### Router Outlet
If we paste the path, `/heroes`, into the browser address bar, If we paste the path, `/heroes`, into the browser address bar,
@ -322,7 +322,7 @@ using the `Location` service we injected previously.
Going back too far could take us out of the application. Going back too far could take us out of the application.
That's acceptable in a demo. We'd guard against it in a real application, That's acceptable in a demo. We'd guard against it in a real application,
perhaps with the [!{_CanDeactivateGuard}](../api/!{_CanDeactivateGuardUri}.html). perhaps with the [!{_CanDeactivateGuard}](api/!{_CanDeactivateGuardUri}).
Then we wire this method with an event binding to a *Back* button that we Then we wire this method with an event binding to a *Back* button that we
add to the bottom of the component template. add to the bottom of the component template.
Modifying the template to add this button spurs us to take one more Modifying the template to add this button spurs us to take one more
@ -352,7 +352,7 @@ with `<a>` tags. The opening `<a>` tag looks like this:
Notice the `[routerLink]` binding. Notice the `[routerLink]` binding.
Top level navigation in the [`AppComponent` Top level navigation in the [`AppComponent`
template](#router-links) has router links set to fixed !{_pathVsName}s of the template](tutorial/toh-pt5#router-links) has router links set to fixed !{_pathVsName}s of the
destination routes, "/dashboard" and "/heroes". destination routes, "/dashboard" and "/heroes".
This time, we're binding to an expression containing a **link parameters !{_array}**. This time, we're binding to an expression containing a **link parameters !{_array}**.
@ -405,7 +405,7 @@ that we slipped into the interpolation binding. Look for it right after the pipe
Pipes are a good way to format strings, currency amounts, dates and other display data. Pipes are a good way to format strings, currency amounts, dates and other display data.
Angular ships with several pipes and we can write our own. Angular ships with several pipes and we can write our own.
Learn about pipes in the [Pipes](../guide/pipes.html) chapter. Learn about pipes in the [Pipes](guide/pipes) chapter.
### Move content out of the component file ### Move content out of the component file
We are not done. We still have to update the component class to support navigation to the We are not done. We still have to update the component class to support navigation to the
@ -490,10 +490,10 @@ It's pretty easy to package it all up and re-use the component somewhere else.
We can also create styles at the *application level* outside of any component. We can also create styles at the *application level* outside of any component.
Our designers provided some basic styles to apply to elements across the entire app. Our designers provided some basic styles to apply to elements across the entire app.
These correspond to the full set of master styles that we installed earlier during [setup](../guide/setup.html). These correspond to the full set of master styles that we installed earlier during [setup](guide/setup).
Here is an excerpt: Here is an excerpt:
Create the file <span ngio-ex>styles.css</span>, if it doesn't exist already. Create the file <span ngio-ex>styles.css</span>, if it doesn't exist already.
Ensure that it contains the [master styles given here](!{styles_css}). Ensure that it contains the [master styles given here](tutorial/!{styles_css}).
If necessary, also edit <span ngio-ex>index.html</span> to refer to this stylesheet. If necessary, also edit <span ngio-ex>index.html</span> to refer to this stylesheet.
Look at the app now. Our dashboard, heroes, and navigation links are styling! Look at the app now. Our dashboard, heroes, and navigation links are styling!

4
aio/content/tutorial/toh-pt6.md
View File

@ -15,7 +15,7 @@ Run the <live-example></live-example> for this part.
## Where We Left Off ## Where We Left Off
In the [previous chapter](toh-pt5.html), we learned to navigate between the dashboard and the fixed heroes list, editing a selected hero along the way. In the [previous chapter](tutorial/toh-pt5), we learned to navigate between the dashboard and the fixed heroes list, editing a selected hero along the way.
That's our starting point for this chapter. That's our starting point for this chapter.
The application runs and updates automatically as we continue to build the Tour of Heroes. The application runs and updates automatically as we continue to build the Tour of Heroes.
@ -289,5 +289,5 @@ Here are the files we _added or changed_ in this chapter.
### Next Step ### Next Step
Return to the [learning path](../guide/learning-angular.html#architecture) where Return to the [learning path](guide/learning-angular) where
you can read about the concepts and practices you discovered in this tutorial. you can read about the concepts and practices you discovered in this tutorial.