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

docs(glossary): general cleanup and fix links (#2100) 

* glossary: replace cached by latest before edits

* docs(glossary): general cleanup and fix links

This commit addresses issues with the glossary for all languages (JS, TS, Dart).

Fixes #1123, #1838, #2036.

This was originally started as post-RC5 Dart resync, but since mixing Harp partials with Jade mixins can be problematic, this commit does a general cleanup of the 3 x 2 = 6 glossary files (found in `{ts,js,dart}/latest/{.,guide}`).

This commit builds upon #2098 (which created the first `ts/_cache` copy of the glossary), but doesn't really depend on it.

* post-review updates

* post-review updates
This commit is contained in:
Patrice Chalin 2016-08-17 17:50:42 -07:00 committed by Kathy Walrath
parent ed37bb4835
commit 08dec19447
7 changed files with 770 additions and 689 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
public/docs/dart/latest/glossary.jade
View File

@ -1,35 +1,68 @@
include _util-fns extends ../../ts/_cache/glossary.jade
block var-def block includes
- var fragPath='../../ts/latest/_fragments/'; include _util-fns
!=partial(fragPath + 'glossary-intro') block annotation-defn
!=partial(fragPath + 'glossary-a1')
!=partial(fragPath + 'glossary-a-2')
!=partial(fragPath + 'glossary-b-c')
!=partial(fragPath + 'glossary-d1')
!=partial(fragPath + 'glossary-d2')
!=partial(fragPath + 'glossary-e1')
!=partial(fragPath + 'glossary-e2')
!=partial(fragPath + 'glossary-f-l')
!=partial(fragPath + 'glossary-m1')
//partial(fragPath + 'glossary-m2') not needed in dart
!=partial(fragPath + 'glossary-n-s-1')
:marked
## snake_case
.l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word is separated by an When unqualified, _annotation_ refers to a Dart [metadata
underscore (`_`). annotation][metadata] (as opposed to, say, a type annotation). A metadata
annotation begins with the character `@`, followed by either a reference
Library and file names are often spelled in snake_case. Examples include: to a compile-time constant (such as [`Component`](#component)) or a call
`angular2_tour_of_heroes` and `app_component.dart`. to a constant constructor. See the [Dart Language Guide][metadata] for
details.
This form is also known as **underscore case**.
!=partial(fragPath + 'glossary-n-s-2') The corresponding term in TypeScript and JavaScript is
!=partial(fragPath + 'glossary-t1') [_decorator_](!{docsPath}/ts/latest/glossary.html#decorator).
//partial(fragPath + 'glossary-t2') notneeded in dart
!=partial(fragPath + 'glossary-u-z') [metadata]: https://www.dartlang.org/guides/language/language-tour#metadata
block bootstrap-defn-top
:marked
We launch an Angular application by "bootstrapping" it with the
[bootstrap][bootstrap] method. The `bootstrap` method identifies an
application's top level "root" [Component](#component) and optionally
registers service [providers](#provider) with the [dependency injection
system](#dependency-injection).
[bootstrap]: !{docsLatest}/api/angular2.platform.browser/bootstrap.html
block decorator-defn
:marked
When used in this guide, these JavaScript terms are taken as synonymous with
[annotation](#annotation).
block module-defn
//- Taken from the Dart Difference in guide/architecture.jade
:marked
In this guide, the term _module_ refers to a Dart compilation unit, such
as a library, or a package. (If a Dart file has no `library` or `part`
directive, then that file itself is a library and thus a compilation
unit.) For more information about compilation units, see
the chapter on "Libraries and Scripts" in the
[Dart Language Specification](https://www.dartlang.org/docs/spec/).
block routing-component-defn
:marked
A [Component](#component) with an attached router.
In most cases, the component became attached to a [router](#router) by means
of a `@RouterConfig` #{decorator} that defined routes to views controlled by this component.
The component's template has a `RouterOutlet` element where it can display views produced by the router.
It likely has anchor tags or buttons with `RouterLink` directives that users can click to navigate.
block append snake-case-defn
:marked
Library and file names are often spelled in snake_case. Examples include:
`angular2_tour_of_heroes` and `app_component.dart`.
block zone-defn
:marked
Zones are a mechanism for encapsulating and intercepting
a Dart application's asynchronous activity.
To learn more, consult the [zones article][zones].
[zones]: https://www.dartlang.org/articles/libraries/zones

2
public/docs/dart/latest/guide/glossary.jade
View File

@ -1,4 +1,4 @@
extends ../glossary extends ../glossary
block var-def block var-def
- var fragPath='../../../ts/latest/_fragments/'; include ../_util-fns

37
public/docs/js/latest/glossary.jade
View File

@ -1,35 +1,4 @@
include _util-fns extends ../../ts/latest/glossary.jade
// From ts/glossary.jade, the folder ts/latest/_fragments is generated which contains a bunch of partial files.
// These partials comprise the glossary,a subset of these partials should be used to generate the glossary for
// __javascript__ under BASICS.
!=partial('../../ts/latest/_fragments/glossary-intro')
//!=partial('../../ts/latest/_fragments/glossary-a-1') not needed in javascript
!=partial('../../ts/latest/_fragments/glossary-a-2')
!=partial('../../ts/latest/_fragments/glossary-b-c')
!=partial('../../ts/latest/_fragments/glossary-d1')
!=partial('../../ts/latest/_fragments/glossary-d2')
!=partial('../../ts/latest/_fragments/glossary-e1')
!=partial('../../ts/latest/_fragments/glossary-e2')
!=partial('../../ts/latest/_fragments/glossary-f-l')
!=partial('../../ts/latest/_fragments/glossary-m1')
!=partial('../../ts/latest/_fragments/glossary-m2')
!=partial('../../ts/latest/_fragments/glossary-n-s')
!=partial('../../ts/latest/_fragments/glossary-t1')
!=partial('../../ts/latest/_fragments/glossary-t2')
!=partial('../../ts/latest/_fragments/glossary-u-z')
// NOTE: (ericjim): I am almost certain these lines are doing nothing, block includes
// so instead I use `!=partial` to include the glossary fragments. include _util-fns
//+includeShared('{ts}', 'intro')
//+includeShared('{ts}', 'a2')
//+includeShared('{ts}', 'b-c')
//+includeShared('{ts}', 'd1')
//+includeShared('{ts}', 'd2')
//+includeShared('{ts}', 'e1')
//+includeShared('{ts}', 'e2')
//+includeShared('{ts}', 'f-l')
//+includeShared('{ts}', 'm1')
//+includeShared('{ts}', 'n-s')
//+includeShared('{ts}', 't1')
//+includeShared('{ts}', 't2')
//+includeShared('{ts}', 'u-z')

5
public/docs/js/latest/guide/glossary.jade
View File

@ -1 +1,4 @@
!= partial("../glossary") extends ../glossary
block var-def
include ../_util-fns

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

@ -1,6 +1,13 @@
include _util-fns block includes
include _util-fns
//- current.path = ['docs', lang, 'latest', ...]
- var lang = current.path[1]
- var docsPath='/' + current.path[0]
- var docsLatest='/' + current.path.slice(0,3).join('/');
- var _at = lang === 'js' ? '' : '@'
- var _decoratorLink = '<a href="#' + _decorator + '">' + _decorator + '</a>'
// #docregion intro
:marked :marked
# Angular 2 Glossary # Angular 2 Glossary
@ -15,19 +22,41 @@ include _util-fns
[A](#A) [B](#B) [C](#C) [D](#D) [E](#E) [F](#F) [G](#G) [H](#H) [I](#I) [A](#A) [B](#B) [C](#C) [D](#D) [E](#E) [F](#F) [G](#G) [H](#H) [I](#I)
[J](#J) [K](#K) [L](#L) [M](#M) [N](#N) [O](#O) [P](#P) [Q](#Q) [R](#R) [J](#J) [K](#K) [L](#L) [M](#M) [N](#N) [O](#O) [P](#P) [Q](#Q) [R](#R)
[S](#S) [T](#T) [U](#U) [V](#V) [W](#W) [X](#X) [Y](#Y) [Z](#Z) [S](#S) [T](#T) [U](#U) [V](#V) [W](#W) [X](#X) [Y](#Y) [Z](#Z)
// #enddocregion intro
// #docregion a1 .l-main-section#A
<a id="A"></a>
// #enddocregion a1 +ifDocsFor('ts')
.l-main-section a#aot
:marked
## Annotation
.l-sub-section
:marked :marked
In practice a synonym for [Decoration](#decorator). ## Ahead of Time (AOT) Compilation
// #enddocregion a-1 .l-sub-section
// #docregion a-2 :marked
Angular applications can be compiled by developers at build-time.
By compiling your application using the compiler-cli, `ngc`, you can boostrap directly
to a Module Factory, meaning you don't need to include the Angular compiler in your javascript bundle.
Ahead of Time compiled applications also benefit from decreased load time and increased performance.
:marked
## Angular Module
.l-sub-section
:marked
Helps us organize an application into cohesive blocks of functionality.
An Angular module identifies the components, directives, and pipes that are used by the application
along with the list of external Angular modules that the application needs, such as `FormsModule`.
Every Angular application has an application root module class. By convention the class is
called `AppModule` and resides in a file named `app.component.ts`.
See the [Angular Module](!{docsLatest}/guide/ngmodule.html) chapter for details and examples.
+ifDocsFor('ts|dart')
:marked
## Annotation
.l-sub-section
block annotation-defn
:marked
In practice, a synonym for [Decoration](#decorator).
:marked :marked
## Attribute Directive ## Attribute Directive
.l-sub-section .l-sub-section
@ -38,54 +67,53 @@ include _util-fns
The `ngClass` directive for adding and removing CSS class names is a good example of The `ngClass` directive for adding and removing CSS class names is a good example of
an Attribute Directive. an Attribute Directive.
// #enddocregion a-2
// #docregion b-c .l-main-section#B
- var lang = current.path[1]
- var decorator = lang === 'dart' ? 'annotation' : '<a href="#decorator">decorator</a>' +ifDocsFor('ts|js')
- var atSym = lang === 'js' ? '' : '@'
<a id="B"></a>
.l-main-section
:marked
## Barrel
.l-sub-section
:marked :marked
A barrel is a way to *rollup exports* from several modules into a single convenience module. ## Barrel
The barrel itself is a module file that re-exports *selected* exports of other modules. .l-sub-section
:marked
Imagine three modules in a `heroes` folder: A barrel is a way to *rollup exports* from several ES2015 modules into a single convenience ES2015 module.
code-example. The barrel itself is an ES2015 module file that re-exports *selected* exports of other ES2015 modules.
// heroes/hero.component.ts
export class HeroComponent {} Imagine three ES2015 modules in a `heroes` folder:
code-example.
// heroes/hero.model.ts // heroes/hero.component.ts
export class Hero {} export class HeroComponent {}
// heroes/hero.service.ts // heroes/hero.model.ts
export class HeroService {} export class Hero {}
:marked
Without a barrel, a consumer would need three import statements: // heroes/hero.service.ts
code-example. export class HeroService {}
import { HeroComponent } from '../heroes/hero.component.ts'; :marked
import { Hero } from '../heroes/hero.model.ts'; Without a barrel, a consumer would need three import statements:
import { HeroService } from '../heroes/hero.service.ts'; code-example.
:marked import { HeroComponent } from '../heroes/hero.component.ts';
We can add a barrel to the `heroes` folder (called `index` by convention) that exports all of these items: import { Hero } from '../heroes/hero.model.ts';
code-example. import { HeroService } from '../heroes/hero.service.ts';
export * from './hero.model.ts'; // re-export all of its exports :marked
export * from './hero.service.ts'; // re-export all of its exports We can add a barrel to the `heroes` folder (called `index` by convention) that exports all of these items:
export { HeroComponent } from './hero.component.ts'; // re-export the named thing code-example.
:marked export * from './hero.model.ts'; // re-export all of its exports
Now a consumer can import what it needs from the barrel. export * from './hero.service.ts'; // re-export all of its exports
code-example. export { HeroComponent } from './hero.component.ts'; // re-export the named thing
import { Hero, HeroService } from '../heroes'; // index is implied :marked
:marked Now a consumer can import what it needs from the barrel.
The Angular [scoped packages](#scoped-package) each have a barrel named `index`. code-example.
// #enddocregion b-c import { Hero, HeroService } from '../heroes'; // index is implied
:marked :marked
That's why we can write this: The Angular [scoped packages](#scoped-package) each have a barrel named `index`.
+makeExcerpt('quickstart/ts/app/app.component.ts', 'import', '')
// #docregion b-c That's why we can write this:
+makeExcerpt('quickstart/ts/app/app.component.ts', 'import', '')
.alert.is-important
:marked
Note that you can often achieve this same goal using [Angular modules](#angular-module) instead.
:marked :marked
## Binding ## Binding
@ -101,25 +129,24 @@ include _util-fns
:marked :marked
## Bootstrap ## Bootstrap
.l-sub-section .l-sub-section
block bootstrap-defn-top
:marked
We launch an Angular application by "bootstrapping" it using the application root Angular module (`AppModule`).
The bootstraping identifies an application's top level "root" [Component](#component), which is the first
component that is loaded for the application. For more information see the [QuickStart](!{docsLatest}/quickstart.html).
:marked :marked
We launch an Angular application by "bootstrapping" it with the `bootstrap` method.
The `bootstrap` method identifies an application's top level "root" [Component](#component)
and optionally registers service [providers](#provider) with the
[dependency injection system](#dependency-injection).
One can bootstrap multiple apps in the same `index.html`, each with its own top level root. One can bootstrap multiple apps in the same `index.html`, each with its own top level root.
<a id="C"></a> .l-main-section#C
.l-main-section
:marked :marked
## camelCase ## camelCase
.l-sub-section .l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter
_except the first letter which is a lowercase letter_. _except the first letter which is a lowercase letter_.
Function, property, and method names are typically spelled in camelCase. Examples include: `square`, `firstName` and `getHeroes`. Function, property, and method names are typically spelled in camelCase. Examples include: `square`, `firstName` and `getHeroes`.
This form is also known as **lower camel case**, to distinguish it from **upper camel case** which we call [PascalCase](#pascalcase). This form is also known as **lower camel case**, to distinguish it from **upper camel case** which we call [PascalCase](#pascalcase).
When we write "camelCase" in this documentation we always mean *lower camel case*. When we write "camelCase" in this documentation we always mean *lower camel case*.
@ -134,28 +161,26 @@ include _util-fns
The Component is one of the most important building blocks in the Angular system. The Component is one of the most important building blocks in the Angular system.
It is, in fact, an Angular [Directive](#directive) with a companion [Template](#template). It is, in fact, an Angular [Directive](#directive) with a companion [Template](#template).
The developer applies the `#{atSym}Component` !{decorator} to The developer applies the `!{_at}Component` !{_decoratorLink} to
the component class, thereby attaching to the class the essential component metadata the component class, thereby attaching to the class the essential component metadata
that Angular needs to create a component instance and render it with its template that Angular needs to create a component instance and render it with its template
as a view. as a view.
Those familiar with "MVC" and "MVVM" patterns will recognize Those familiar with "MVC" and "MVVM" patterns will recognize
the Component in the role of "Controller" or "View Model". the Component in the role of "Controller" or "View Model".
// #enddocregion b-c
// #docregion d1 .l-main-section#D
<a id="D"></a>
.l-main-section
:marked :marked
## dash-case ## dash-case
.l-sub-section .l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`). The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`).
Directive selectors and the root of filenames are often spelled in dash-case. Examples include: `my-app` and `hero-list.component.ts`.
This form is also known as [kebab-case](#kebab-case). This form is also known as [kebab-case](#kebab-case).
[Directive](#directive) selectors (like `my-app`) <span if-docs="ts">and
the root of filenames (such as `hero-list.component.ts`)</span> are often
spelled in dash-case.
:marked :marked
## Data Binding ## Data Binding
.l-sub-section .l-sub-section
@ -176,52 +201,53 @@ include _util-fns
operations and supporting declaration syntax. operations and supporting declaration syntax.
The many forms of binding include: The many forms of binding include:
* [Interpolation](/docs/ts/latest/guide/template-syntax.html#interpolation) * [Interpolation](!{docsLatest}/guide/template-syntax.html#interpolation)
* [Property Binding](/docs/ts/latest/guide/template-syntax.html#property-binding) * [Property Binding](!{docsLatest}/guide/template-syntax.html#property-binding)
* [Event Binding](/docs/ts/latest/guide/template-syntax.html#event-binding) * [Event Binding](!{docsLatest}/guide/template-syntax.html#event-binding)
* [Attribute Binding](/docs/ts/latest/guide/template-syntax.html#attribute-binding) * [Attribute Binding](!{docsLatest}/guide/template-syntax.html#attribute-binding)
* [Class Binding](/docs/ts/latest/guide/template-syntax.html#class-binding) * [Class Binding](!{docsLatest}/guide/template-syntax.html#class-binding)
* [Style Binding](/docs/ts/latest/guide/template-syntax.html#style-binding) * [Style Binding](!{docsLatest}/guide/template-syntax.html#style-binding)
* [Two-way data binding with ngModel](/docs/ts/latest/guide/template-syntax.html#ng-model) * [Two-way data binding with ngModel](!{docsLatest}/guide/template-syntax.html#ng-model)
Learn more about data binding in the Learn more about data binding in the
[Template Syntax](/docs/ts/latest/guide/template-syntax.html#data-binding) chapter. [Template Syntax](!{docsLatest}/guide/template-syntax.html#data-binding) chapter.
// #enddocregion d1 +ifDocsFor('ts|dart')
<a id="decorator"></a> <a id="decoration"></a> a#decorator
:marked a#decoration
## Decorator | Decoration
.l-sub-section
:marked :marked
A Decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments. ## Decorator | Decoration
.l-sub-section
block decorator-defn
:marked
A Decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments.
Decorators are a JavaScript language [feature](https://github.com/wycats/javascript-decorators), implemented in TypeScript and proposed for ES2016 (AKA ES7). Decorators are a JavaScript language [feature](https://github.com/wycats/javascript-decorators), implemented in TypeScript and proposed for ES2016 (AKA ES7).
We apply a decorator by positioning it We apply a decorator by positioning it
immediately above or to the left of the thing it decorates. immediately above or to the left of the thing it decorates.
Angular has its own set of decorators to help it interoperate with our application parts. Angular has its own set of decorators to help it interoperate with our application parts.
Here is an example of a `@Component` decorator that identifies a Here is an example of a `@Component` decorator that identifies a
class as an Angular [Component](#component) and an `@Input` decorator applied to a property class as an Angular [Component](#component) and an `@Input` decorator applied to a property
of that component. of that component.
The elided object argument to the `@Component` decorator would contain the pertinent component metadata. The elided object argument to the `@Component` decorator would contain the pertinent component metadata.
``` ```
@Component({...}) @Component({...})
export class AppComponent { export class AppComponent {
constructor(@Inject('SpecialFoo') public foo:Foo) {} constructor(@Inject('SpecialFoo') public foo:Foo) {}
@Input() name:string; @Input() name:string;
} }
``` ```
The scope of a decorator is limited to the language feature The scope of a decorator is limited to the language feature
that it decorates. None of the decorations shown here will "leak" to other that it decorates. None of the decorations shown here will "leak" to other
classes appearing below it in the file. classes appearing below it in the file.
.alert.is-important .alert.is-important
:marked :marked
Always include the parentheses `()` when applying a decorator. Always include the parentheses `()` when applying a decorator.
A decorator is a **function** that must be called when applied. A decorator is a **function** that must be called when applied.
// #docregion d2
:marked :marked
## Dependency Injection ## Dependency Injection
.l-sub-section .l-sub-section
@ -271,11 +297,9 @@ include _util-fns
Registering providers is a critical preparatory step. Registering providers is a critical preparatory step.
Angular registers some of its own providers with every injector. Angular registers some of its own providers with every injector.
We can register our own providers. Quite often the best time to register a `Provider` We can register our own providers.
is when we [bootstrap](#bootstrap) the application.
There are other opportunities to register as well.
Learn more in the [Dependency Injection](/docs/ts/latest/guide/dependency-injection.html) chapter. Learn more in the [Dependency Injection](!{docsLatest}/guide/dependency-injection.html) chapter.
:marked :marked
## Directive ## Directive
.l-sub-section .l-sub-section
@ -308,13 +332,9 @@ include _util-fns
1. [Structural Directives](#structural-directive), a directive responsible for 1. [Structural Directives](#structural-directive), a directive responsible for
shaping or re-shaping HTML layout, typically by adding, removing, or manipulating shaping or re-shaping HTML layout, typically by adding, removing, or manipulating
elements and their children. elements and their children.
// #enddocregion d2
// #docregion e1 .l-main-section#E
<a id="E"></a>
// #enddocregion e1
// #docregion e2
.l-main-section
:marked :marked
## ECMAScript ## ECMAScript
.l-sub-section .l-sub-section
@ -322,23 +342,17 @@ include _util-fns
The [official JavaScript language specification](https://en.wikipedia.org/wiki/ECMAScript). The [official JavaScript language specification](https://en.wikipedia.org/wiki/ECMAScript).
The latest approved version of JavaScript is The latest approved version of JavaScript is
[ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/) [ECMAScript 2016](http://www.ecma-international.org/ecma-262/7.0/)
(AKA "ES2015" or "ES6") and many Angular 2 developers will write their applications (AKA "ES2016" or "ES7") and many Angular 2 developers will write their applications
either in this version of the language or a dialect that strives to be either in this version of the language or a dialect that strives to be
compatible with it such as [TypeScript](#typesScript). compatible with it such as [TypeScript](#typesScript).
Most modern browsers today only support the prior "ECMAScript 5" (AKA ES5) standard. Most modern browsers today only support the much older "ECMAScript 5" (AKA ES5) standard.
Applications written in ES2015 or one of its dialects must be "[transpiled](#transpile)" Applications written in ES2016, ES2015 or one of their dialects must be "[transpiled](#transpile)"
to ES5 JavaScript. to ES5 JavaScript.
Angular 2 developers may choose to write in ES5 directly. Angular 2 developers may choose to write in ES5 directly.
:marked
## ECMAScript 2015
.l-sub-section
:marked
The latest released version of JavaScript,
[ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/)
(AKA "ES2015" or "ES6")
:marked :marked
## ES2015 ## ES2015
.l-sub-section .l-sub-section
@ -355,14 +369,11 @@ include _util-fns
:marked :marked
Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers. Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers.
See [ECMAScript](#ecmascript). See [ECMAScript](#ecmascript).
// #enddocregion e2
// #docregion f-l a#F
<a id="F"></a> a#G
<a id="G"></a> a#H
<a id="H"></a> .l-main-section#I
<a id="I"></a>
.l-main-section
:marked :marked
## Injector ## Injector
.l-sub-section .l-sub-section
@ -376,11 +387,11 @@ include _util-fns
.l-sub-section .l-sub-section
:marked :marked
A directive property that can be the ***target*** of a A directive property that can be the ***target*** of a
[Property Binding](/docs/ts/latest/guide/template-syntax.html#property-binding). [Property Binding](!{docsLatest}/guide/template-syntax.html#property-binding).
Data values flow *into* this property from the data source identified Data values flow *into* this property from the data source identified
in the template expression to the right of the equal sign. in the template expression to the right of the equal sign.
See the [Template Syntax](/docs/ts/latest/guide/template-syntax.html#inputs-outputs) chapter. See the [Template Syntax](!{docsLatest}/guide/template-syntax.html#inputs-outputs) chapter.
:marked :marked
## Interpolation ## Interpolation
@ -397,25 +408,28 @@ include _util-fns
:marked :marked
Learn more about interpolation in the Learn more about interpolation in the
[Template Syntax](/docs/ts/latest/guide/template-syntax.html#interpolation) chapter. [Template Syntax](!{docsLatest}/guide/template-syntax.html#interpolation) chapter.
.l-main-section#J
<a id="J"></a> +ifDocsFor('ts')
a#jit
:marked
## Just in Time (JIT) Compilation
.l-sub-section
:marked
With Angular _Just in Time_ bootstrapping you compile your components and modules in the browser
and launch the application dynamically. This is a good choice during development.
Consider the [Ahead of Time](#aot) mode for production apps.
.l-main-section .l-main-section#K
<a id="K"></a>
:marked :marked
## kebab-case ## kebab-case
.l-sub-section .l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`). See [dash-case](#dash-case).
Directive selectors and the root of filenames are often spelled in kebab-case. Examples include: `my-app` and `hero-list.component.ts`.
This form is also known as [dash-case](#dash-case).
<a id="L"></a> .l-main-section#L
.l-main-section
:marked :marked
## Lifecycle Hooks ## Lifecycle Hooks
.l-sub-section .l-sub-section
@ -439,74 +453,84 @@ include _util-fns
* `ngAfterViewChecked` - after every check of a component's view(s) * `ngAfterViewChecked` - after every check of a component's view(s)
* `ngOnDestroy` - just before the directive is destroyed. * `ngOnDestroy` - just before the directive is destroyed.
Learn more in the [Lifecycle Hooks](/docs/ts/latest/guide/lifecycle-hooks.html) chapter. Learn more in the [Lifecycle Hooks](!{docsLatest}/guide/lifecycle-hooks.html) chapter.
// #enddocregion f-l
.l-main-section#M
// #docregion m1
<a id="M"></a>
// #enddocregion m1
// #docregion m2
.l-main-section
:marked :marked
## Module ## Module
.l-sub-section .l-sub-section
block module-defn
.alert.is-important
:marked
In Angular, there are two types of modules:
- [Angular modules](#angular-module).
See the [Angular Module](!{docsLatest}/guide/ngmodule.html) chapter for details and examples.
- ES2015 modules as described in this section.
:marked
Angular apps are modular.
In general, we assemble our application from many modules, both the ones we write ourselves
and the ones we acquire from others.
A typical module is a cohesive block of code dedicated to a single purpose.
A module **exports** something of value in that code, typically one thing such as a class.
A module that needs that thing, **imports** it.
The structure of Angular modules and the import/export syntax
is based on the [ES2015](#es2015) module standard
described [here](http://www.2ality.com/2014/09/es6-modules-final.html).
An application that adheres to this standard requires a module loader to
load modules on request and resolve inter-module dependencies.
Angular does not ship with a module loader and does not have a preference
for any particular 3rd party library (although most samples use SystemJS).
Application developers may pick any module library that conforms to the standard
Modules are typically named after the file in which the exported thing is defined.
The Angular [DatePipe](https://github.com/angular/angular/blob/master/modules/@angular/common/src/pipes/date_pipe.ts)
class belongs to a feature module named `date_pipe` in the file `date_pipe.ts`.
Developers rarely access Angular feature modules directly.
We usually import them from one of the Angular [scoped packages](#scoped-package) such as `@angular/core`.
a#N
.l-main-section#O
+ifDocsFor('ts|js')
:marked :marked
Angular apps are modular. ## Observable
.l-sub-section
:marked
We can think of an observable as an array whose items arrive asynchronously over time.
Observables help us manage asynchronous data, such as data coming from a backend service.
Observables are used within Angular itself, including Angular's event system and its http client service.
In general, we assemble our application from many modules, both the ones we write ourselves To use observables, Angular uses a third-party library called Reactive Extensions (RxJS).
and the ones we acquire from others. Observables are a proposed feature for ES 2016, the next version of JavaScript.
A typical module is a cohesive block of code dedicated to a single purpose.
A module **exports** something of value in that code, typically one thing such as a class.
A module that needs that thing, **imports** it.
The structure of Angular modules and the import/export syntax
is based on the [ES2015](#es2015) module standard
described [here](http://www.2ality.com/2014/09/es6-modules-final.html).
An application that adheres to this standard requires a module loader to
load modules on request and resolve inter-module dependencies.
Angular does not ship with a module loader and does not have a preference
for any particular 3rd party library (although most samples use SystemJS).
Application developers may pick any module library that conforms to the standard
Modules are typically named after the file in which the exported thing is defined.
The Angular [DatePipe](https://github.com/angular/angular/blob/master/modules/@angular/common/src/pipes/date_pipe.ts)
class belongs to a feature module named `date_pipe` in the file `date_pipe.ts`.
Developers rarely access Angular feature modules directly.
We usually import them from one of the Angular [scoped packages](#scoped-package) such as `@angular/core`.
// #enddocregion m2
// #docregion n-s-1
- var lang = current.path[1]
- var decorator = lang === 'dart' ? 'annotation' : '<a href="#decorator">decorator</a>'
- var atSym = lang === 'js' ? '' : '@'
<a id="N"></a>
<a id="O"></a>
.l-main-section
:marked :marked
## Output ## Output
.l-sub-section .l-sub-section
:marked :marked
A directive property that can be the ***target*** of an A directive property that can be the ***target*** of an
[Event Binding](/docs/ts/latest/guide/template-syntax.html#property-binding). [Event Binding](!{docsLatest}/guide/template-syntax.html#property-binding).
Events stream *out* of this property to the receiver identified Events stream *out* of this property to the receiver identified
in the template expression to the right of the equal sign. in the template expression to the right of the equal sign.
See the [Template Syntax](/docs/ts/latest/guide/template-syntax.html#inputs-outputs) chapter. See the [Template Syntax](!{docsLatest}/guide/template-syntax.html#inputs-outputs) chapter.
.l-main-section#P
.l-main-section
<a id="P"></a>
:marked :marked
## PascalCase ## PascalCase
.l-sub-section .l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter. The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter.
Class names are typically spelled in PascalCase. Examples include: `Person` and `Customer`. Class names are typically spelled in PascalCase. Examples include: `Person` and `HeroDetailComponent`.
This form is also known as **upper camel case**, to distinguish it from **lower camel case** which we simply call [camelCase](#camelcase). This form is also known as **upper camel case**, to distinguish it from **lower camel case** which we simply call [camelCase](#camelcase).
In this documentation, "PascalCase" means *upper camel case* and "camelCase" means *lower camel case*. In this documentation, "PascalCase" means *upper camel case* and "camelCase" means *lower camel case*.
@ -515,8 +539,8 @@ include _util-fns
.l-sub-section .l-sub-section
:marked :marked
An Angular pipe is a function that transforms input values to output values for An Angular pipe is a function that transforms input values to output values for
display in a [view](#view). We use the `#{atSym}Pipe` !{decorator} display in a [view](#view). We use the `!{_at}Pipe` !{_decoratorLink}
to associate the pipe function with a name. We then can use that to associate the pipe function with a name. We can then use that
name in our HTML to declaratively transform values on screen. name in our HTML to declaratively transform values on screen.
Here's an example that uses the built-in `currency` pipe to display Here's an example that uses the built-in `currency` pipe to display
@ -525,24 +549,38 @@ include _util-fns
code-example(language="html" escape="html"). code-example(language="html" escape="html").
<label>Price: </label>{{product.price | currency}} <label>Price: </label>{{product.price | currency}}
:marked :marked
Learn more in the chapter on [pipes](/docs/ts/latest/guide/pipes.html) . Learn more in the chapter on [pipes](!{docsLatest}/guide/pipes.html) .
- var _ProviderUrl = docsLatest+'/api/'+(lang == 'dart' ? 'angular2.core' : 'core/index')+'/Provider-class.html'
:marked :marked
## Provider ## Provider
.l-sub-section .l-sub-section
:marked :marked
A Provider creates a new instance of a dependency for the Dependency Injection system. A [Provider](!{_ProviderUrl}) creates a new instance of a dependency for the
It relates a lookup token to code - sometimes called a "recipe" - that can create a dependency value. [Dependency Injection](#dependency-injection) system.
It relates a lookup token to code &mdash; sometimes called a "recipe" &mdash;
that can create a dependency value.
For example, `new Provider(Foo, {useClass: Foo})` creates a `Provider` a#Q
that relates the `Foo` token to a function that creates a new instance of the `Foo` class. .l-main-section#R
There are other ways to create tokens and recipes. +ifDocsFor('ts|js')
See [Dependency Injection](#dependency-injection) chapter to learn more. :marked
## Reactive Forms
.l-sub-section
:marked
A technique for building Angular forms through code in a component.
The alternate technique is [Template-Driven Forms](#template-driven-forms).
When building reactive forms:
- The "source of truth" is the component. The validation is defined using code in the component.
- Each control is explicitly created in the component class with `new FormControl()` or with `FormBuilder`.
- The template input elements do *not* use `ngModel`.
- The associated Angular directives are all prefixed with `Form` such as `FormGroup`, `FormControl`, and `FormControlName`.
Reactive forms are powerful, flexible, and great for more complex data entry form scenarios, such as dynamic generation
of form controls.
.l-main-section
<a id="Q"></a>
<a id="R"></a>
:marked :marked
## Router ## Router
.l-sub-section .l-sub-section
@ -552,40 +590,84 @@ include _util-fns
and taking other similar actions that cause the application to and taking other similar actions that cause the application to
replace one view with another. replace one view with another.
The Angular [Component Router](/docs/ts/latest/guide/router.html) is a richly featured mechanism for configuring The Angular [Component Router](!{docsLatest}/guide/router.html) is a richly featured mechanism for configuring
and managing the entire view navigation process including the creation and destruction and managing the entire view navigation process including the creation and destruction
of views. of views.
+ifDocsFor('ts|js')
:marked
In most cases, components becomes attached to a [router](#router) by means
of a `RouterConfig` that defines routes to views.
A [routing component's](#routing-component) template has a `RouterOutlet` element
where it can display views produced by the router.
Other views in the application likely have anchor tags or buttons with `RouterLink`
directives that users can click to navigate.
See the [Component Router](!{docsLatest}/guide/router.html) chapter to learn more.
+ifDocsFor('ts|js')
:marked
## RouterModule
.l-sub-section
:marked
A separate [Angular module](#angular-module) that provides the necessary service providers and directives for navigating through application views.
See the [Component Router](!{docsLatest}/guide/router.html) chapter to learn more.
:marked :marked
## Routing Component ## Routing Component
.l-sub-section .l-sub-section
block routing-component-defn
:marked
An Angular [Component](#component) with a RouterOutlet that displays views based on router navigations.
See the [Component Router](!{docsLatest}/guide/router.html) chapter to learn more.
.l-main-section#S
+ifDocsFor('ts|js')
:marked :marked
A [Component](#component) with an attached router. ## Scoped Package
.l-sub-section
:marked
Angular modules are delivered within *scoped packages* such as `@angular/core`, `@angular/common`, `@angular/platform-browser-dynamic`,
`@angular/http`, and `@angular/router`.
In most cases, the component became attached to a [router](#router) by means A [*scoped package*](https://docs.npmjs.com/misc/scope) is a way to group related *npm* packages.
of a `#{atSym}RouterConfig` #{decorator} that defined routes to views controlled by this component.
The component's template has a `RouterOutlet` element where it can display views produced by the router. We import a scoped package the same way we'd import a *normal* package.
The only difference, from a consumer perspective,
is that the package name begins with the Angular *scope name*, `@angular`.
It likely has anchor tags or buttons with `RouterLink` directives that users can click to navigate. +makeExcerpt('architecture/ts/app/app.component.ts', 'import', '')
<a id="S"></a> a#snake-case
.l-main-section
// #enddocregion n-s-1
:marked :marked
## Scoped Package ## snake_case
.l-sub-section
block snake-case-defn
:marked
The practice of writing compound words or phrases such that each word is separated by an
underscore (`_`). This form is also known as **underscore case**.
:marked
## Service
.l-sub-section .l-sub-section
:marked :marked
Angular modules are delivered within *scoped packages* such as `@angular/core`, `@angular/common`, `@angular/platform-browser-dynamic`, Components are great and all, but what do we do with data or logic that are not associated
`@angular/http`, and `@angular/router`. with a specific view or that we want to share across components? We build services!
A [*scoped package*](https://docs.npmjs.com/misc/scope) is a way to group related *npm* packages. Applications often require services such as a hero data service or a logging service.
Our components depend on these services to do the heavy lifting.
We import a scoped package the same way we'd import a *normal* package.
The only difference, from a consumer perspective,
is that the package name begins with the Angular *scope name*, `@angular`.
+makeExcerpt('architecture/ts/app/app.component.ts', 'import', '') A service is a class with a focused purpose.
// #docregion n-s-2 We often create a service to implement features that are
independent from any specific view,
provide share data or logic across components, or encapsulate external interactions.
See the [Services](!{docsLatest}/tutorial/toh-pt4.html) chapter of the tutorial to learn more.
:marked :marked
## Structural Directive ## Structural Directive
@ -597,11 +679,10 @@ include _util-fns
The `ngIf` "conditional element" directive and the `ngFor` "repeater" directive are The `ngIf` "conditional element" directive and the `ngFor` "repeater" directive are
good examples in this category. good examples in this category.
// #enddocregion n-s-2
// #docregion t1 See the [Structural Directives](!{docsLatest}/guide/structural-directives.html) chapter to learn more.
<a id="T"></a>
.l-main-section .l-main-section#T
:marked :marked
## Template ## Template
.l-sub-section .l-sub-section
@ -610,18 +691,36 @@ include _util-fns
the support and continuing guidance of an Angular [Directive](#directive), the support and continuing guidance of an Angular [Directive](#directive),
most notably a [Component](#component). most notably a [Component](#component).
We write templates in a special [Template Syntax](/docs/ts/latest/guide/template-syntax.html). We write templates in a special [Template Syntax](!{docsLatest}/guide/template-syntax.html).
+ifDocsFor('ts|js')
:marked
## Template-Driven Forms
.l-sub-section
:marked
A technique for building Angular forms using HTML forms and input elements in the view.
The alternate technique is [Reactive Forms](#reactive-forms).
When building template-driven forms:
- The "source of truth" is the template. The validation is defined using attributes on the individual input elements.
- [Two-way binding](#data-binding) with `ngModel` keeps the component model in synchronization with the user's entry into the input elements.
- Behind the scenes, Angular creates a new control for each input element that has a `name` attribute and
two-way binding set up.
- The associated Angular directives are all prefixed with `ng` such as `ngForm`, `ngModel`, and `ngModelGroup`.
Template-driven forms are convenient, quick, and simple and are a good choice for many basic data entry form scenarios.
Learn how to build template-driven forms
in the [Forms](!{docsLatest}/guide/forms.html) chapter.
:marked :marked
## Template Expression ## Template Expression
.l-sub-section .l-sub-section
:marked :marked
An expression in a JavaScript-like syntax that Angular evaluates within An expression is a !{_Lang}-like syntax that Angular evaluates within
a [data binding](#data-binding). Learn how to write template expressions a [data binding](#data-binding). Learn how to write template expressions
in the [Template Syntax](/docs/ts/latest/guide/template-syntax.html#template-expressions) chapter. in the [Template Syntax](!{docsLatest}/guide/template-syntax.html#template-expressions) chapter.
// #enddocregion t1
// #docregion t2
:marked :marked
## Transpile ## Transpile
.l-sub-section .l-sub-section
@ -645,15 +744,11 @@ include _util-fns
TypeScript is the preferred language for Angular 2 development although TypeScript is the preferred language for Angular 2 development although
we are welcome to write in other JavaScript dialects such as [ES5](#es5). we are welcome to write in other JavaScript dialects such as [ES5](#es5).
Angular 2 itself is written in TypeScript.
Learn more about TypeScript on its [website](http://www.typescriptlang.org/). Learn more about TypeScript on its [website](http://www.typescriptlang.org/).
// #enddocregion t2
// #docregion u-z a#U
<a id="U"></a> .l-main-section#V
<a id="V"></a>
.l-main-section
:marked :marked
## View ## View
.l-sub-section .l-sub-section
@ -670,31 +765,31 @@ include _util-fns
dynamically as the user navigates through the application, typically dynamically as the user navigates through the application, typically
under the control of a [router](#router). under the control of a [router](#router).
.l-main-section a#W
<a id="W"></a> a#X
<a id="X"></a> a#Y
<a id="Y"></a> .l-main-section#Z
<a id="Z"></a>
:marked :marked
## Zone ## Zone
.l-sub-section .l-sub-section
:marked block zone-defn
Zones are a mechanism for encapsulating and intercepting :marked
a JavaScript application's asynchronous activity. Zones are a mechanism for encapsulating and intercepting
a JavaScript application's asynchronous activity.
The browser DOM and JavaScript have a limited number The browser DOM and JavaScript have a limited number
of asynchronous activities, activities such as DOM events (e.g., clicks), of asynchronous activities, activities such as DOM events (e.g., clicks),
[promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), and [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), and
[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
calls to remote servers. calls to remote servers.
Zones intercept all of these activities and give a "zone client" the opportunity Zones intercept all of these activities and give a "zone client" the opportunity
to take action before and after the async activity completes. to take action before and after the async activity completes.
Angular runs our application in a zone where it can respond to Angular runs our application in a zone where it can respond to
asynchronous events by checking for data changes and updating asynchronous events by checking for data changes and updating
the information it displays via [data binding](#data-binding). the information it displays via [data bindings](#data-binding).
Learn more about zones in this Learn more about zones in this
[Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). [Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U).
// #enddocregion u-z

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

@ -1,6 +1,13 @@
include _util-fns block includes
include _util-fns
//- current.path = ['docs', lang, 'latest', ...]
- var lang = current.path[1]
- var docsPath='/' + current.path[0]
- var docsLatest='/' + current.path.slice(0,3).join('/');
- var _at = lang === 'js' ? '' : '@'
- var _decoratorLink = '<a href="#' + _decorator + '">' + _decorator + '</a>'
// #docregion intro
:marked :marked
# Angular 2 Glossary # Angular 2 Glossary
@ -15,43 +22,41 @@ include _util-fns
[A](#A) [B](#B) [C](#C) [D](#D) [E](#E) [F](#F) [G](#G) [H](#H) [I](#I) [A](#A) [B](#B) [C](#C) [D](#D) [E](#E) [F](#F) [G](#G) [H](#H) [I](#I)
[J](#J) [K](#K) [L](#L) [M](#M) [N](#N) [O](#O) [P](#P) [Q](#Q) [R](#R) [J](#J) [K](#K) [L](#L) [M](#M) [N](#N) [O](#O) [P](#P) [Q](#Q) [R](#R)
[S](#S) [T](#T) [U](#U) [V](#V) [W](#W) [X](#X) [Y](#Y) [Z](#Z) [S](#S) [T](#T) [U](#U) [V](#V) [W](#W) [X](#X) [Y](#Y) [Z](#Z)
// #enddocregion intro
// #docregion a1 .l-main-section#A
<a id="A"></a>
// #enddocregion a1 +ifDocsFor('ts')
a#aot a#aot
.l-main-section
:marked
## Ahead of Time (AOT) Compilation
.l-sub-section
:marked :marked
Angular applications can be compiled by developers at build-time. ## Ahead of Time (AOT) Compilation
By compiling your application using the compiler-cli, `ngc`, you can boostrap directly .l-sub-section
to a Module Factory, meaning you don't need to include the Angular compiler in your javascript bundle. :marked
Ahead of Time compiled applications also benefit from decreased load time and increased performance. Angular applications can be compiled by developers at build-time.
By compiling your application using the compiler-cli, `ngc`, you can boostrap directly
to a Module Factory, meaning you don't need to include the Angular compiler in your javascript bundle.
Ahead of Time compiled applications also benefit from decreased load time and increased performance.
.l-main-section
<a id="angular-module"></a>
:marked
## Angular Module
.l-sub-section
:marked :marked
Helps us organize an application into cohesive blocks of functionality. ## Angular Module
An Angular module identifies the components, directives, and pipes that are used by the application .l-sub-section
along with the list of external Angular modules that the application needs, such as `FormsModule`. :marked
Helps us organize an application into cohesive blocks of functionality.
An Angular module identifies the components, directives, and pipes that are used by the application
along with the list of external Angular modules that the application needs, such as `FormsModule`.
Every Angular application has an application root module class. By convention the class is Every Angular application has an application root module class. By convention the class is
called `AppModule` and resides in a file named `app.component.ts`. called `AppModule` and resides in a file named `app.component.ts`.
See the [Angular Module](/docs/ts/latest/guide/ngmodule.html) chapter for details and examples. See the [Angular Module](!{docsLatest}/guide/ngmodule.html) chapter for details and examples.
:marked
## Annotation +ifDocsFor('ts|dart')
.l-sub-section
:marked :marked
In practice a synonym for [Decoration](#decorator). ## Annotation
// #enddocregion a-1 .l-sub-section
// #docregion a-2 block annotation-defn
:marked
In practice, a synonym for [Decoration](#decorator).
:marked :marked
## Attribute Directive ## Attribute Directive
.l-sub-section .l-sub-section
@ -62,59 +67,53 @@ a#aot
The `ngClass` directive for adding and removing CSS class names is a good example of The `ngClass` directive for adding and removing CSS class names is a good example of
an Attribute Directive. an Attribute Directive.
// #enddocregion a-2
// #docregion b-c .l-main-section#B
- var lang = current.path[1]
- var decorator = lang === 'dart' ? 'annotation' : '<a href="#decorator">decorator</a>'
- var atSym = lang === 'js' ? '' : '@'
<a id="B"></a>
.l-main-section
:marked
## Barrel
.l-sub-section
:marked
A barrel is a way to *rollup exports* from several ES2015 modules into a single convenience ES2015 module.
The barrel itself is an ES2015 module file that re-exports *selected* exports of other ES2015 modules.
Imagine three ES2015 modules in a `heroes` folder:
code-example.
// heroes/hero.component.ts
export class HeroComponent {}
// heroes/hero.model.ts
export class Hero {}
// heroes/hero.service.ts
export class HeroService {}
:marked
Without a barrel, a consumer would need three import statements:
code-example.
import { HeroComponent } from '../heroes/hero.component.ts';
import { Hero } from '../heroes/hero.model.ts';
import { HeroService } from '../heroes/hero.service.ts';
:marked
We can add a barrel to the `heroes` folder (called `index` by convention) that exports all of these items:
code-example.
export * from './hero.model.ts'; // re-export all of its exports
export * from './hero.service.ts'; // re-export all of its exports
export { HeroComponent } from './hero.component.ts'; // re-export the named thing
:marked
Now a consumer can import what it needs from the barrel.
code-example.
import { Hero, HeroService } from '../heroes'; // index is implied
:marked
The Angular [scoped packages](#scoped-package) each have a barrel named `index`.
// #enddocregion b-c +ifDocsFor('ts|js')
:marked
That's why we can write this:
+makeExcerpt('quickstart/ts/app/app.component.ts', 'import', '')
// #docregion b-c
.alert.is-important
:marked :marked
Note that you can often achieve this same goal using [Angular modules](#angular-module) instead. ## Barrel
.l-sub-section
:marked
A barrel is a way to *rollup exports* from several ES2015 modules into a single convenience ES2015 module.
The barrel itself is an ES2015 module file that re-exports *selected* exports of other ES2015 modules.
Imagine three ES2015 modules in a `heroes` folder:
code-example.
// heroes/hero.component.ts
export class HeroComponent {}
// heroes/hero.model.ts
export class Hero {}
// heroes/hero.service.ts
export class HeroService {}
:marked
Without a barrel, a consumer would need three import statements:
code-example.
import { HeroComponent } from '../heroes/hero.component.ts';
import { Hero } from '../heroes/hero.model.ts';
import { HeroService } from '../heroes/hero.service.ts';
:marked
We can add a barrel to the `heroes` folder (called `index` by convention) that exports all of these items:
code-example.
export * from './hero.model.ts'; // re-export all of its exports
export * from './hero.service.ts'; // re-export all of its exports
export { HeroComponent } from './hero.component.ts'; // re-export the named thing
:marked
Now a consumer can import what it needs from the barrel.
code-example.
import { Hero, HeroService } from '../heroes'; // index is implied
:marked
The Angular [scoped packages](#scoped-package) each have a barrel named `index`.
That's why we can write this:
+makeExcerpt('quickstart/ts/app/app.component.ts', 'import', '')
.alert.is-important
:marked
Note that you can often achieve this same goal using [Angular modules](#angular-module) instead.
:marked :marked
## Binding ## Binding
@ -130,24 +129,24 @@ a#aot
:marked :marked
## Bootstrap ## Bootstrap
.l-sub-section .l-sub-section
block bootstrap-defn-top
:marked
We launch an Angular application by "bootstrapping" it using the application root Angular module (`AppModule`).
The bootstraping identifies an application's top level "root" [Component](#component), which is the first
component that is loaded for the application. For more information see the [QuickStart](!{docsLatest}/quickstart.html).
:marked :marked
We launch an Angular application by "bootstrapping" it using the application root Angular module (`AppModule`).
The bootstraping identifies an application's top level "root" [Component](#component), which is the first
component that is loaded for the application. For more information see the [QuickStart](/docs/ts/latest/quickstart.html).
One can bootstrap multiple apps in the same `index.html`, each with its own top level root. One can bootstrap multiple apps in the same `index.html`, each with its own top level root.
<a id="C"></a> .l-main-section#C
.l-main-section
:marked :marked
## camelCase ## camelCase
.l-sub-section .l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter
_except the first letter which is a lowercase letter_. _except the first letter which is a lowercase letter_.
Function, property, and method names are typically spelled in camelCase. Examples include: `square`, `firstName` and `getHeroes`. Function, property, and method names are typically spelled in camelCase. Examples include: `square`, `firstName` and `getHeroes`.
This form is also known as **lower camel case**, to distinguish it from **upper camel case** which we call [PascalCase](#pascalcase). This form is also known as **lower camel case**, to distinguish it from **upper camel case** which we call [PascalCase](#pascalcase).
When we write "camelCase" in this documentation we always mean *lower camel case*. When we write "camelCase" in this documentation we always mean *lower camel case*.
@ -162,28 +161,26 @@ a#aot
The Component is one of the most important building blocks in the Angular system. The Component is one of the most important building blocks in the Angular system.
It is, in fact, an Angular [Directive](#directive) with a companion [Template](#template). It is, in fact, an Angular [Directive](#directive) with a companion [Template](#template).
The developer applies the `#{atSym}Component` !{decorator} to The developer applies the `!{_at}Component` !{_decoratorLink} to
the component class, thereby attaching to the class the essential component metadata the component class, thereby attaching to the class the essential component metadata
that Angular needs to create a component instance and render it with its template that Angular needs to create a component instance and render it with its template
as a view. as a view.
Those familiar with "MVC" and "MVVM" patterns will recognize Those familiar with "MVC" and "MVVM" patterns will recognize
the Component in the role of "Controller" or "View Model". the Component in the role of "Controller" or "View Model".
// #enddocregion b-c
// #docregion d1 .l-main-section#D
<a id="D"></a>
.l-main-section
:marked :marked
## dash-case ## dash-case
.l-sub-section .l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`). The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`).
Directive selectors and the root of filenames are often spelled in dash-case. Examples include: `my-app` and `hero-list.component.ts`.
This form is also known as [kebab-case](#kebab-case). This form is also known as [kebab-case](#kebab-case).
[Directive](#directive) selectors (like `my-app`) <span if-docs="ts">and
the root of filenames (such as `hero-list.component.ts`)</span> are often
spelled in dash-case.
:marked :marked
## Data Binding ## Data Binding
.l-sub-section .l-sub-section
@ -204,52 +201,53 @@ a#aot
operations and supporting declaration syntax. operations and supporting declaration syntax.
The many forms of binding include: The many forms of binding include:
* [Interpolation](/docs/ts/latest/guide/template-syntax.html#interpolation) * [Interpolation](!{docsLatest}/guide/template-syntax.html#interpolation)
* [Property Binding](/docs/ts/latest/guide/template-syntax.html#property-binding) * [Property Binding](!{docsLatest}/guide/template-syntax.html#property-binding)
* [Event Binding](/docs/ts/latest/guide/template-syntax.html#event-binding) * [Event Binding](!{docsLatest}/guide/template-syntax.html#event-binding)
* [Attribute Binding](/docs/ts/latest/guide/template-syntax.html#attribute-binding) * [Attribute Binding](!{docsLatest}/guide/template-syntax.html#attribute-binding)
* [Class Binding](/docs/ts/latest/guide/template-syntax.html#class-binding) * [Class Binding](!{docsLatest}/guide/template-syntax.html#class-binding)
* [Style Binding](/docs/ts/latest/guide/template-syntax.html#style-binding) * [Style Binding](!{docsLatest}/guide/template-syntax.html#style-binding)
* [Two-way data binding with ngModel](/docs/ts/latest/guide/template-syntax.html#ng-model) * [Two-way data binding with ngModel](!{docsLatest}/guide/template-syntax.html#ng-model)
Learn more about data binding in the Learn more about data binding in the
[Template Syntax](/docs/ts/latest/guide/template-syntax.html#data-binding) chapter. [Template Syntax](!{docsLatest}/guide/template-syntax.html#data-binding) chapter.
// #enddocregion d1 +ifDocsFor('ts|dart')
<a id="decorator"></a> <a id="decoration"></a> a#decorator
:marked a#decoration
## Decorator | Decoration
.l-sub-section
:marked :marked
A Decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments. ## Decorator | Decoration
.l-sub-section
block decorator-defn
:marked
A Decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments.
Decorators are a JavaScript language [feature](https://github.com/wycats/javascript-decorators), implemented in TypeScript and proposed for ES2016 (AKA ES7). Decorators are a JavaScript language [feature](https://github.com/wycats/javascript-decorators), implemented in TypeScript and proposed for ES2016 (AKA ES7).
We apply a decorator by positioning it We apply a decorator by positioning it
immediately above or to the left of the thing it decorates. immediately above or to the left of the thing it decorates.
Angular has its own set of decorators to help it interoperate with our application parts. Angular has its own set of decorators to help it interoperate with our application parts.
Here is an example of a `@Component` decorator that identifies a Here is an example of a `@Component` decorator that identifies a
class as an Angular [Component](#component) and an `@Input` decorator applied to a property class as an Angular [Component](#component) and an `@Input` decorator applied to a property
of that component. of that component.
The elided object argument to the `@Component` decorator would contain the pertinent component metadata. The elided object argument to the `@Component` decorator would contain the pertinent component metadata.
``` ```
@Component({...}) @Component({...})
export class AppComponent { export class AppComponent {
constructor(@Inject('SpecialFoo') public foo:Foo) {} constructor(@Inject('SpecialFoo') public foo:Foo) {}
@Input() name:string; @Input() name:string;
} }
``` ```
The scope of a decorator is limited to the language feature The scope of a decorator is limited to the language feature
that it decorates. None of the decorations shown here will "leak" to other that it decorates. None of the decorations shown here will "leak" to other
classes appearing below it in the file. classes appearing below it in the file.
.alert.is-important .alert.is-important
:marked :marked
Always include the parentheses `()` when applying a decorator. Always include the parentheses `()` when applying a decorator.
A decorator is a **function** that must be called when applied. A decorator is a **function** that must be called when applied.
// #docregion d2
:marked :marked
## Dependency Injection ## Dependency Injection
.l-sub-section .l-sub-section
@ -301,7 +299,7 @@ a#aot
Angular registers some of its own providers with every injector. Angular registers some of its own providers with every injector.
We can register our own providers. We can register our own providers.
Learn more in the [Dependency Injection](/docs/ts/latest/guide/dependency-injection.html) chapter. Learn more in the [Dependency Injection](!{docsLatest}/guide/dependency-injection.html) chapter.
:marked :marked
## Directive ## Directive
.l-sub-section .l-sub-section
@ -334,13 +332,9 @@ a#aot
1. [Structural Directives](#structural-directive), a directive responsible for 1. [Structural Directives](#structural-directive), a directive responsible for
shaping or re-shaping HTML layout, typically by adding, removing, or manipulating shaping or re-shaping HTML layout, typically by adding, removing, or manipulating
elements and their children. elements and their children.
// #enddocregion d2
// #docregion e1 .l-main-section#E
<a id="E"></a>
// #enddocregion e1
// #docregion e2
.l-main-section
:marked :marked
## ECMAScript ## ECMAScript
.l-sub-section .l-sub-section
@ -375,14 +369,11 @@ a#aot
:marked :marked
Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers. Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers.
See [ECMAScript](#ecmascript). See [ECMAScript](#ecmascript).
// #enddocregion e2
// #docregion f-l a#F
<a id="F"></a> a#G
<a id="G"></a> a#H
<a id="H"></a> .l-main-section#I
<a id="I"></a>
.l-main-section
:marked :marked
## Injector ## Injector
.l-sub-section .l-sub-section
@ -396,11 +387,11 @@ a#aot
.l-sub-section .l-sub-section
:marked :marked
A directive property that can be the ***target*** of a A directive property that can be the ***target*** of a
[Property Binding](/docs/ts/latest/guide/template-syntax.html#property-binding). [Property Binding](!{docsLatest}/guide/template-syntax.html#property-binding).
Data values flow *into* this property from the data source identified Data values flow *into* this property from the data source identified
in the template expression to the right of the equal sign. in the template expression to the right of the equal sign.
See the [Template Syntax](/docs/ts/latest/guide/template-syntax.html#inputs-outputs) chapter. See the [Template Syntax](!{docsLatest}/guide/template-syntax.html#inputs-outputs) chapter.
:marked :marked
## Interpolation ## Interpolation
@ -417,34 +408,28 @@ a#aot
:marked :marked
Learn more about interpolation in the Learn more about interpolation in the
[Template Syntax](/docs/ts/latest/guide/template-syntax.html#interpolation) chapter. [Template Syntax](!{docsLatest}/guide/template-syntax.html#interpolation) chapter.
.l-main-section#J
<a id="J"></a> +ifDocsFor('ts')
a#jit
a#jit
.l-main-section
:marked
## Just in Time (JIT) Compilation
.l-sub-section
:marked :marked
With Angular _Just in Time_ bootstrapping you compile your components and modules in the browser ## Just in Time (JIT) Compilation
and launch the application dynamically. This is a good choice during development. .l-sub-section
Consider the [Ahead of Time](#aot) mode for production apps. :marked
With Angular _Just in Time_ bootstrapping you compile your components and modules in the browser
and launch the application dynamically. This is a good choice during development.
Consider the [Ahead of Time](#aot) mode for production apps.
<a id="K"></a> .l-main-section#K
:marked :marked
## kebab-case ## kebab-case
.l-sub-section .l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`). See [dash-case](#dash-case).
Directive selectors and the root of filenames are often spelled in kebab-case. Examples include: `my-app` and `hero-list.component.ts`.
This form is also known as [dash-case](#dash-case).
<a id="L"></a> .l-main-section#L
.l-main-section
:marked :marked
## Lifecycle Hooks ## Lifecycle Hooks
.l-sub-section .l-sub-section
@ -468,93 +453,84 @@ a#jit
* `ngAfterViewChecked` - after every check of a component's view(s) * `ngAfterViewChecked` - after every check of a component's view(s)
* `ngOnDestroy` - just before the directive is destroyed. * `ngOnDestroy` - just before the directive is destroyed.
Learn more in the [Lifecycle Hooks](/docs/ts/latest/guide/lifecycle-hooks.html) chapter. Learn more in the [Lifecycle Hooks](!{docsLatest}/guide/lifecycle-hooks.html) chapter.
// #enddocregion f-l
.l-main-section#M
// #docregion m1
<a id="M"></a>
// #enddocregion m1
// #docregion m2
.l-main-section
:marked :marked
## Module ## Module
.l-sub-section .l-sub-section
block module-defn
.alert.is-important
:marked
In Angular, there are two types of modules:
- [Angular modules](#angular-module).
See the [Angular Module](!{docsLatest}/guide/ngmodule.html) chapter for details and examples.
- ES2015 modules as described in this section.
.alert.is-important
:marked :marked
In Angular, there are two types of modules: Angular apps are modular.
- [Angular modules](#angular-module).
See the [Angular Module](/docs/ts/latest/guide/ngmodule.html) chapter for details and examples.
- ES2015 modules as described in this section.
In general, we assemble our application from many modules, both the ones we write ourselves
and the ones we acquire from others.
A typical module is a cohesive block of code dedicated to a single purpose.
A module **exports** something of value in that code, typically one thing such as a class.
A module that needs that thing, **imports** it.
The structure of Angular modules and the import/export syntax
is based on the [ES2015](#es2015) module standard
described [here](http://www.2ality.com/2014/09/es6-modules-final.html).
An application that adheres to this standard requires a module loader to
load modules on request and resolve inter-module dependencies.
Angular does not ship with a module loader and does not have a preference
for any particular 3rd party library (although most samples use SystemJS).
Application developers may pick any module library that conforms to the standard
Modules are typically named after the file in which the exported thing is defined.
The Angular [DatePipe](https://github.com/angular/angular/blob/master/modules/@angular/common/src/pipes/date_pipe.ts)
class belongs to a feature module named `date_pipe` in the file `date_pipe.ts`.
Developers rarely access Angular feature modules directly.
We usually import them from one of the Angular [scoped packages](#scoped-package) such as `@angular/core`.
a#N
.l-main-section#O
+ifDocsFor('ts|js')
:marked :marked
Angular apps are modular. ## Observable
.l-sub-section
:marked
We can think of an observable as an array whose items arrive asynchronously over time.
Observables help us manage asynchronous data, such as data coming from a backend service.
Observables are used within Angular itself, including Angular's event system and its http client service.
In general, we assemble our application from many modules, both the ones we write ourselves To use observables, Angular uses a third-party library called Reactive Extensions (RxJS).
and the ones we acquire from others. Observables are a proposed feature for ES 2016, the next version of JavaScript.
A typical module is a cohesive block of code dedicated to a single purpose.
A module **exports** something of value in that code, typically one thing such as a class.
A module that needs that thing, **imports** it.
The structure of Angular modules and the import/export syntax
is based on the [ES2015](#es2015) module standard
described [here](http://www.2ality.com/2014/09/es6-modules-final.html).
An application that adheres to this standard requires a module loader to
load modules on request and resolve inter-module dependencies.
Angular does not ship with a module loader and does not have a preference
for any particular 3rd party library (although most samples use SystemJS).
Application developers may pick any module library that conforms to the standard
Modules are typically named after the file in which the exported thing is defined.
The Angular [DatePipe](https://github.com/angular/angular/blob/master/modules/@angular/common/src/pipes/date_pipe.ts)
class belongs to a feature module named `date_pipe` in the file `date_pipe.ts`.
Developers rarely access Angular feature modules directly.
We usually import them from one of the Angular [scoped packages](#scoped-package) such as `@angular/core`.
// #enddocregion m2
// #docregion n-s-1
- var lang = current.path[1]
- var decorator = lang === 'dart' ? 'annotation' : '<a href="#decorator">decorator</a>'
- var atSym = lang === 'js' ? '' : '@'
<a id="N"></a>
<a id="O"></a>
.l-main-section
:marked
## Observable
.l-sub-section
:marked
We can think of an observable as an array whose items arrive asynchronously over time.
Observables help us manage asynchronous data, such as data coming from a backend service.
Observables are used within Angular itself, including Angular's event system and its http client service.
To use observables, Angular uses a third-party library called Reactive Extensions (RxJS).
Observables are a proposed feature for ES 2016, the next version of JavaScript.
:marked :marked
## Output ## Output
.l-sub-section .l-sub-section
:marked :marked
A directive property that can be the ***target*** of an A directive property that can be the ***target*** of an
[Event Binding](/docs/ts/latest/guide/template-syntax.html#property-binding). [Event Binding](!{docsLatest}/guide/template-syntax.html#property-binding).
Events stream *out* of this property to the receiver identified Events stream *out* of this property to the receiver identified
in the template expression to the right of the equal sign. in the template expression to the right of the equal sign.
See the [Template Syntax](/docs/ts/latest/guide/template-syntax.html#inputs-outputs) chapter. See the [Template Syntax](!{docsLatest}/guide/template-syntax.html#inputs-outputs) chapter.
.l-main-section#P
.l-main-section
<a id="P"></a>
:marked :marked
## PascalCase ## PascalCase
.l-sub-section .l-sub-section
:marked :marked
The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter. The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter.
Class names are typically spelled in PascalCase. Examples include: `Person` and `HeroDetailComponent`. Class names are typically spelled in PascalCase. Examples include: `Person` and `HeroDetailComponent`.
This form is also known as **upper camel case**, to distinguish it from **lower camel case** which we simply call [camelCase](#camelcase). This form is also known as **upper camel case**, to distinguish it from **lower camel case** which we simply call [camelCase](#camelcase).
In this documentation, "PascalCase" means *upper camel case* and "camelCase" means *lower camel case*. In this documentation, "PascalCase" means *upper camel case* and "camelCase" means *lower camel case*.
@ -563,7 +539,7 @@ a#jit
.l-sub-section .l-sub-section
:marked :marked
An Angular pipe is a function that transforms input values to output values for An Angular pipe is a function that transforms input values to output values for
display in a [view](#view). We use the `#{atSym}Pipe` !{decorator} display in a [view](#view). We use the `!{_at}Pipe` !{_decoratorLink}
to associate the pipe function with a name. We can then use that to associate the pipe function with a name. We can then use that
name in our HTML to declaratively transform values on screen. name in our HTML to declaratively transform values on screen.
@ -573,40 +549,37 @@ a#jit
code-example(language="html" escape="html"). code-example(language="html" escape="html").
<label>Price: </label>{{product.price | currency}} <label>Price: </label>{{product.price | currency}}
:marked :marked
Learn more in the chapter on [pipes](/docs/ts/latest/guide/pipes.html) . Learn more in the chapter on [pipes](!{docsLatest}/guide/pipes.html) .
- var _ProviderUrl = docsLatest+'/api/'+(lang == 'dart' ? 'angular2.core' : 'core/index')+'/Provider-class.html'
:marked :marked
## Provider ## Provider
.l-sub-section .l-sub-section
:marked :marked
A Provider creates a new instance of a dependency for the Dependency Injection system. A [Provider](!{_ProviderUrl}) creates a new instance of a dependency for the
It relates a lookup token to code - sometimes called a "recipe" - that can create a dependency value. [Dependency Injection](#dependency-injection) system.
It relates a lookup token to code &mdash; sometimes called a "recipe" &mdash;
that can create a dependency value.
For example, `new Provider(Foo, {useClass: Foo})` creates a `Provider` a#Q
that relates the `Foo` token to a function that creates a new instance of the `Foo` class. .l-main-section#R
There are other ways to create tokens and recipes. +ifDocsFor('ts|js')
See [Dependency Injection](#dependency-injection) chapter to learn more.
.l-main-section
<a id="Q"></a>
<a id="R"></a>
<a id="reactive-forms"></a>
:marked
## Reactive Forms
.l-sub-section
:marked :marked
A technique for building Angular forms through code in a component. ## Reactive Forms
The alternate technique is [Template-Driven Forms](#template-driven-forms). .l-sub-section
:marked
A technique for building Angular forms through code in a component.
The alternate technique is [Template-Driven Forms](#template-driven-forms).
When building reactive forms: When building reactive forms:
- The "source of truth" is the component. The validation is defined using code in the component. - The "source of truth" is the component. The validation is defined using code in the component.
- Each control is explicitly created in the component class with `new FormControl()` or with `FormBuilder`. - Each control is explicitly created in the component class with `new FormControl()` or with `FormBuilder`.
- The template input elements do *not* use `ngModel`. - The template input elements do *not* use `ngModel`.
- The associated Angular directives are all prefixed with `Form` such as `FormGroup`, `FormControl`, and `FormControlName`. - The associated Angular directives are all prefixed with `Form` such as `FormGroup`, `FormControl`, and `FormControlName`.
Reactive forms are powerful, flexible, and great for more complex data entry form scenarios, such as dynamic generation Reactive forms are powerful, flexible, and great for more complex data entry form scenarios, such as dynamic generation
of form controls. of form controls.
:marked :marked
## Router ## Router
@ -617,60 +590,73 @@ a#jit
and taking other similar actions that cause the application to and taking other similar actions that cause the application to
replace one view with another. replace one view with another.
The Angular [Component Router](/docs/ts/latest/guide/router.html) is a richly featured mechanism for configuring The Angular [Component Router](!{docsLatest}/guide/router.html) is a richly featured mechanism for configuring
and managing the entire view navigation process including the creation and destruction and managing the entire view navigation process including the creation and destruction
of views. of views.
+ifDocsFor('ts|js')
:marked
In most cases, components becomes attached to a [router](#router) by means
of a `RouterConfig` that defines routes to views.
In most cases, components becomes attached to a [router](#router) by means A [routing component's](#routing-component) template has a `RouterOutlet` element
of a `RouterConfig` that defines routes to views. where it can display views produced by the router.
A [routing component's](#routing-component) template has a `RouterOutlet` element where it can display views produced by the router. Other views in the application likely have anchor tags or buttons with `RouterLink`
directives that users can click to navigate.
Other views in the application likely have anchor tags or buttons with `RouterLink` directives that users can click to navigate. See the [Component Router](!{docsLatest}/guide/router.html) chapter to learn more.
See the [Component Router](/docs/ts/latest/guide/router.html) chapter to learn more. +ifDocsFor('ts|js')
:marked
## RouterModule
.l-sub-section
:marked :marked
A separate [Angular module](#angular-module) that provides the necessary service providers and directives for navigating through application views. ## RouterModule
.l-sub-section
:marked
A separate [Angular module](#angular-module) that provides the necessary service providers and directives for navigating through application views.
See the [Component Router](/docs/ts/latest/guide/router.html) chapter to learn more. See the [Component Router](!{docsLatest}/guide/router.html) chapter to learn more.
<a id="routing-component"></a>
:marked :marked
## Routing Component ## Routing Component
.l-sub-section .l-sub-section
block routing-component-defn
:marked
An Angular [Component](#component) with a RouterOutlet that displays views based on router navigations.
See the [Component Router](!{docsLatest}/guide/router.html) chapter to learn more.
.l-main-section#S
+ifDocsFor('ts|js')
:marked :marked
An Angular [Component](#component) with a RouterOutlet that displays views based on router navigations. ## Scoped Package
.l-sub-section
:marked
Angular modules are delivered within *scoped packages* such as `@angular/core`, `@angular/common`, `@angular/platform-browser-dynamic`,
`@angular/http`, and `@angular/router`.
See the [Component Router](/docs/ts/latest/guide/router.html) chapter to learn more. A [*scoped package*](https://docs.npmjs.com/misc/scope) is a way to group related *npm* packages.
<a id="S"></a> We import a scoped package the same way we'd import a *normal* package.
.l-main-section The only difference, from a consumer perspective,
// #enddocregion n-s-1 is that the package name begins with the Angular *scope name*, `@angular`.
+makeExcerpt('architecture/ts/app/app.component.ts', 'import', '')
a#snake-case
:marked :marked
## Scoped Package ## snake_case
.l-sub-section .l-sub-section
:marked block snake-case-defn
Angular modules are delivered within *scoped packages* such as `@angular/core`, `@angular/common`, `@angular/platform-browser-dynamic`, :marked
`@angular/http`, and `@angular/router`. The practice of writing compound words or phrases such that each word is separated by an
underscore (`_`). This form is also known as **underscore case**.
A [*scoped package*](https://docs.npmjs.com/misc/scope) is a way to group related *npm* packages.
We import a scoped package the same way we'd import a *normal* package.
The only difference, from a consumer perspective,
is that the package name begins with the Angular *scope name*, `@angular`.
+makeExcerpt('architecture/ts/app/app.component.ts', 'import', '')
// #docregion n-s-2
:marked :marked
## Service ## Service
.l-sub-section .l-sub-section
:marked :marked
Components are great and all … but what do we do with data or logic that are not associated Components are great and all, but what do we do with data or logic that are not associated
with a specific view or that we want to share across components? We build services! with a specific view or that we want to share across components? We build services!
Applications often require services such as a hero data service or a logging service. Applications often require services such as a hero data service or a logging service.
@ -678,10 +664,10 @@ a#jit
A service is a class with a focused purpose. A service is a class with a focused purpose.
We often create a service to implement features that are We often create a service to implement features that are
independent from any specific view, independent from any specific view,
provide share data or logic across components, or encapsulate external interactions. provide share data or logic across components, or encapsulate external interactions.
See the [Services](/docs/ts/latest/tutorial/toh-pt4.html) chapter of the tutorial to learn more. See the [Services](!{docsLatest}/tutorial/toh-pt4.html) chapter of the tutorial to learn more.
:marked :marked
## Structural Directive ## Structural Directive
@ -694,12 +680,9 @@ a#jit
The `ngIf` "conditional element" directive and the `ngFor` "repeater" directive are The `ngIf` "conditional element" directive and the `ngFor` "repeater" directive are
good examples in this category. good examples in this category.
See the [Structural Directives](/docs/ts/latest/guide/structural-directives.html) chapter to learn more. See the [Structural Directives](!{docsLatest}/guide/structural-directives.html) chapter to learn more.
// #enddocregion n-s-2
// #docregion t1 .l-main-section#T
<a id="T"></a>
.l-main-section
:marked :marked
## Template ## Template
.l-sub-section .l-sub-section
@ -708,38 +691,36 @@ a#jit
the support and continuing guidance of an Angular [Directive](#directive), the support and continuing guidance of an Angular [Directive](#directive),
most notably a [Component](#component). most notably a [Component](#component).
We write templates in a special [Template Syntax](/docs/ts/latest/guide/template-syntax.html). We write templates in a special [Template Syntax](!{docsLatest}/guide/template-syntax.html).
<a id="template-driven-forms"></a> +ifDocsFor('ts|js')
:marked
## Template-Driven Forms
.l-sub-section
:marked :marked
A technique for building Angular forms using HTML forms and input elements in the view. ## Template-Driven Forms
The alternate technique is [Reactive Forms](#reactive-forms). .l-sub-section
:marked
A technique for building Angular forms using HTML forms and input elements in the view.
The alternate technique is [Reactive Forms](#reactive-forms).
When building template-driven forms: When building template-driven forms:
- The "source of truth" is the template. The validation is defined using attributes on the individual input elements. - The "source of truth" is the template. The validation is defined using attributes on the individual input elements.
- [Two-way binding](#data-binding) with `ngModel` keeps the component model in synchronization with the user's entry into the input elements. - [Two-way binding](#data-binding) with `ngModel` keeps the component model in synchronization with the user's entry into the input elements.
- Behind the scenes, Angular creates a new control for each input element that has a `name` attribute and - Behind the scenes, Angular creates a new control for each input element that has a `name` attribute and
two-way binding set up. two-way binding set up.
- The associated Angular directives are all prefixed with `ng` such as `ngForm`, `ngModel`, and `ngModelGroup`. - The associated Angular directives are all prefixed with `ng` such as `ngForm`, `ngModel`, and `ngModelGroup`.
Template-driven forms are convenient, quick, and simple and are a good choice for many basic data entry form scenarios. Template-driven forms are convenient, quick, and simple and are a good choice for many basic data entry form scenarios.
Learn how to build template-driven forms Learn how to build template-driven forms
in the [Forms](/docs/ts/latest/guide/forms.html) chapter. in the [Forms](!{docsLatest}/guide/forms.html) chapter.
:marked :marked
## Template Expression ## Template Expression
.l-sub-section .l-sub-section
:marked :marked
An expression is a JavaScript-like syntax that Angular evaluates within An expression is a !{_Lang}-like syntax that Angular evaluates within
a [data binding](#data-binding). Learn how to write template expressions a [data binding](#data-binding). Learn how to write template expressions
in the [Template Syntax](/docs/ts/latest/guide/template-syntax.html#template-expressions) chapter. in the [Template Syntax](!{docsLatest}/guide/template-syntax.html#template-expressions) chapter.
// #enddocregion t1
// #docregion t2
:marked :marked
## Transpile ## Transpile
.l-sub-section .l-sub-section
@ -763,15 +744,11 @@ a#jit
TypeScript is the preferred language for Angular 2 development although TypeScript is the preferred language for Angular 2 development although
we are welcome to write in other JavaScript dialects such as [ES5](#es5). we are welcome to write in other JavaScript dialects such as [ES5](#es5).
Angular 2 itself is written in TypeScript.
Learn more about TypeScript on its [website](http://www.typescriptlang.org/). Learn more about TypeScript on its [website](http://www.typescriptlang.org/).
// #enddocregion t2
// #docregion u-z a#U
<a id="U"></a> .l-main-section#V
<a id="V"></a>
.l-main-section
:marked :marked
## View ## View
.l-sub-section .l-sub-section
@ -788,31 +765,31 @@ a#jit
dynamically as the user navigates through the application, typically dynamically as the user navigates through the application, typically
under the control of a [router](#router). under the control of a [router](#router).
.l-main-section a#W
<a id="W"></a> a#X
<a id="X"></a> a#Y
<a id="Y"></a> .l-main-section#Z
<a id="Z"></a>
:marked :marked
## Zone ## Zone
.l-sub-section .l-sub-section
:marked block zone-defn
Zones are a mechanism for encapsulating and intercepting :marked
a JavaScript application's asynchronous activity. Zones are a mechanism for encapsulating and intercepting
a JavaScript application's asynchronous activity.
The browser DOM and JavaScript have a limited number The browser DOM and JavaScript have a limited number
of asynchronous activities, activities such as DOM events (e.g., clicks), of asynchronous activities, activities such as DOM events (e.g., clicks),
[promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), and [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), and
[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
calls to remote servers. calls to remote servers.
Zones intercept all of these activities and give a "zone client" the opportunity Zones intercept all of these activities and give a "zone client" the opportunity
to take action before and after the async activity completes. to take action before and after the async activity completes.
Angular runs our application in a zone where it can respond to Angular runs our application in a zone where it can respond to
asynchronous events by checking for data changes and updating asynchronous events by checking for data changes and updating
the information it displays via [data binding](#data-binding). the information it displays via [data bindings](#data-binding).
Learn more about zones in this Learn more about zones in this
[Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). [Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U).
// #enddocregion u-z

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

@ -1 +1,5 @@
include ../glossary extends ../glossary
block includes
include ../_util-fns