From a771a6e0d05364160902b2e5bb421100bd55fc32 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 12 Aug 2016 11:14:44 -0700 Subject: [PATCH] chore(ts/cache): add glossary (#2098) --- public/docs/ts/_cache/glossary.jade | 700 ++++++++++++++++++++++++++++ scripts/cache.sh | 1 + 2 files changed, 701 insertions(+) create mode 100644 public/docs/ts/_cache/glossary.jade diff --git a/public/docs/ts/_cache/glossary.jade b/public/docs/ts/_cache/glossary.jade new file mode 100644 index 0000000000..50c6100cda --- /dev/null +++ b/public/docs/ts/_cache/glossary.jade @@ -0,0 +1,700 @@ +include _util-fns + +// #docregion intro +:marked + # Angular 2 Glossary + + Angular 2 has a vocabulary of its own. + Most Angular 2 terms are everyday English words + with a specific meaning within the Angular system. + + We have gathered here the most prominent terms + and a few less familiar ones that have unusual or + unexpected definitions. + + [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 + :marked + In practice a synonym for [Decoration](#decorator). +// #enddocregion a-1 +// #docregion a-2 +:marked + ## Attribute Directive +.l-sub-section + :marked + A category of [Directive](#directive) that can listen to and modify the behavior of + other HTML elements, attributes, properties, and components. They are usually represented + as HTML attributes, hence the name. + + 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 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 + +:marked + ## Binding +.l-sub-section + :marked + Almost always refers to [Data Binding](#data-binding) and the act of + binding an HTML object property to a data object property. + + May refer to a [Dependency Injection](#dependency-injection) binding + between a "token" or "key" and a dependency [provider](#provider). + This more rare usage should be clear in context. + +:marked + ## Bootstrap +.l-sub-section + :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 +: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_. + + 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*. + +:marked + ## Component +.l-sub-section + :marked + An Angular class responsible for exposing data + to a [View](#view) and handling most of the view’s display + and user-interaction logic. + + 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 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 +: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`. + + This form is also known as [kebab-case](#kebab-case). + +:marked + ## Data Binding +.l-sub-section + :marked + Applications display data values to a user and respond to user + actions (clicks, touches, keystrokes). + + We could push application data values into HTML, attach + event listeners, pull changed values from the screen, and + update application data values ... all by hand. + + Or we could declare the relationship between an HTML widget + and an application data source ... and let a data binding + framework handle the details. + + Data Binding is that second approach. Angular has a rich + data binding framework with a variety of data binding + 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) + + Learn more about data binding in the + [Template Syntax](/docs/ts/latest/guide/template-syntax.html#data-binding) chapter. + +// #enddocregion d1 + +:marked + ## Decorator | Decoration +.l-sub-section + :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). + + 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. + + .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 + :marked + Dependency Injection is both a design pattern and a mechanism + for creating and delivering parts of an application to other + parts of an application that request them. + + Angular developers prefer to build applications by defining many simple parts + that each do one thing well and then wire them together at runtime. + + These parts often rely on other parts. An Angular [Component](#component) + part might rely on a service part to get data or perform a calculation. When a + part "A" relies on another part "B", we say that "A" depends on "B" and + that "B" is a dependency of "A". + + We can ask a "Dependency Injection System" to create "A" + for us and handle all the dependencies. + If "A" needs "B" and "B" needs "C", the system resolves that chain of dependencies + and returns a fully prepared instance of "A". + + Angular provides and relies upon its own sophisticated + [Dependency Injection](dependency-injection.html) system + to assemble and run applications by "injecting" application parts + into other application parts where and when needed. + + At the core there is an [`Injector`](#injector) that returns dependency values on request. + The expression `injector.get(token)` returns the value associated with the given token. + + A token is an Angular type (`OpaqueToken`). We rarely deal with tokens directly; most + methods accept a class name (`Foo`) or a string ("foo") and Angular converts it + to a token. When we write `injector.get(Foo)`, the injector returns + the value associated with the token for the `Foo` class, typically an instance of `Foo` itself. + + Angular makes similar requests internally during many of its operations + as when it creates a [`Component`](#component) for display. + + The `Injector` maintains an internal map of tokens to dependency values. + If the `Injector` can't find a value for a given token, it creates + a new value using a `Provider` for that token. + + A [Provider](#provider) is a recipe for + creating new instances of a dependency value associated with a particular token. + + An injector can only create a value for a given token if it has + a `Provider` for that token in its internal provider registry. + 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. + + Learn more in the [Dependency Injection](/docs/ts/latest/guide/dependency-injection.html) chapter. +:marked + ## Directive +.l-sub-section + :marked + An Angular class responsible for creating, re-shaping, and interacting with HTML elements + in the browser DOM. Directives are Angular's most fundamental feature. + + A Directive is almost always associated with an HTML element or attribute. + We often refer to such an element or attribute as the directive itself. + When Angular finds a directive in an HTML template, + it creates the matching directive class instance + and gives that instance control over that portion of the browser DOM. + + Developers can invent custom HTML markup (e.g., ``) to + associate with their custom directives. They add this custom markup to HTML templates + as if they were writing native HTML. In this way, directives become extensions of + HTML itself. + + Directives fall into one of three categories: + + 1. [Components](#component) that combine application logic with an HTML template to + render application [views]. Components are usually represented as HTML elements. + They are the building blocks of an Angular application and the + developer can expect to write a lot of them. + + 1. [Attribute Directives](#attribute-directive) that can listen to and modify the behavior of + other HTML elements, attributes, properties, and components. They are usually represented + as HTML attributes, hence the name. + + 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 +:marked + ## ECMAScript +.l-sub-section + :marked + 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 + 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)" + 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 + :marked + Short hand for "[ECMAScript 2015](#ecmascript=2015)". +:marked + ## ES6 +.l-sub-section + :marked + Short hand for "[ECMAScript 2015](#ecmascript=2015)". +:marked + ## ES5 +.l-sub-section + :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 +:marked + ## Injector +.l-sub-section + :marked + An object in the Angular [dependency injection system](#dependency-injection) + that can find a named "dependency" in its cache or create such a thing + with a registered [provider](#provider). + +:marked + ## Input +.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). + 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. + +:marked + ## Interpolation +.l-sub-section + :marked + A form of [Property Data Binding](#data-binding) in which a + [template expression](#template-expression) between double-curly braces + renders as text. That text may be concatenated with neighboring text + before it is assigned to an element property + or displayed between element tags as in this example. + + code-example(language="html" escape="html"). + + + :marked + Learn more about interpolation in the + [Template Syntax](/docs/ts/latest/guide/template-syntax.html#interpolation) chapter. + + + + +.l-main-section + +: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). + + +.l-main-section +:marked + ## Lifecycle Hooks +.l-sub-section + :marked + [Directives](#directive) and [Components](#component) have a lifecycle + managed by Angular as it creates, updates and destroys them. + + Developers can tap into key moments in that lifecycle by implementing + one or more of the "Lifecycle Hook" interfaces. + + Each interface has a single hook method whose name is the interface name prefixed with `ng`. + For example, the `OnInit` interface has a hook method names `ngOnInit`. + + Angular calls these hook methods in the following order: + * `ngOnChanges` - called when an [input](#input)/[output](#output) binding values change + * `ngOnInit` - after the first `ngOnChanges` + * `ngDoCheck` - developer's custom change detection + * `ngAfterContentInit` - after component content initialized + * `ngAfterContentChecked` - after every check of component content + * `ngAfterViewInit` - after component's view(s) are initialized + * `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 + +// #docregion m1 + +// #enddocregion m1 +// #docregion m2 +.l-main-section +:marked + ## Module +.l-sub-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`. + +// #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). + 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. + +.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`. + + 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*. + +:marked + ## Pipe +.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 + name in our HTML to declaratively transform values on screen. + + Here's an example that uses the built-in `currency` pipe to display + a numeric value in the local currency. + + code-example(language="html" escape="html"). + {{product.price | currency}} + :marked + Learn more in the chapter on [pipes](/docs/ts/latest/guide/pipes.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. + + 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. + + There are other ways to create tokens and recipes. + See [Dependency Injection](#dependency-injection) chapter to learn more. + +.l-main-section + + +:marked + ## Router +.l-sub-section + :marked + Most applications consist of many screens or [views](#view). + The user navigates among them by clicking links and buttons + 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 + and managing the entire view navigation process including the creation and destruction + of views. +:marked + ## Routing Component +.l-sub-section + :marked + A [Component](#component) with an attached 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. + + 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. + + +.l-main-section +// #enddocregion n-s-1 +:marked + ## 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`. + + A [*scoped package*](https://docs.npmjs.com/misc/scope) is a way to group related *npm* packages. + + We import a scoped package the same way we'd import a *normal* package. + The only difference, from a consumer perspective, + is that the package name begins with the Angular *scope name*, `@angular`. + + +makeExcerpt('architecture/ts/app/app.component.ts', 'import', '') +// #docregion n-s-2 + +:marked + ## Structural Directive +.l-sub-section + :marked + A category of [Directive](#directive) that can + shape or re-shape HTML layout, typically by adding, removing, or manipulating + elements and their children. + + 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 +:marked + ## Template +.l-sub-section + :marked + A template is a chunk of HTML that Angular uses to render a [view](#view) with + 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). + +:marked + ## Template Expression +.l-sub-section + :marked + An expression in a JavaScript-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. + +// #enddocregion t1 +// #docregion t2 +:marked + ## Transpile +.l-sub-section + :marked + The process of transforming code written in one form of JavaScript + (e.g., TypeScript) into another form of JavaScript (e.g., [ES5](#es5)). + + :marked + ## TypeScript +.l-sub-section + :marked + A version of JavaScript that supports most [ECMAScript 2015](#ecmascript=2015) + language features and many features that may arrive in future versions + of JavaScript such as [Decorators](#decorator). + + TypeScript is also noteable for its optional typing system which gives + us compile-time type-checking and strong tooling support (e.g. "intellisense", + code completion, refactoring, and intelligent search). Many code editors + and IDEs support TypeScript either natively or with plugins. + + 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 +:marked + ## View +.l-sub-section + :marked + A view is a portion of the screen that displays information and responds + to user actions such as clicks, mouse moves, and keystrokes. + + Angular renders a view under the control of one or more [Directives](#directive), + especially [Component](#component) directives and their companion [Templates](#template). + The Component plays such a prominent role that we often + find it convenient to refer to a component as a view. + + Views often contain other views and any view might be loaded and unloaded + dynamically as the user navigates through the application, typically + under the control of a [router](#router). + +.l-main-section + + + + +:marked + ## Zone +.l-sub-section + :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. + + 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). + + Learn more about zones in this + [Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). +// #enddocregion u-z diff --git a/scripts/cache.sh b/scripts/cache.sh index dda45285a9..1c1ad7c351 100755 --- a/scripts/cache.sh +++ b/scripts/cache.sh @@ -19,6 +19,7 @@ guide/security.jade guide/server-communication.jade guide/structural-directives.jade guide/template-syntax.jade +glossary.jade quickstart.jade tutorial/toh-pt6.jade"