From 4d46d7c1e481274ec1ab602981c7870f577ed6b2 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Wed, 14 Sep 2016 16:38:20 -0400 Subject: [PATCH] docs(glossary): copy edit See #2292 for review history. closes #2292 --- public/docs/ts/latest/glossary.jade | 178 +++++++++++++--------------- 1 file changed, 85 insertions(+), 93 deletions(-) diff --git a/public/docs/ts/latest/glossary.jade b/public/docs/ts/latest/glossary.jade index 96df4be2f1..4586fe8092 100644 --- a/public/docs/ts/latest/glossary.jade +++ b/public/docs/ts/latest/glossary.jade @@ -28,21 +28,20 @@ block includes +ifDocsFor('ts') a#aot :marked - ## Ahead of Time (AOT) Compilation + ## Ahead-of-time (AoT) compilation .l-sub-section :marked You can compile Angular applications at build-time. By compiling your application using the compiler-cli, `ngc`, you can bootstrap 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. + 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 + ## 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 the application uses - along with the list of external Angular modules that the application needs, such as `FormsModule`. + Helps you organize an application into cohesive blocks of functionality. + An Angular module identifies the components, directives, and pipes that the application uses 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`. @@ -58,14 +57,14 @@ block includes In practice, a synonym for [Decoration](#decorator). :marked - ## Attribute Directive + ## Attribute directive .l-sub-section :marked - A category of [Directive](#directive) that can listen to and modify the behavior of + 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. - A good example of an Attribute Directive is the `ngClass` directive for adding and removing CSS class names. + A good example of an attribute directive is the `ngClass` directive for adding and removing CSS class names. .l-main-section#B @@ -100,7 +99,7 @@ block includes 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 they need from the barrel. + Now a consumer can import what it needs from the barrel. code-example. import { Hero, HeroService } from '../heroes'; // index is implied :marked @@ -121,7 +120,7 @@ block includes 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 + May refer to a [dependency injection](#dependency-injection) binding between a "token", also referred to as a "key", and a dependency [provider](#provider). This more rare usage should be clear in context. @@ -130,9 +129,7 @@ block includes .l-sub-section block bootstrap-defn-top :marked - You launch an Angular application by "bootstrapping" it using the application root Angular module (`AppModule`). - Bootstrapping identifies an application's top level "root" [Component](#component), which is the first - component that is loaded for the application. For more information, see [QuickStart](!{docsLatest}/quickstart.html). + You launch an Angular application by "bootstrapping" it using the application root Angular module (`AppModule`). Bootstrapping identifies an application's top level "root" [component](#component), which is the first component that is loaded for the application. For more information, see [QuickStart](!{docsLatest}/quickstart.html). :marked You can bootstrap multiple apps in the same `index.html`, each with its own top level root. @@ -142,23 +139,21 @@ block includes .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 lowercase_. + _except the first letter, which is lowercase_. Function, property, and method names are typically spelled in camelCase. Examples include: `square`, `firstName` and `getHeroes`. Notice that `square` is an example of how you write a single word in camelCase. - This form is also known as **lower camel case**, to distinguish it from **upper camel case** which is [PascalCase](#pascalcase). + This form is also known as **lower camel case**, to distinguish it from **upper camel case**, which is [PascalCase](#pascalcase). When you see "camelCase" in this documentation it always means *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. + 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 *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). You apply the `!{_at}Component` !{_decoratorLink} to the component class, thereby attaching to the class the essential component metadata @@ -166,7 +161,7 @@ block includes as a view. Those familiar with "MVC" and "MVVM" patterns will recognize - the Component in the role of "Controller" or "View Model". + the component in the role of "controller" or "view model". .l-main-section#D :marked @@ -181,7 +176,7 @@ block includes spelled in dash-case. :marked - ## Data Binding + ## Data binding .l-sub-section :marked Applications display data values to a user and respond to user @@ -195,27 +190,25 @@ block includes Angular has a rich data binding framework with a variety of data binding operations and supporting declaration syntax. - The many forms of binding include: + Read about the forms of binding in the [Template Syntax](!{docsLatest}/guide/template-syntax.html#data-binding) page: * [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). + * [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#ngModel). - Read more about data binding in the - [Template Syntax](!{docsLatest}/guide/template-syntax.html#data-binding) chapter. +ifDocsFor('ts|dart') a#decorator a#decoration :marked - ## Decorator | Decoration + ## 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. + 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). @@ -223,7 +216,7 @@ block includes Angular has its own set of decorators to help it interoperate with your 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 the `name` property + class as an Angular [component](#component) and an `@Input` decorator applied to the `name` property of that component. The elided object argument to the `@Component` decorator would contain the pertinent component metadata. ``` @Component({...}) @@ -241,10 +234,10 @@ block includes Always include parentheses `()` when applying a decorator. :marked - ## Dependency Injection + ## Dependency injection .l-sub-section :marked - Dependency Injection is both a design pattern and a mechanism + 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. @@ -256,17 +249,17 @@ block includes part "A" relies on another part "B", you say that "A" depends on "B" and that "B" is a dependency of "A". - You can ask a "Dependency Injection System" to create "A" + You 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 + [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. + 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`). You rarely deal with tokens directly; most @@ -274,23 +267,23 @@ block includes to a token. When you write `injector.get(Foo)`, the injector returns the value associated with the token for the `Foo` class, typically an instance of `Foo` itself. - During many of its operations, Angular makes similar requests internally, such as when it creates a [`Component`](#component) for display. + During many of its operations, Angular makes similar requests internally, such 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 + 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. + 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. - Learn more in the [Dependency Injection](!{docsLatest}/guide/dependency-injection.html) page. + Read more in the [Dependency Injection](!{docsLatest}/guide/dependency-injection.html) page. :marked ## Directive .l-sub-section @@ -304,7 +297,7 @@ block includes it creates the matching directive class instance and gives the instance control over that portion of the browser DOM. - You can invent custom HTML markup (e.g., ``) to + You can invent custom HTML markup (for example, ``) to associate with your custom directives. You add this custom markup to HTML templates as if you were writing native HTML. In this way, directives become extensions of HTML itself. @@ -316,11 +309,11 @@ block includes 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 + 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 + 1. [Structural directives](#structural-directive), a directive responsible for shaping or reshaping HTML layout, typically by adding, removing, or manipulating elements and their children. @@ -336,7 +329,7 @@ block includes [ECMAScript 2016](http://www.ecma-international.org/ecma-262/7.0/) (AKA "ES2016" or "ES7") and many Angular 2 developers write their applications either in this version of the language or a dialect that strives to be - compatible with it, such as [TypeScript](#typesScript). + compatible with it, such as [TypeScript](#typescript). 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)" @@ -378,17 +371,17 @@ a#H .l-sub-section :marked A directive property that can be the ***target*** of a - [Property Binding](!{docsLatest}/guide/template-syntax.html#property-binding). + [property binding](!{docsLatest}/guide/template-syntax.html#property-binding) (explained in detail in the [Template Syntax](!{docsLatest}/guide/template-syntax.html) page). 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](!{docsLatest}/guide/template-syntax.html#inputs-outputs) page. + See the [Input and output properties](!{docsLatest}/guide/template-syntax.html#inputs-outputs) section of the [Template Syntax](!{docsLatest}/guide/template-syntax.html) page. :marked ## Interpolation .l-sub-section :marked - A form of [Property Data Binding](#data-binding) in which a + 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 @@ -398,20 +391,20 @@ a#H :marked - Read more about interpolation in the - [Template Syntax](!{docsLatest}/guide/template-syntax.html#interpolation) page. + Read more about [interpolation](!{docsLatest}/guide/template-syntax.html#interpolation) in the + [Template Syntax](!{docsLatest}/guide/template-syntax.html) page. .l-main-section#J +ifDocsFor('ts') a#jit :marked - ## Just in Time (JIT) Compilation + ## Just-in-time (JiT) compilation .l-sub-section :marked - With Angular _Just in Time_ bootstrapping you compile your components and modules in the browser + 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 using the [Ahead of Time](#aot) mode for production apps. + Consider using the [ahead-of-time](#aot) mode for production apps. .l-main-section#K :marked @@ -422,14 +415,14 @@ a#H .l-main-section#L :marked - ## Lifecycle Hooks + ## Lifecycle hooks .l-sub-section :marked - [Directives](#directive) and [Components](#component) have a lifecycle + [Directives](#directive) and [components](#component) have a lifecycle managed by Angular as it creates, updates, and destroys them. You can tap into key moments in that lifecycle by implementing - one or more of the "Lifecycle Hook" interfaces. + 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 named `ngOnInit`. @@ -456,7 +449,7 @@ a#H :marked In Angular, there are two types of modules: - [Angular modules](#angular-module). - For details and examples, see the [Angular Module](!{docsLatest}/guide/ngmodule.html) page. + For details and examples, see the [Angular Modules](!{docsLatest}/guide/ngmodule.html) page. - ES2015 modules, as described in this section. :marked @@ -503,12 +496,12 @@ a#N ## Output .l-sub-section :marked - A directive property that can be the ***target*** of an - [Event Binding](!{docsLatest}/guide/template-syntax.html#property-binding). + A directive property that can be the ***target*** of + [event binding](!{docsLatest}/guide/template-syntax.html#event-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](!{docsLatest}/guide/template-syntax.html#inputs-outputs) page. + See the [Input and output properties](!{docsLatest}/guide/template-syntax.html#inputs-outputs) section of the [Template Syntax](!{docsLatest}/guide/template-syntax.html) page. .l-main-section#P @@ -518,8 +511,7 @@ a#N :marked The practice of writing individual words, 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*. + This form is also known as **upper camel case** to distinguish it from **lower camel case**, which is simply called [camelCase](#camelcase). In this documentation, "PascalCase" means *upper camel case* and "camelCase" means *lower camel case*. :marked ## Pipe @@ -543,8 +535,8 @@ a#N ## Provider .l-sub-section :marked - A [Provider](!{_ProviderUrl}) creates a new instance of a dependency for the - [Dependency Injection](#dependency-injection) system. + 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. a#Q @@ -552,7 +544,7 @@ a#Q +ifDocsFor('ts|js') :marked - ## Reactive Forms + ## Reactive forms .l-sub-section :marked A technique for building Angular forms through code in a component. @@ -575,7 +567,7 @@ a#Q and performing other similar actions that cause the application to replace one view with another. - 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 + 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 @@ -588,31 +580,31 @@ a#Q Other views in the application likely have anchor tags or buttons with `RouterLink` directives that users can click to navigate. - For more information, see the [Component Router](!{docsLatest}/guide/router.html) page. + For more information, see the [Routing & Navigation](!{docsLatest}/guide/router.html) page. +ifDocsFor('ts|js') :marked - ## RouterModule + ## Router module .l-sub-section :marked A separate [Angular module](#angular-module) that provides the necessary service providers and directives for navigating through application views. - For more information, see the [Component Router](!{docsLatest}/guide/router.html) page. + For more information, see the [Routing & Navigation](!{docsLatest}/guide/router.html) page. :marked - ## Routing Component + ## Routing component .l-sub-section block routing-component-defn :marked - An Angular [Component](#component) with a RouterOutlet that displays views based on router navigations. + An Angular [component](#component) with a RouterOutlet that displays views based on router navigations. - For more information, see the [Component Router](!{docsLatest}/guide/router.html) page. + For more information, see the [Routing & Navigation](!{docsLatest}/guide/router.html) page. .l-main-section#S +ifDocsFor('ts|js') :marked - ## Scoped Package + ## Scoped package .l-sub-section :marked Angular modules are delivered within *scoped packages* such as `@angular/core`, `@angular/common`, `@angular/platform-browser-dynamic`, @@ -650,13 +642,13 @@ a#snake-case independent from any specific view, provide shared data or logic across components, or encapsulate external interactions. - For more information, see the [Services](!{docsLatest}/tutorial/toh-pt4.html) page. + For more information, see the [Services](!{docsLatest}/tutorial/toh-pt4.html) page of the [Tour of Heroes](!{docsLatest}/tutorial/) tutorial. :marked - ## Structural Directive + ## Structural directive .l-sub-section :marked - A category of [Directive](#directive) that can + A category of [directive](#directive) that can shape or reshape HTML layout, typically by adding, removing, or manipulating elements and their children; for example, the `ngIf` "conditional element" directive and the `ngFor` "repeater" directive. @@ -668,13 +660,13 @@ a#snake-case .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). + the support and continuing guidance of an Angular [directive](#directive), + most notably a [component](#component). +ifDocsFor('ts|js') :marked - ## Template-Driven Forms + ## Template-driven forms .l-sub-section :marked A technique for building Angular forms using HTML forms and input elements in the view. @@ -683,20 +675,20 @@ a#snake-case 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, provided you have set up a `name` attribute and two-way binding for each input. + - Behind the scenes, Angular creates a new control for each input element, provided you have set up a `name` attribute and two-way binding for each input. - The associated Angular directives are all prefixed with `ng` such as `ngForm`, `ngModel`, and `ngModelGroup`. Template-driven forms are convenient, quick, and simple. They 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. + Read about how to build template-driven forms + in the [Forms](!{docsLatest}/guide/forms.html) page. :marked - ## Template Expression + ## Template expression .l-sub-section :marked An expression is a !{_Lang}-like syntax that Angular evaluates within - a [data binding](#data-binding). + a [data binding](#data-binding). Read about how to write template expressions in the [Template Syntax](!{docsLatest}/guide/template-syntax.html#template-expressions) page. @@ -713,7 +705,7 @@ a#snake-case .l-sub-section :marked A version of JavaScript that supports most [ECMAScript 2015](#ecmascript=2015) - language features such as [Decorators](#decorator). + language features such as [decorators](#decorator). TypeScript is also noteable for its optional typing system, which gives us compile-time type checking and strong tooling support (for example, "intellisense", @@ -723,7 +715,7 @@ a#snake-case TypeScript is the preferred language for Angular 2 development although you can use other JavaScript dialects such as [ES5](#es5). - Read more about TypeScript on its [website](http://www.typescriptlang.org/). + Read more about TypeScript at [typescript.org](http://www.typescriptlang.org/). a#U .l-main-section#V @@ -735,9 +727,9 @@ a#U 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 it's often + 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 it's often convenient to refer to a component as a view. Views often contain other views and any view might be loaded and unloaded