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
- var fragPath='../../ts/latest/_fragments/';
block includes
include _util-fns
!=partial(fragPath + 'glossary-intro')
!=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
block annotation-defn
:marked
The practice of writing compound words or phrases such that each word is separated by an
underscore (`_`).
Library and file names are often spelled in snake_case. Examples include:
`angular2_tour_of_heroes` and `app_component.dart`.
This form is also known as **underscore case**.
When unqualified, _annotation_ refers to a Dart [metadata
annotation][metadata] (as opposed to, say, a type annotation). A metadata
annotation begins with the character `@`, followed by either a reference
to a compile-time constant (such as [`Component`](#component)) or a call
to a constant constructor. See the [Dart Language Guide][metadata] for
details.
!=partial(fragPath + 'glossary-n-s-2')
!=partial(fragPath + 'glossary-t1')
//partial(fragPath + 'glossary-t2') notneeded in dart
!=partial(fragPath + 'glossary-u-z')
The corresponding term in TypeScript and JavaScript is
[_decorator_](!{docsPath}/ts/latest/glossary.html#decorator).
[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
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
// 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')
extends ../../ts/latest/glossary.jade
// NOTE: (ericjim): I am almost certain these lines are doing nothing,
// so instead I use `!=partial` to include the glossary fragments.
//+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')
block includes
include _util-fns

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
# 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)
[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)
// #enddocregion intro
// #docregion a1
<a id="A"></a>
// #enddocregion a1
.l-main-section
:marked
## Annotation
.l-sub-section
.l-main-section#A
+ifDocsFor('ts')
a#aot
:marked
In practice a synonym for [Decoration](#decorator).
// #enddocregion a-1
// #docregion a-2
## Ahead of Time (AOT) Compilation
.l-sub-section
:marked
Angular applications can be compiled by developers at build-time.
By compiling your application using the compiler-cli, `ngc`, you can boostrap directly
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
## Attribute Directive
.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
an Attribute Directive.
// #enddocregion a-2
// #docregion b-c
- 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
.l-main-section#B
+ifDocsFor('ts|js')
:marked
A barrel is a way to *rollup exports* from several modules into a single convenience module.
The barrel itself is a module file that re-exports *selected* exports of other modules.
Imagine three 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
:marked
That's why we can write this:
+makeExcerpt('quickstart/ts/app/app.component.ts', 'import', '')
// #docregion b-c
## 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
## Binding
@ -101,25 +129,24 @@ include _util-fns
:marked
## Bootstrap
.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
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.
<a id="C"></a>
.l-main-section
.l-main-section#C
:marked
## camelCase
.l-sub-section
:marked
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_.
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_.
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).
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.
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
that Angular needs to create a component instance and render it with its template
as a view.
Those familiar with "MVC" and "MVVM" patterns will recognize
the Component in the role of "Controller" or "View Model".
// #enddocregion b-c
// #docregion d1
<a id="D"></a>
.l-main-section
.l-main-section#D
:marked
## dash-case
.l-sub-section
:marked
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`.
The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`).
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
## Data Binding
.l-sub-section
@ -176,52 +201,53 @@ include _util-fns
operations and supporting declaration syntax.
The many forms of binding include:
* [Interpolation](/docs/ts/latest/guide/template-syntax.html#interpolation)
* [Property Binding](/docs/ts/latest/guide/template-syntax.html#property-binding)
* [Event Binding](/docs/ts/latest/guide/template-syntax.html#event-binding)
* [Attribute Binding](/docs/ts/latest/guide/template-syntax.html#attribute-binding)
* [Class Binding](/docs/ts/latest/guide/template-syntax.html#class-binding)
* [Style Binding](/docs/ts/latest/guide/template-syntax.html#style-binding)
* [Two-way data binding with ngModel](/docs/ts/latest/guide/template-syntax.html#ng-model)
* [Interpolation](!{docsLatest}/guide/template-syntax.html#interpolation)
* [Property Binding](!{docsLatest}/guide/template-syntax.html#property-binding)
* [Event Binding](!{docsLatest}/guide/template-syntax.html#event-binding)
* [Attribute Binding](!{docsLatest}/guide/template-syntax.html#attribute-binding)
* [Class Binding](!{docsLatest}/guide/template-syntax.html#class-binding)
* [Style Binding](!{docsLatest}/guide/template-syntax.html#style-binding)
* [Two-way data binding with ngModel](!{docsLatest}/guide/template-syntax.html#ng-model)
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
<a id="decorator"></a> <a id="decoration"></a>
:marked
## Decorator | Decoration
.l-sub-section
+ifDocsFor('ts|dart')
a#decorator
a#decoration
: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
immediately above or to the left of the thing it decorates.
We apply a decorator by positioning it
immediately above or to the left of the thing it decorates.
Angular has its own set of decorators to help it interoperate with our application parts.
Here is an example of a `@Component` decorator that identifies a
class as an Angular [Component](#component) and an `@Input` decorator applied to a property
of that component.
The elided object argument to the `@Component` decorator would contain the pertinent component metadata.
```
@Component({...})
export class AppComponent {
constructor(@Inject('SpecialFoo') public foo:Foo) {}
@Input() name:string;
}
```
The scope of a decorator is limited to the language feature
that it decorates. None of the decorations shown here will "leak" to other
classes appearing below it in the file.
Angular has its own set of decorators to help it interoperate with our application parts.
Here is an example of a `@Component` decorator that identifies a
class as an Angular [Component](#component) and an `@Input` decorator applied to a property
of that component.
The elided object argument to the `@Component` decorator would contain the pertinent component metadata.
```
@Component({...})
export class AppComponent {
constructor(@Inject('SpecialFoo') public foo:Foo) {}
@Input() name:string;
}
```
The scope of a decorator is limited to the language feature
that it decorates. None of the decorations shown here will "leak" to other
classes appearing below it in the file.
.alert.is-important
:marked
Always include the parentheses `()` when applying a decorator.
A decorator is a **function** that must be called when applied.
.alert.is-important
:marked
Always include the parentheses `()` when applying a decorator.
A decorator is a **function** that must be called when applied.
// #docregion d2
:marked
## Dependency Injection
.l-sub-section
@ -271,11 +297,9 @@ include _util-fns
Registering providers is a critical preparatory step.
Angular registers some of its own providers with every injector.
We can register our own providers. Quite often the best time to register a `Provider`
is when we [bootstrap](#bootstrap) the application.
There are other opportunities to register as well.
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
## Directive
.l-sub-section
@ -308,13 +332,9 @@ include _util-fns
1. [Structural Directives](#structural-directive), a directive responsible for
shaping or re-shaping HTML layout, typically by adding, removing, or manipulating
elements and their children.
// #enddocregion d2
// #docregion e1
<a id="E"></a>
// #enddocregion e1
// #docregion e2
.l-main-section
.l-main-section#E
:marked
## ECMAScript
.l-sub-section
@ -322,23 +342,17 @@ include _util-fns
The [official JavaScript language specification](https://en.wikipedia.org/wiki/ECMAScript).
The latest approved version of JavaScript is
[ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/)
(AKA "ES2015" or "ES6") and many Angular 2 developers will write their applications
[ECMAScript 2016](http://www.ecma-international.org/ecma-262/7.0/)
(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
compatible with it such as [TypeScript](#typesScript).
Most modern browsers today only support the prior "ECMAScript 5" (AKA ES5) standard.
Applications written in ES2015 or one of its dialects must be "[transpiled](#transpile)"
Most modern browsers today only support the much older "ECMAScript 5" (AKA ES5) standard.
Applications written in ES2016, ES2015 or one of their dialects must be "[transpiled](#transpile)"
to ES5 JavaScript.
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
## ES2015
.l-sub-section
@ -355,14 +369,11 @@ include _util-fns
:marked
Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers.
See [ECMAScript](#ecmascript).
// #enddocregion e2
// #docregion f-l
<a id="F"></a>
<a id="G"></a>
<a id="H"></a>
<a id="I"></a>
.l-main-section
a#F
a#G
a#H
.l-main-section#I
:marked
## Injector
.l-sub-section
@ -376,11 +387,11 @@ include _util-fns
.l-sub-section
:marked
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
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
## Interpolation
@ -397,25 +408,28 @@ include _util-fns
:marked
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
<a id="K"></a>
.l-main-section#K
:marked
## kebab-case
.l-sub-section
:marked
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 kebab-case. Examples include: `my-app` and `hero-list.component.ts`.
This form is also known as [dash-case](#dash-case).
See [dash-case](#dash-case).
<a id="L"></a>
.l-main-section
.l-main-section#L
:marked
## Lifecycle Hooks
.l-sub-section
@ -439,74 +453,84 @@ include _util-fns
* `ngAfterViewChecked` - after every check of a component's view(s)
* `ngOnDestroy` - just before the directive is destroyed.
Learn more in the [Lifecycle Hooks](/docs/ts/latest/guide/lifecycle-hooks.html) chapter.
// #enddocregion f-l
Learn more in the [Lifecycle Hooks](!{docsLatest}/guide/lifecycle-hooks.html) chapter.
.l-main-section#M
// #docregion m1
<a id="M"></a>
// #enddocregion m1
// #docregion m2
.l-main-section
:marked
## Module
.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
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
and the ones we acquire from others.
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.
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
## Output
.l-sub-section
:marked
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
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
## PascalCase
.l-sub-section
:marked
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`.
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`.
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*.
@ -515,8 +539,8 @@ include _util-fns
.l-sub-section
:marked
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}
to associate the pipe function with a name. We then can use that
display in a [view](#view). We use the `!{_at}Pipe` !{_decoratorLink}
to associate the pipe function with a name. We can then use that
name in our HTML to declaratively transform values on screen.
Here's an example that uses the built-in `currency` pipe to display
@ -525,24 +549,38 @@ include _util-fns
code-example(language="html" escape="html").
<label>Price: </label>{{product.price | currency}}
: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
## Provider
.l-sub-section
:marked
A Provider creates a new instance of a dependency for the Dependency Injection system.
It relates a lookup token to code - sometimes called a "recipe" - that can create a dependency value.
A [Provider](!{_ProviderUrl}) creates a new instance of a dependency for the
[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`
that relates the `Foo` token to a function that creates a new instance of the `Foo` class.
a#Q
.l-main-section#R
There are other ways to create tokens and recipes.
See [Dependency Injection](#dependency-injection) chapter to learn more.
+ifDocsFor('ts|js')
: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
## Router
.l-sub-section
@ -552,40 +590,84 @@ include _util-fns
and taking other similar actions that cause the application to
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
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
## Routing Component
.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
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
of a `#{atSym}RouterConfig` #{decorator} that defined routes to views controlled by this component.
A [*scoped package*](https://docs.npmjs.com/misc/scope) is a way to group related *npm* packages.
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>
.l-main-section
// #enddocregion n-s-1
a#snake-case
: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
:marked
Angular modules are delivered within *scoped packages* such as `@angular/core`, `@angular/common`, `@angular/platform-browser-dynamic`,
`@angular/http`, and `@angular/router`.
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!
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`.
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.
+makeExcerpt('architecture/ts/app/app.component.ts', 'import', '')
// #docregion n-s-2
A service is a class with a focused purpose.
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
## Structural Directive
@ -597,11 +679,10 @@ include _util-fns
The `ngIf` "conditional element" directive and the `ngFor` "repeater" directive are
good examples in this category.
// #enddocregion n-s-2
// #docregion t1
<a id="T"></a>
.l-main-section
See the [Structural Directives](!{docsLatest}/guide/structural-directives.html) chapter to learn more.
.l-main-section#T
:marked
## Template
.l-sub-section
@ -610,18 +691,36 @@ include _util-fns
the support and continuing guidance of an Angular [Directive](#directive),
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
## Template Expression
.l-sub-section
: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
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
## Transpile
.l-sub-section
@ -645,15 +744,11 @@ include _util-fns
TypeScript is the preferred language for Angular 2 development although
we are welcome to write in other JavaScript dialects such as [ES5](#es5).
Angular 2 itself is written in TypeScript.
Learn more about TypeScript on its [website](http://www.typescriptlang.org/).
// #enddocregion t2
// #docregion u-z
<a id="U"></a>
<a id="V"></a>
.l-main-section
a#U
.l-main-section#V
:marked
## View
.l-sub-section
@ -670,31 +765,31 @@ include _util-fns
dynamically as the user navigates through the application, typically
under the control of a [router](#router).
.l-main-section
<a id="W"></a>
<a id="X"></a>
<a id="Y"></a>
<a id="Z"></a>
a#W
a#X
a#Y
.l-main-section#Z
:marked
## Zone
.l-sub-section
:marked
Zones are a mechanism for encapsulating and intercepting
a JavaScript application's asynchronous activity.
block zone-defn
:marked
Zones are a mechanism for encapsulating and intercepting
a JavaScript application's asynchronous activity.
The browser DOM and JavaScript have a limited number
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
[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
calls to remote servers.
The browser DOM and JavaScript have a limited number
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
[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
calls to remote servers.
Zones intercept all of these activities and give a "zone client" the opportunity
to take action before and after the async activity completes.
Zones intercept all of these activities and give a "zone client" the opportunity
to take action before and after the async activity completes.
Angular runs our application in a zone where it can respond to
asynchronous events by checking for data changes and updating
the information it displays via [data binding](#data-binding).
Angular runs our application in a zone where it can respond to
asynchronous events by checking for data changes and updating
the information it displays via [data bindings](#data-binding).
Learn more about zones in this
[Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U).
// #enddocregion u-z
Learn more about zones in this
[Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U).

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
# 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)
[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)
// #enddocregion intro
// #docregion a1
<a id="A"></a>
// #enddocregion a1
a#aot
.l-main-section
:marked
## Ahead of Time (AOT) Compilation
.l-sub-section
.l-main-section#A
+ifDocsFor('ts')
a#aot
: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.
## Ahead of Time (AOT) Compilation
.l-sub-section
:marked
Angular applications can be compiled by developers at build-time.
By compiling your application using the compiler-cli, `ngc`, you can boostrap directly
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
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`.
## 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`.
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](/docs/ts/latest/guide/ngmodule.html) chapter for details and examples.
:marked
## Annotation
.l-sub-section
See the [Angular Module](!{docsLatest}/guide/ngmodule.html) chapter for details and examples.
+ifDocsFor('ts|dart')
:marked
In practice a synonym for [Decoration](#decorator).
// #enddocregion a-1
// #docregion a-2
## Annotation
.l-sub-section
block annotation-defn
:marked
In practice, a synonym for [Decoration](#decorator).
:marked
## Attribute Directive
.l-sub-section
@ -62,59 +67,53 @@ a#aot
The `ngClass` directive for adding and removing CSS class names is a good example of
an Attribute Directive.
// #enddocregion a-2
// #docregion b-c
- 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`.
.l-main-section#B
// #enddocregion b-c
:marked
That's why we can write this:
+makeExcerpt('quickstart/ts/app/app.component.ts', 'import', '')
// #docregion b-c
.alert.is-important
+ifDocsFor('ts|js')
: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
## Binding
@ -130,24 +129,24 @@ a#aot
:marked
## Bootstrap
.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
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.
<a id="C"></a>
.l-main-section
.l-main-section#C
:marked
## camelCase
.l-sub-section
:marked
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_.
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_.
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).
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.
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
that Angular needs to create a component instance and render it with its template
as a view.
Those familiar with "MVC" and "MVVM" patterns will recognize
the Component in the role of "Controller" or "View Model".
// #enddocregion b-c
// #docregion d1
<a id="D"></a>
.l-main-section
.l-main-section#D
:marked
## dash-case
.l-sub-section
:marked
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`.
The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`).
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
## Data Binding
.l-sub-section
@ -204,52 +201,53 @@ a#aot
operations and supporting declaration syntax.
The many forms of binding include:
* [Interpolation](/docs/ts/latest/guide/template-syntax.html#interpolation)
* [Property Binding](/docs/ts/latest/guide/template-syntax.html#property-binding)
* [Event Binding](/docs/ts/latest/guide/template-syntax.html#event-binding)
* [Attribute Binding](/docs/ts/latest/guide/template-syntax.html#attribute-binding)
* [Class Binding](/docs/ts/latest/guide/template-syntax.html#class-binding)
* [Style Binding](/docs/ts/latest/guide/template-syntax.html#style-binding)
* [Two-way data binding with ngModel](/docs/ts/latest/guide/template-syntax.html#ng-model)
* [Interpolation](!{docsLatest}/guide/template-syntax.html#interpolation)
* [Property Binding](!{docsLatest}/guide/template-syntax.html#property-binding)
* [Event Binding](!{docsLatest}/guide/template-syntax.html#event-binding)
* [Attribute Binding](!{docsLatest}/guide/template-syntax.html#attribute-binding)
* [Class Binding](!{docsLatest}/guide/template-syntax.html#class-binding)
* [Style Binding](!{docsLatest}/guide/template-syntax.html#style-binding)
* [Two-way data binding with ngModel](!{docsLatest}/guide/template-syntax.html#ng-model)
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
<a id="decorator"></a> <a id="decoration"></a>
:marked
## Decorator | Decoration
.l-sub-section
+ifDocsFor('ts|dart')
a#decorator
a#decoration
: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
immediately above or to the left of the thing it decorates.
We apply a decorator by positioning it
immediately above or to the left of the thing it decorates.
Angular has its own set of decorators to help it interoperate with our application parts.
Here is an example of a `@Component` decorator that identifies a
class as an Angular [Component](#component) and an `@Input` decorator applied to a property
of that component.
The elided object argument to the `@Component` decorator would contain the pertinent component metadata.
```
@Component({...})
export class AppComponent {
constructor(@Inject('SpecialFoo') public foo:Foo) {}
@Input() name:string;
}
```
The scope of a decorator is limited to the language feature
that it decorates. None of the decorations shown here will "leak" to other
classes appearing below it in the file.
Angular has its own set of decorators to help it interoperate with our application parts.
Here is an example of a `@Component` decorator that identifies a
class as an Angular [Component](#component) and an `@Input` decorator applied to a property
of that component.
The elided object argument to the `@Component` decorator would contain the pertinent component metadata.
```
@Component({...})
export class AppComponent {
constructor(@Inject('SpecialFoo') public foo:Foo) {}
@Input() name:string;
}
```
The scope of a decorator is limited to the language feature
that it decorates. None of the decorations shown here will "leak" to other
classes appearing below it in the file.
.alert.is-important
:marked
Always include the parentheses `()` when applying a decorator.
A decorator is a **function** that must be called when applied.
.alert.is-important
:marked
Always include the parentheses `()` when applying a decorator.
A decorator is a **function** that must be called when applied.
// #docregion d2
:marked
## Dependency Injection
.l-sub-section
@ -301,7 +299,7 @@ a#aot
Angular registers some of its own providers with every injector.
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
## Directive
.l-sub-section
@ -334,13 +332,9 @@ a#aot
1. [Structural Directives](#structural-directive), a directive responsible for
shaping or re-shaping HTML layout, typically by adding, removing, or manipulating
elements and their children.
// #enddocregion d2
// #docregion e1
<a id="E"></a>
// #enddocregion e1
// #docregion e2
.l-main-section
.l-main-section#E
:marked
## ECMAScript
.l-sub-section
@ -375,14 +369,11 @@ a#aot
:marked
Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers.
See [ECMAScript](#ecmascript).
// #enddocregion e2
// #docregion f-l
<a id="F"></a>
<a id="G"></a>
<a id="H"></a>
<a id="I"></a>
.l-main-section
a#F
a#G
a#H
.l-main-section#I
:marked
## Injector
.l-sub-section
@ -396,11 +387,11 @@ a#aot
.l-sub-section
:marked
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
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
## Interpolation
@ -417,34 +408,28 @@ a#aot
:marked
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>
a#jit
.l-main-section
:marked
## Just in Time (JIT) Compilation
.l-sub-section
+ifDocsFor('ts')
a#jit
: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.
## 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.
<a id="K"></a>
.l-main-section#K
:marked
## kebab-case
.l-sub-section
:marked
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 kebab-case. Examples include: `my-app` and `hero-list.component.ts`.
This form is also known as [dash-case](#dash-case).
See [dash-case](#dash-case).
<a id="L"></a>
.l-main-section
.l-main-section#L
:marked
## Lifecycle Hooks
.l-sub-section
@ -468,93 +453,84 @@ a#jit
* `ngAfterViewChecked` - after every check of a component's view(s)
* `ngOnDestroy` - just before the directive is destroyed.
Learn more in the [Lifecycle Hooks](/docs/ts/latest/guide/lifecycle-hooks.html) chapter.
// #enddocregion f-l
Learn more in the [Lifecycle Hooks](!{docsLatest}/guide/lifecycle-hooks.html) chapter.
.l-main-section#M
// #docregion m1
<a id="M"></a>
// #enddocregion m1
// #docregion m2
.l-main-section
:marked
## Module
.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
In Angular, there are two types of modules:
- [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.
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
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
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`.
// #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.
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
## Output
.l-sub-section
:marked
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
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
## PascalCase
.l-sub-section
: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`.
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*.
@ -563,7 +539,7 @@ a#jit
.l-sub-section
:marked
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
name in our HTML to declaratively transform values on screen.
@ -573,40 +549,37 @@ a#jit
code-example(language="html" escape="html").
<label>Price: </label>{{product.price | currency}}
: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
## Provider
.l-sub-section
:marked
A Provider creates a new instance of a dependency for the Dependency Injection system.
It relates a lookup token to code - sometimes called a "recipe" - that can create a dependency value.
A [Provider](!{_ProviderUrl}) creates a new instance of a dependency for the
[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`
that relates the `Foo` token to a function that creates a new instance of the `Foo` class.
a#Q
.l-main-section#R
There are other ways to create tokens and recipes.
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
+ifDocsFor('ts|js')
:marked
A technique for building Angular forms through code in a component.
The alternate technique is [Template-Driven Forms](#template-driven-forms).
## 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`.
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.
Reactive forms are powerful, flexible, and great for more complex data entry form scenarios, such as dynamic generation
of form controls.
:marked
## Router
@ -617,60 +590,73 @@ a#jit
and taking other similar actions that cause the application to
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
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
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.
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.
:marked
## RouterModule
.l-sub-section
+ifDocsFor('ts|js')
: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
## Routing Component
.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
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>
.l-main-section
// #enddocregion n-s-1
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#snake-case
:marked
## Scoped Package
## snake_case
.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`.
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
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
: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!
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.
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.
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
## Structural Directive
@ -694,12 +680,9 @@ a#jit
The `ngIf` "conditional element" directive and the `ngFor` "repeater" directive are
good examples in this category.
See the [Structural Directives](/docs/ts/latest/guide/structural-directives.html) chapter to learn more.
// #enddocregion n-s-2
See the [Structural Directives](!{docsLatest}/guide/structural-directives.html) chapter to learn more.
// #docregion t1
<a id="T"></a>
.l-main-section
.l-main-section#T
:marked
## Template
.l-sub-section
@ -708,38 +691,36 @@ a#jit
the support and continuing guidance of an Angular [Directive](#directive),
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>
:marked
## Template-Driven Forms
.l-sub-section
+ifDocsFor('ts|js')
:marked
A technique for building Angular forms using HTML forms and input elements in the view.
The alternate technique is [Reactive Forms](#reactive-forms).
## 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`.
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.
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](/docs/ts/latest/guide/forms.html) chapter.
Learn how to build template-driven forms
in the [Forms](!{docsLatest}/guide/forms.html) chapter.
:marked
## Template Expression
.l-sub-section
: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
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
## Transpile
.l-sub-section
@ -763,15 +744,11 @@ a#jit
TypeScript is the preferred language for Angular 2 development although
we are welcome to write in other JavaScript dialects such as [ES5](#es5).
Angular 2 itself is written in TypeScript.
Learn more about TypeScript on its [website](http://www.typescriptlang.org/).
// #enddocregion t2
// #docregion u-z
<a id="U"></a>
<a id="V"></a>
.l-main-section
a#U
.l-main-section#V
:marked
## View
.l-sub-section
@ -788,31 +765,31 @@ a#jit
dynamically as the user navigates through the application, typically
under the control of a [router](#router).
.l-main-section
<a id="W"></a>
<a id="X"></a>
<a id="Y"></a>
<a id="Z"></a>
a#W
a#X
a#Y
.l-main-section#Z
:marked
## Zone
.l-sub-section
:marked
Zones are a mechanism for encapsulating and intercepting
a JavaScript application's asynchronous activity.
block zone-defn
:marked
Zones are a mechanism for encapsulating and intercepting
a JavaScript application's asynchronous activity.
The browser DOM and JavaScript have a limited number
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
[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
calls to remote servers.
The browser DOM and JavaScript have a limited number
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
[XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
calls to remote servers.
Zones intercept all of these activities and give a "zone client" the opportunity
to take action before and after the async activity completes.
Zones intercept all of these activities and give a "zone client" the opportunity
to take action before and after the async activity completes.
Angular runs our application in a zone where it can respond to
asynchronous events by checking for data changes and updating
the information it displays via [data binding](#data-binding).
Angular runs our application in a zone where it can respond to
asynchronous events by checking for data changes and updating
the information it displays via [data bindings](#data-binding).
Learn more about zones in this
[Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U).
// #enddocregion u-z
Learn more about zones in this
[Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U).

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

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