diff --git a/public/docs/dart/latest/glossary.jade b/public/docs/dart/latest/glossary.jade index 673436c805..26feb4d9f3 100644 --- a/public/docs/dart/latest/glossary.jade +++ b/public/docs/dart/latest/glossary.jade @@ -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 diff --git a/public/docs/dart/latest/guide/glossary.jade b/public/docs/dart/latest/guide/glossary.jade index eeef440cb0..1d2eb49664 100644 --- a/public/docs/dart/latest/guide/glossary.jade +++ b/public/docs/dart/latest/guide/glossary.jade @@ -1,4 +1,4 @@ extends ../glossary block var-def - - var fragPath='../../../ts/latest/_fragments/'; + include ../_util-fns diff --git a/public/docs/js/latest/glossary.jade b/public/docs/js/latest/glossary.jade index 3b2d90d2f2..17e889224f 100644 --- a/public/docs/js/latest/glossary.jade +++ b/public/docs/js/latest/glossary.jade @@ -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') \ No newline at end of file +block includes + include _util-fns diff --git a/public/docs/js/latest/guide/glossary.jade b/public/docs/js/latest/guide/glossary.jade index a66284569e..1d2eb49664 100644 --- a/public/docs/js/latest/guide/glossary.jade +++ b/public/docs/js/latest/guide/glossary.jade @@ -1 +1,4 @@ -!= partial("../glossary") +extends ../glossary + +block var-def + include ../_util-fns diff --git a/public/docs/ts/_cache/glossary.jade b/public/docs/ts/_cache/glossary.jade index 50c6100cda..53fe6be9b5 100644 --- a/public/docs/ts/_cache/glossary.jade +++ b/public/docs/ts/_cache/glossary.jade @@ -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 = '' + _decorator + '' -// #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 - -// #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' : 'decorator' -- var atSym = lang === 'js' ? '' : '@' - -.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. - -.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 - -.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`) and + the root of filenames (such as `hero-list.component.ts`) 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 - -: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 - -// #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 - - - - -.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 - ++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 :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). - -.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 - -// #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' : 'decorator' -- var atSym = lang === 'js' ? '' : '@' - - -.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 - :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"). {{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 — sometimes called a "recipe" — + 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 - - :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', '') - -.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 - -.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 - - -.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#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). diff --git a/public/docs/ts/latest/glossary.jade b/public/docs/ts/latest/glossary.jade index bc9a7445b8..53fe6be9b5 100644 --- a/public/docs/ts/latest/glossary.jade +++ b/public/docs/ts/latest/glossary.jade @@ -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 = '' + _decorator + '' -// #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 - -// #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 - -: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' : 'decorator' -- var atSym = lang === 'js' ? '' : '@' - -.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. - -.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 - -.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`) and + the root of filenames (such as `hero-list.component.ts`) 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 - -: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 - -// #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 - - - - -.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#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. - +.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). - -.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 - -// #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' : 'decorator' -- var atSym = lang === 'js' ? '' : '@' - - -.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 - :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"). {{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 — sometimes called a "recipe" — + 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 - - - -: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. - :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. - -.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 - -.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). - -: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 - - -.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#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). diff --git a/public/docs/ts/latest/guide/glossary.jade b/public/docs/ts/latest/guide/glossary.jade index ca1429104e..76fb55a9ed 100644 --- a/public/docs/ts/latest/guide/glossary.jade +++ b/public/docs/ts/latest/guide/glossary.jade @@ -1 +1,5 @@ -include ../glossary +extends ../glossary + +block includes + include ../_util-fns +