From 1bcd58cee86c6e2fe7d21e486fc8ff6a5b958c22 Mon Sep 17 00:00:00 2001 From: George Kalpakas Date: Sat, 20 Jul 2019 20:40:17 +0300 Subject: [PATCH] refactor(docs-infra): remove `linenums=false` since it is now the default (#31674) PR Close #31674 --- aio/content/guide/ajs-quick-reference.md | 58 +-- aio/content/guide/animations.md | 7 +- aio/content/guide/aot-compiler.md | 16 +- aio/content/guide/app-shell.md | 8 +- aio/content/guide/architecture-components.md | 32 +- aio/content/guide/architecture-modules.md | 12 +- aio/content/guide/architecture-services.md | 44 +- aio/content/guide/attribute-directives.md | 50 +-- aio/content/guide/bootstrapping.md | 9 +- aio/content/guide/browser-support.md | 2 +- aio/content/guide/cli-builder.md | 18 +- .../guide/complex-animation-sequences.md | 8 +- aio/content/guide/component-styles.md | 19 +- .../guide/dependency-injection-in-action.md | 72 +--- .../guide/dependency-injection-navtree.md | 68 +-- .../guide/dependency-injection-providers.md | 53 +-- aio/content/guide/dependency-injection.md | 9 +- aio/content/guide/deployment.md | 16 +- aio/content/guide/deprecations.md | 2 +- aio/content/guide/displaying-data.md | 52 +-- aio/content/guide/docs-style-guide.md | 2 +- aio/content/guide/dynamic-component-loader.md | 16 +- aio/content/guide/dynamic-form.md | 12 +- aio/content/guide/feature-modules.md | 15 +- aio/content/guide/file-structure.md | 10 +- aio/content/guide/form-validation.md | 40 +- aio/content/guide/forms.md | 96 ++--- aio/content/guide/glossary.md | 2 +- .../hierarchical-dependency-injection.md | 81 ++-- aio/content/guide/http.md | 395 +++++++++--------- aio/content/guide/i18n.md | 104 ++--- aio/content/guide/lazy-loading-ngmodules.md | 20 +- aio/content/guide/lifecycle-hooks.md | 26 +- aio/content/guide/ngmodule-faq.md | 3 +- aio/content/guide/ngmodules.md | 3 +- aio/content/guide/pipes.md | 67 +-- aio/content/guide/providers.md | 9 +- aio/content/guide/reactive-forms.md | 108 ++--- aio/content/guide/reusable-animations.md | 8 +- aio/content/guide/route-animations.md | 21 +- aio/content/guide/router.md | 382 +++++------------ aio/content/guide/schematics-authoring.md | 18 +- aio/content/guide/schematics-for-libraries.md | 12 +- aio/content/guide/schematics.md | 10 +- aio/content/guide/security.md | 24 +- .../guide/service-worker-communications.md | 8 +- aio/content/guide/set-document-title.md | 2 +- aio/content/guide/singleton-services.md | 22 +- aio/content/guide/structural-directives.md | 92 +--- aio/content/guide/styleguide.md | 2 +- aio/content/guide/template-syntax.md | 324 +++++--------- aio/content/guide/testing.md | 275 +++++------- aio/content/guide/transition-and-triggers.md | 36 +- aio/content/guide/typescript-configuration.md | 8 +- aio/content/guide/universal.md | 69 ++- aio/content/guide/upgrade.md | 35 +- aio/content/guide/user-input.md | 40 +- aio/content/guide/workspace-config.md | 26 +- aio/content/start/data.md | 152 +++---- aio/content/start/forms.md | 27 +- aio/content/tutorial/toh-pt0.md | 6 +- aio/content/tutorial/toh-pt1.md | 26 +- aio/content/tutorial/toh-pt2.md | 26 +- aio/content/tutorial/toh-pt3.md | 13 +- aio/content/tutorial/toh-pt4.md | 3 +- aio/content/tutorial/toh-pt5.md | 2 +- aio/content/tutorial/toh-pt6.md | 5 +- .../remark-package/services/handlers/code.js | 4 +- .../services/renderMarkdown.spec.js | 2 +- .../api/includes/class-overview.html | 2 +- .../templates/api/includes/ngmodule.html | 2 +- .../templates/api/lib/memberHelpers.html | 2 +- .../templates/api/ngmodule.template.html | 4 +- packages/core/src/di/injectable.ts | 3 +- packages/core/src/di/interface/provider.ts | 30 +- packages/core/src/di/metadata.ts | 24 +- packages/core/src/metadata/di.ts | 27 +- packages/core/src/metadata/directives.ts | 7 +- packages/forms/src/form_builder.ts | 3 +- packages/router/src/router_state.ts | 2 +- packages/router/upgrade/src/upgrade.ts | 2 +- packages/service-worker/src/module.ts | 2 +- 82 files changed, 1257 insertions(+), 2097 deletions(-) diff --git a/aio/content/guide/ajs-quick-reference.md b/aio/content/guide/ajs-quick-reference.md index 2bc8f4531b..6625e0083d 100644 --- a/aio/content/guide/ajs-quick-reference.md +++ b/aio/content/guide/ajs-quick-reference.md @@ -66,7 +66,7 @@ The following table lists some of the key AngularJS template features with their ### Bindings/interpolation - + In Angular, a template expression in curly braces still denotes one-way binding. @@ -102,7 +102,7 @@ The following table lists some of the key AngularJS template features with their ### Pipes - + In Angular you use similar syntax with the pipe (|) character to filter output, but now you call them **pipes**. @@ -136,7 +136,7 @@ The following table lists some of the key AngularJS template features with their ### Input variables - + Angular has true template input variables that are explicitly defined using the `let` keyword. @@ -202,10 +202,10 @@ The following are some of the key AngularJS built-in directives and their equiva ### Bootstrapping - +
- + Angular doesn't have a bootstrap directive. @@ -245,7 +245,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### ngClass - + In Angular, the `ngClass` directive works similarly. @@ -291,7 +291,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### Bind to the `click` event - + AngularJS event-based directives do not exist in Angular. @@ -338,7 +338,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### Component decorator - + In Angular, the template no longer specifies its associated controller. @@ -401,7 +401,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### Bind to the `href` property - + Angular uses property binding; there is no built-in *href* directive. @@ -412,7 +412,7 @@ The following are some of the key AngularJS built-in directives and their equiva In Angular, `href` is no longer used for routing. Routing uses `routerLink`, as shown in the following example. - + For more information on routing, see the [RouterLink binding](guide/router#router-link) @@ -445,7 +445,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### *ngIf - + The `*ngIf` directive in Angular works the same as the `ng-if` directive in AngularJS. It removes @@ -480,7 +480,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### ngModel - + In Angular, **two-way binding** is denoted by `[()]`, descriptively referred to as a "banana in a box". This syntax is a shortcut for defining both property binding (from the component to the view) @@ -516,7 +516,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### *ngFor - + The `*ngFor` directive in Angular is similar to the `ng-repeat` directive in AngularJS. It repeats @@ -559,7 +559,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### Bind to the `hidden` property - + Angular uses property binding; there is no built-in *show* directive. @@ -598,7 +598,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### Bind to the `src` property - + Angular uses property binding; there is no built-in *src* directive. @@ -635,7 +635,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### ngStyle - + In Angular, the `ngStyle` directive works similarly. It sets a CSS style on an HTML element based on an expression. @@ -690,7 +690,7 @@ The following are some of the key AngularJS built-in directives and their equiva ### ngSwitch - + In Angular, the `ngSwitch` directive works similarly. @@ -765,7 +765,7 @@ For more information on pipes, see [Pipes](guide/pipes). ### currency - + The Angular `currency` pipe is similar although some of the parameters have changed. @@ -793,7 +793,7 @@ For more information on pipes, see [Pipes](guide/pipes). ### date - + The Angular `date` pipe is similar. @@ -847,7 +847,7 @@ For more information on pipes, see [Pipes](guide/pipes). ### json - + The Angular `json` pipe does the same thing. @@ -876,7 +876,7 @@ For more information on pipes, see [Pipes](guide/pipes). ### slice - + The `SlicePipe` does the same thing but the *order of the parameters is reversed*, in keeping @@ -907,7 +907,7 @@ For more information on pipes, see [Pipes](guide/pipes). ### lowercase - + The Angular `lowercase` pipe does the same thing. @@ -935,7 +935,7 @@ For more information on pipes, see [Pipes](guide/pipes). ### number - + The Angular `number` pipe is similar. @@ -1068,7 +1068,7 @@ The Angular code is shown using TypeScript. ### NgModules - + NgModules, defined with the `NgModule` decorator, serve the same purpose: @@ -1109,7 +1109,7 @@ The Angular code is shown using TypeScript. ### Component decorator - + Angular adds a decorator to the component class to provide any required metadata. @@ -1145,7 +1145,7 @@ The Angular code is shown using TypeScript. ### Component class - + In Angular, you create a component class. @@ -1184,7 +1184,7 @@ The Angular code is shown using TypeScript. ### Dependency injection - + In Angular, you pass in dependencies as arguments to the component class constructor. @@ -1254,7 +1254,7 @@ also encapsulate a style sheet within a specific component. ### Styles configuration - + With the Angular CLI, you can configure your global styles in the `angular.json` file. You can rename the extension to `.scss` to use sass. @@ -1263,7 +1263,7 @@ also encapsulate a style sheet within a specific component. In Angular, you can use the `styles` or `styleUrls` property of the `@Component` metadata to define a style sheet for a particular component. - + This allows you to set appropriate styles for individual components that won’t leak into diff --git a/aio/content/guide/animations.md b/aio/content/guide/animations.md index 1bcc9a5c2d..5222cf7556 100644 --- a/aio/content/guide/animations.md +++ b/aio/content/guide/animations.md @@ -37,8 +37,7 @@ To get started with adding Angular animations to your project, import the animat Import `BrowserAnimationsModule`, which introduces the animation capabilities into your Angular root application module. - - +
@@ -180,9 +179,7 @@ In this example, we'll name the trigger `openClose`, and attach it to the `butto Animations are defined in the metadata of the component that controls the HTML element to be animated. Put the code that defines your animations under the `animations:` property within the `@Component()` decorator. - - + When you've defined an animation trigger for a component, you can attach it to an element in that component's template by wrapping the trigger name in brackets and preceding it with an `@` symbol. Then, you can bind the trigger to a template expression using standard Angular property binding syntax as shown below, where `triggerName` is the name of the trigger, and `expression` evaluates to a defined animation state. diff --git a/aio/content/guide/aot-compiler.md b/aio/content/guide/aot-compiler.md index fb410dccc3..ce2be6ef1b 100644 --- a/aio/content/guide/aot-compiler.md +++ b/aio/content/guide/aot-compiler.md @@ -21,7 +21,7 @@ Angular offers two ways to compile your application: 1. **_Just-in-Time_ (JIT)**, which compiles your app in the browser at runtime. 1. **_Ahead-of-Time_ (AOT)**, which compiles your app at build time. -JIT compilation is the default when you run the [`ng build`](cli/build) (build only) or [`ng serve`](cli/serve) (build and serve locally) CLI commands: +JIT compilation is the default when you run the [`ng build`](cli/build) (build only) or [`ng serve`](cli/serve) (build and serve locally) CLI commands: ng build @@ -945,7 +945,7 @@ import { calculateValue } from './utilities'; To correct this error, export a function from the module and refer to the function in a `useFactory` provider instead. - + // CORRECTED import { calculateValue } from './utilities'; @@ -978,7 +978,7 @@ The compiler does not support references to variables assigned by [destructuring For example, you cannot write something like this: - + // ERROR import { configuration } from './configuration'; @@ -994,7 +994,7 @@ const {foo, bar} = configuration; To correct this error, refer to non-destructured values. - + // CORRECTED import { configuration } from './configuration'; ... @@ -1041,7 +1041,7 @@ you can finesse the problem in four steps: Here's an illustrative example. - + // CORRECTED import { Inject } from '@angular/core'; @@ -1064,7 +1064,7 @@ uses the `@Inject(WINDOW)` to generate the injection code. Angular does something similar with the `DOCUMENT` token so you can inject the browser's `document` object (or an abstraction of it, depending upon the platform in which the application runs). - + import { Inject } from '@angular/core'; import { DOCUMENT } from '@angular/platform-browser'; @@ -1101,7 +1101,7 @@ that you referenced in metadata. The compiler can understand simple enum values but not complex values such as those derived from computed properties. - + // ERROR enum Colors { Red = 1, @@ -1311,7 +1311,7 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there]( {@a tsconfig-extends} ## Configuration inheritance with extends Similar to TypeScript Compiler, Angular Compiler also supports `extends` in the `tsconfig.json` on `angularCompilerOptions`. A tsconfig file can inherit configurations from another file using the `extends` property. - The `extends` is a top level property parallel to `compilerOptions` and `angularCompilerOptions`. + The `extends` is a top level property parallel to `compilerOptions` and `angularCompilerOptions`. The configuration from the base file are loaded first, then overridden by those in the inheriting config file. Example: ```json diff --git a/aio/content/guide/app-shell.md b/aio/content/guide/app-shell.md index 1aca279f3d..5a7fb8b93f 100644 --- a/aio/content/guide/app-shell.md +++ b/aio/content/guide/app-shell.md @@ -10,7 +10,7 @@ Learn more in [The App Shell Model](https://developers.google.com/web/fundamenta ## Step 1: Prepare the application You can do this with the following CLI command: - + ng new my-app --routing @@ -20,7 +20,7 @@ For an existing application, you have to manually add the `RouterModule` and def Use the CLI to automatically create the app shell. - + ng generate app-shell --client-project my-app --universal-project server-app @@ -29,7 +29,7 @@ ng generate app-shell --client-project my-app --universal-project server-app After running this command you will notice that the `angular.json` configuration file has been updated to add two new targets, with a few other changes. - + "server": { "builder": "@angular-devkit/build-angular:server", "options": { @@ -52,7 +52,7 @@ After running this command you will notice that the `angular.json` configuration Use the CLI to build the `app-shell` target. - + ng run my-app:app-shell diff --git a/aio/content/guide/architecture-components.md b/aio/content/guide/architecture-components.md index c140abd4e9..638e04a15a 100644 --- a/aio/content/guide/architecture-components.md +++ b/aio/content/guide/architecture-components.md @@ -10,12 +10,12 @@ For example, individual components define and control each of the following view You define a component's application logic—what it does to support the view—inside a class. The class interacts with the view through an API of properties and methods. -For example, `HeroListComponent` has a `heroes` property that holds an array of heroes. -Its `selectHero()` method sets a `selectedHero` property when the user clicks to choose a hero from that list. -The component acquires the heroes from a service, which is a TypeScript [parameter property](http://www.typescriptlang.org/docs/handbook/classes.html#parameter-properties) on the constructor. +For example, `HeroListComponent` has a `heroes` property that holds an array of heroes. +Its `selectHero()` method sets a `selectedHero` property when the user clicks to choose a hero from that list. +The component acquires the heroes from a service, which is a TypeScript [parameter property](http://www.typescriptlang.org/docs/handbook/classes.html#parameter-properties) on the constructor. The service is provided to the component through the dependency injection system. - + Angular creates, updates, and destroys components as the user moves through the application. Your app can take action at each moment in this lifecycle through optional [lifecycle hooks](guide/lifecycle-hooks), like `ngOnInit()`. @@ -31,7 +31,7 @@ In addition to containing or pointing to the template, the `@Component` metadata Here's an example of basic metadata for `HeroListComponent`. - + This example shows some of the most useful `@Component` configuration options: @@ -40,7 +40,7 @@ Angular inserts an instance of the `HeroListComponent` view between those tags. * `templateUrl`: The module-relative address of this component's HTML template. Alternatively, you can provide the HTML template inline, as the value of the `template` property. This template defines the component's *host view*. -* `providers`: An array of [providers](guide/glossary#provider) for services that the component requires. In the example, this tells Angular how to provide the `HeroService` instance that the component's constructor uses to get the list of heroes to display. +* `providers`: An array of [providers](guide/glossary#provider) for services that the component requires. In the example, this tells Angular how to provide the `HeroService` instance that the component's constructor uses to get the list of heroes to display. ## Templates and views @@ -69,7 +69,7 @@ This template uses typical HTML elements like `

` and `

`, and also includ * The `*ngFor` directive tells Angular to iterate over a list. * `{{hero.name}}`, `(click)`, and `[hero]` bind program data to and from the DOM, responding to user input. See more about [data binding](#data-binding) below. -* The `` tag in the example is an element that represents a new component, `HeroDetailComponent`. +* The `` tag in the example is an element that represents a new component, `HeroDetailComponent`. `HeroDetailComponent` (code not shown) defines the hero-detail child view of `HeroListComponent`. Notice how custom components like this mix seamlessly with native HTML in the same layouts. @@ -87,7 +87,7 @@ The following diagram shows the four forms of data binding markup. Each form has This example from the `HeroListComponent` template uses three of these forms. - + * The `{{hero.name}}` [*interpolation*](guide/displaying-data#interpolation) displays the component's `hero.name` property value within the `

  • ` element. @@ -97,11 +97,11 @@ displays the component's `hero.name` property value within the `
  • ` element. * The `(click)` [*event binding*](guide/user-input#binding-to-user-input-events) calls the component's `selectHero` method when the user clicks a hero's name. -Two-way data binding (used mainly in [template-driven forms](guide/forms)) -combines property and event binding in a single notation. +Two-way data binding (used mainly in [template-driven forms](guide/forms)) +combines property and event binding in a single notation. Here's an example from the `HeroDetailComponent` template that uses two-way data binding with the `ngModel` directive. - + In two-way binding, a data property value flows to the input box from the component as with property binding. The user's changes also flow back to the component, resetting the property to the latest value, @@ -151,20 +151,20 @@ Angular templates are *dynamic*. When Angular renders them, it transforms the DO A component is technically a directive. However, components are so distinctive and central to Angular applications that Angular -defines the `@Component()` decorator, which extends the `@Directive()` decorator with +defines the `@Component()` decorator, which extends the `@Directive()` decorator with template-oriented features. -In addition to components, there are two other kinds of directives: *structural* and *attribute*. +In addition to components, there are two other kinds of directives: *structural* and *attribute*. Angular defines a number of directives of both kinds, and you can define your own using the `@Directive()` decorator. Just as for components, the metadata for a directive associates the decorated class with a `selector` element that you use to insert it into HTML. In templates, directives typically appear within an element tag as attributes, either by name or as the target of an assignment or a binding. #### Structural directives -*Structural directives* alter layout by adding, removing, and replacing elements in the DOM. +*Structural directives* alter layout by adding, removing, and replacing elements in the DOM. The example template uses two built-in structural directives to add application logic to how the view is rendered. - + * [`*ngFor`](guide/displaying-data#ngFor) is an iterative; it tells Angular to stamp out one `
  • ` per hero in the `heroes` list. * [`*ngIf`](guide/displaying-data#ngIf) is a conditional; it includes the `HeroDetail` component only if a selected hero exists. @@ -176,7 +176,7 @@ In templates they look like regular HTML attributes, hence the name. The `ngModel` directive, which implements two-way data binding, is an example of an attribute directive. `ngModel` modifies the behavior of an existing element (typically ``) by setting its display value property and responding to change events. - + Angular has more pre-defined directives that either alter the layout structure (for example, [ngSwitch](guide/template-syntax#ngSwitch)) diff --git a/aio/content/guide/architecture-modules.md b/aio/content/guide/architecture-modules.md index 88752e9ca5..cc07ae4011 100644 --- a/aio/content/guide/architecture-modules.md +++ b/aio/content/guide/architecture-modules.md @@ -23,7 +23,7 @@ An NgModule is defined by a class decorated with `@NgModule()`. The `@NgModule() Here's a simple root NgModule definition. - +
    @@ -69,9 +69,9 @@ In JavaScript each *file* is a module and all objects defined in the file belong The module declares some objects to be public by marking them with the `export` key word. Other JavaScript modules use *import statements* to access public objects from other modules. - + - +
    Learn more about the JavaScript module system on the web. @@ -87,17 +87,17 @@ Angular loads as a collection of JavaScript modules. You can think of them as li For example, import Angular's `Component` decorator from the `@angular/core` library like this. - + You also import NgModules from Angular *libraries* using JavaScript import statements. For example, the following code imports the `BrowserModule` NgModule from the `platform-browser` library. - + In the example of the simple root module above, the application module needs material from within `BrowserModule`. To access that material, add it to the `@NgModule` metadata `imports` like this. - + In this way you're using the Angular and JavaScript module systems *together*. Although it's easy to confuse the two systems, which share the common vocabulary of "imports" and "exports", you will become familiar with the different contexts in which they are used. diff --git a/aio/content/guide/architecture-services.md b/aio/content/guide/architecture-services.md index ebf44c1a17..27aaa1afe6 100644 --- a/aio/content/guide/architecture-services.md +++ b/aio/content/guide/architecture-services.md @@ -1,7 +1,7 @@ # Introduction to services and dependency injection *Service* is a broad category encompassing any value, function, or feature that an app needs. -A service is typically a class with a narrow, well-defined purpose. +A service is typically a class with a narrow, well-defined purpose. It should do something specific and do it well. Angular distinguishes components from services to increase modularity and reusability. @@ -14,9 +14,9 @@ in order to mediate between the view (rendered by the template) and the application logic (which often includes some notion of a *model*). A component can delegate certain tasks to services, such as fetching data from the server, -validating user input, or logging directly to the console. +validating user input, or logging directly to the console. By defining such processing tasks in an *injectable service class*, you make those tasks -available to any component. +available to any component. You can also make your app more adaptable by injecting different providers of the same kind of service, as appropriate in different circumstances. @@ -28,21 +28,21 @@ available to components through *dependency injection*. Here's an example of a service class that logs to the browser console. - + Services can depend on other services. For example, here's a `HeroService` that depends on the `Logger` service, and also uses `BackendService` to get heroes. That service in turn might depend on the `HttpClient` service to fetch heroes asynchronously from a server. - + ## Dependency injection (DI) Service DI is wired into the Angular framework and used everywhere to provide new components with the services or other things they need. -Components consume services; that is, you can *inject* a service into a component, giving the component access to that service class. +Components consume services; that is, you can *inject* a service into a component, giving the component access to that service class. -To define a class as a service in Angular, use the `@Injectable()` decorator to provide the metadata that allows Angular to inject it into a component as a *dependency*. -Similarly, use the `@Injectable()` decorator to indicate that a component or other class (such as another service, a pipe, or an NgModule) *has* a dependency. +To define a class as a service in Angular, use the `@Injectable()` decorator to provide the metadata that allows Angular to inject it into a component as a *dependency*. +Similarly, use the `@Injectable()` decorator to indicate that a component or other class (such as another service, a pipe, or an NgModule) *has* a dependency. * The *injector* is the main mechanism. Angular creates an application-wide injector for you during the bootstrap process, and additional injectors as needed. You don't have to create injectors. @@ -50,19 +50,19 @@ Similarly, use the `@Injectable()` decorator to indicate that a component or oth * A *provider* is an object that tells an injector how to obtain or create a dependency. -For any dependency that you need in your app, you must register a provider with the app's injector, -so that the injector can use the provider to create new instances. +For any dependency that you need in your app, you must register a provider with the app's injector, +so that the injector can use the provider to create new instances. For a service, the provider is typically the service class itself.
    -A dependency doesn't have to be a service—it could be a function, for example, or a value. +A dependency doesn't have to be a service—it could be a function, for example, or a value.
    When Angular creates a new instance of a component class, it determines which services or other dependencies that component needs by looking at the constructor parameter types. For example, the constructor of `HeroListComponent` needs `HeroService`. - + When Angular discovers that a component depends on a service, it first checks if the injector has any existing instances of that service. If a requested service instance doesn't yet exist, the injector makes one using the registered provider, and adds it to the injector before returning the service to Angular. @@ -78,26 +78,26 @@ The process of `HeroService` injection looks something like this. You must register at least one *provider* of any service you are going to use. The provider can be part of the service's own metadata, making that service available everywhere, -or you can register providers with specific modules or components. +or you can register providers with specific modules or components. You register providers in the metadata of the service (in the `@Injectable()` decorator), -or in the `@NgModule()` or `@Component()` metadata +or in the `@NgModule()` or `@Component()` metadata * By default, the Angular CLI command [`ng generate service`](cli/generate) registers a provider with the root injector for your service by including provider metadata in the `@Injectable()` decorator. The tutorial uses this method to register the provider of HeroService class definition. - ``` + ``` @Injectable({ providedIn: 'root', }) - ``` + ``` When you provide the service at the root level, Angular creates a single, shared instance of `HeroService` - and injects it into any class that asks for it. + and injects it into any class that asks for it. Registering the provider in the `@Injectable()` metadata also allows Angular to optimize an app - by removing the service from the compiled app if it isn't used. + by removing the service from the compiled app if it isn't used. * When you register a provider with a [specific NgModule](guide/architecture-modules), the same instance of a service is available to all components in that NgModule. To register at this level, use the `providers` property of the `@NgModule()` decorator, - ``` + ``` @NgModule({ providers: [ BackendService, @@ -105,12 +105,12 @@ or in the `@NgModule()` or `@Component()` metadata ], ... }) - ``` + ``` * When you register a provider at the component level, you get a new instance of the -service with each new instance of that component. +service with each new instance of that component. At the component level, register a service provider in the `providers` property of the `@Component()` metadata. - + For more detailed information, see the [Dependency Injection](guide/dependency-injection) section. diff --git a/aio/content/guide/attribute-directives.md b/aio/content/guide/attribute-directives.md index 3cfcfada88..51168afcda 100644 --- a/aio/content/guide/attribute-directives.md +++ b/aio/content/guide/attribute-directives.md @@ -37,13 +37,13 @@ This page demonstrates building a simple _appHighlight_ attribute directive to set an element's background color when the user hovers over that element. You can apply it like this: - + {@a write-directive} Please note that directives _do not_ support namespaces. - + ### Write the directive code @@ -101,7 +101,7 @@ Now edit the generated `src/app/highlight.directive.ts` to look as follows: The `import` statement specifies an additional `ElementRef` symbol from the Angular `core` library: You use the `ElementRef` in the directive's constructor -to [inject](guide/dependency-injection) a reference to the host DOM element, +to [inject](guide/dependency-injection) a reference to the host DOM element, the element to which you applied `appHighlight`. `ElementRef` grants direct access to the host DOM element @@ -140,12 +140,12 @@ and respond by setting or clearing the highlight color. Begin by adding `HostListener` to the list of imported symbols. - + Then add two eventhandlers that respond when the mouse enters or leaves, each adorned by the `HostListener` decorator. - + The `@HostListener` decorator lets you subscribe to events of the DOM element that hosts an attribute directive, the `

    ` in this case. @@ -166,7 +166,7 @@ The handlers delegate to a helper method that sets the color on the host DOM ele The helper method, `highlight`, was extracted from the constructor. The revised constructor simply declares the injected `el: ElementRef`. - + Here's the updated directive in full: @@ -187,11 +187,11 @@ Currently the highlight color is hard-coded _within_ the directive. That's infle In this section, you give the developer the power to set the highlight color while applying the directive. Begin by adding `Input` to the list of symbols imported from `@angular/core`. - + Add a `highlightColor` property to the directive class like this: - + {@a input} @@ -204,19 +204,19 @@ Without that input metadata, Angular rejects the binding; see [below](guide/attr Try it by adding the following directive binding variations to the `AppComponent` template: - + Add a `color` property to the `AppComponent`. - + Let it control the highlight color with a property binding. - + That's good, but it would be nice to _simultaneously_ apply the directive and set the color _in the same attribute_ like this. - + The `[appHighlight]` attribute binding both applies the highlighting directive to the `

    ` element and sets the directive's highlight color with a property binding. @@ -225,7 +225,7 @@ That's a crisp, compact syntax. You'll have to rename the directive's `highlightColor` property to `appHighlight` because that's now the color property binding name. - + This is disagreeable. The word, `appHighlight`, is a terrible property name and it doesn't convey the property's intent. @@ -237,23 +237,23 @@ Fortunately you can name the directive property whatever you want _and_ **_alias Restore the original property name and specify the selector as the alias in the argument to `@Input`. - + _Inside_ the directive the property is known as `highlightColor`. _Outside_ the directive, where you bind to it, it's known as `appHighlight`. You get the best of both worlds: the property name you want and the binding syntax you want: - + Now that you're binding via the alias to the `highlightColor`, modify the `onMouseEnter()` method to use that property. If someone neglects to bind to `appHighlightColor`, highlight the host element in red: - + Here's the latest version of the directive class. - + ## Write a harness to try it @@ -263,11 +263,11 @@ lets you pick the highlight color with a radio button and bind your color choice Update app.component.html as follows: - + Revise the `AppComponent.color` so that it has no initial value. - + Here are the harness and directive in action. @@ -287,12 +287,12 @@ Let the template developer set the default color. Add a second **input** property to `HighlightDirective` called `defaultColor`: - + Revise the directive's `onMouseEnter` so that it first tries to highlight with the `highlightColor`, then with the `defaultColor`, and falls back to "red" if both properties are undefined. - + How do you bind to a second property when you're already binding to the `appHighlight` attribute name? @@ -300,7 +300,7 @@ As with components, you can add as many directive property bindings as you need The developer should be able to write the following template HTML to both bind to the `AppComponent.color` and fall back to "violet" as the default color. - + Angular knows that the `defaultColor` binding belongs to the `HighlightDirective` because you made it _public_ with the `@Input` decorator. @@ -342,11 +342,11 @@ You can also experience and download the + You've seen it with an alias: - + Either way, the `@Input` decorator tells Angular that this property is _public_ and available for binding by a parent component. @@ -378,7 +378,7 @@ You can tell if `@Input` is needed by the position of the property name in a bin Now apply that reasoning to the following example: - + * The `color` property in the expression on the right belongs to the template's component. The template and its component trust each other. diff --git a/aio/content/guide/bootstrapping.md b/aio/content/guide/bootstrapping.md index 70c590f662..7dc9b0adc6 100644 --- a/aio/content/guide/bootstrapping.md +++ b/aio/content/guide/bootstrapping.md @@ -106,19 +106,16 @@ To use a directive, component, or pipe in a module, you must do a few things: Those three steps look like the following. In the file where you create your directive, export it. The following example, named `ItemDirective` is the default directive structure that the CLI generates in its own file, `item.directive.ts`: - - + The key point here is that you have to export it so you can import it elsewhere. Next, import it into the NgModule, in this example `app.module.ts`, with a JavaScript import statement: - - + And in the same file, add it to the `@NgModule` `declarations` array: - - + Now you could use your `ItemDirective` in a component. This example uses `AppModule`, but you'd do it the same way for a feature module. For more about directives, see [Attribute Directives](guide/attribute-directives) and [Structural Directives](guide/structural-directives). You'd also use the same technique for [pipes](guide/pipes) and components. diff --git a/aio/content/guide/browser-support.md b/aio/content/guide/browser-support.md index a9f355ae4a..3f6d15c901 100644 --- a/aio/content/guide/browser-support.md +++ b/aio/content/guide/browser-support.md @@ -527,7 +527,7 @@ If you are not using the CLI, add your polyfill scripts directly to the host web For example: - + <!-- pre-zone polyfills --> <script src="node_modules/core-js/client/shim.min.js"></script> <script src="node_modules/web-animations-js/web-animations.min.js"></script> diff --git a/aio/content/guide/cli-builder.md b/aio/content/guide/cli-builder.md index d78cfa4720..f7f18e3b3c 100644 --- a/aio/content/guide/cli-builder.md +++ b/aio/content/guide/cli-builder.md @@ -191,7 +191,7 @@ For our example builder, we expect the `options` value to be a `JsonObject` with We can provide the following schema for type validation of these values. - + { "$schema": "http://json-schema.org/schema", @@ -222,7 +222,7 @@ To link our builder implementation with its schema and name, we need to create a Create a file named `builders.json` file that looks like this. - + { "builders": { @@ -238,7 +238,7 @@ Create a file named `builders.json` file that looks like this. In the `package.json` file, add a `builders` key that tells the Architect tool where to find our builder definition file. - + { "name": "@example/command-runner", @@ -257,7 +257,7 @@ The first part of this is the package name (resolved using node resolution), an Using one of our `options` is very straightforward, we did this in the previous section when we accessed `options.command`. - + context.reportStatus(`Executing "${options.command}"...`); const child = childProcess.spawn(options.command, options.args, { stdio: 'pipe' }); @@ -274,7 +274,7 @@ The Architect tool uses the target definition to resolve input options for a giv The `angular.json` file has a section for each project, and the "architect" section of each project configures targets for builders used by CLI commands such as 'build', 'test', and 'lint'. By default, for example, the `build` command runs the builder `@angular-devkit/build-angular:browser` to perform the build task, and passes in default option values as specified for the `build` target in `angular.json`. - + { "myApp": { ... @@ -361,7 +361,7 @@ npm install @example/command-runner If we create a new project with `ng new builder-test`, the generated `angular.json` file looks something like this, with only default builder configurations. - + { // ... @@ -413,7 +413,7 @@ We need to update the `angular.json` file to add a target for this builder to th * The configurations key is optional, we'll leave it out for now. - + { "projects": { @@ -495,7 +495,7 @@ Use integration testing for your builder, so that you can use the Architect sche Here’s an example of a test that runs the command builder. The test uses the builder to run the `ls` command, then validates that it ran successfully and listed the proper files. - + import { Architect, ArchitectHost } from '@angular-devkit/architect'; import { TestingArchitectHost } from '@angular-devkit/architect/testing'; @@ -592,4 +592,4 @@ The CLI Builder API provides a new way of changing the behavior of the Angular C * We recommend that you use integration tests to test Architect builders. You can use unit tests to validate the logic that the builder executes. -* If your builder returns an Observable, it should clean up in the teardown logic of that Observable. \ No newline at end of file +* If your builder returns an Observable, it should clean up in the teardown logic of that Observable. diff --git a/aio/content/guide/complex-animation-sequences.md b/aio/content/guide/complex-animation-sequences.md index 5d6e5cdf1d..ed052f34ec 100644 --- a/aio/content/guide/complex-animation-sequences.md +++ b/aio/content/guide/complex-animation-sequences.md @@ -38,7 +38,7 @@ The following example demonstrates how to use `query()` and `stagger()` function * Animate each element on screen for 0.5 seconds using a custom-defined easing curve, simultaneously fading it in and un-transforming it. - + ## Parallel animation using group() function @@ -51,7 +51,7 @@ You've seen how to add a delay between each successive animation. But you may al In the following example, using groups on both `:enter` and `:leave` allow for two different timing configurations. They're applied to the same element in parallel, but run independently. - + ## Sequential vs. parallel animations @@ -74,7 +74,7 @@ The HTML template contains a trigger called `filterAnimation`. The component file contains three transitions. - + The animation does the following: @@ -101,4 +101,4 @@ You may also be interested in the following: * [Introduction to Angular animations](guide/animations) * [Transition and triggers](guide/transition-and-triggers) * [Reusable animations](guide/reusable-animations) -* [Route transition animations](guide/route-animations) \ No newline at end of file +* [Route transition animations](guide/route-animations) diff --git a/aio/content/guide/component-styles.md b/aio/content/guide/component-styles.md index ab5704bb33..a139549eab 100644 --- a/aio/content/guide/component-styles.md +++ b/aio/content/guide/component-styles.md @@ -21,8 +21,7 @@ One way to do this is to set the `styles` property in the component metadata. The `styles` property takes an array of strings that contain CSS code. Usually you give it one string, as in the following example: - - + ## Style scope @@ -71,8 +70,7 @@ Use the `:host` pseudo-class selector to target styles in the element that *host targeting elements *inside* the component's template). - - + The `:host` selector is the only way to target the host element. You can't reach the host element from inside the component with other selectors because it's not part of the @@ -83,8 +81,7 @@ including another selector inside parentheses after `:host`. The next example targets the host element again, but only when it also has the `active` CSS class. - - + ### :host-context @@ -99,8 +96,7 @@ up to the document root. The `:host-context()` selector is useful when combined The following example applies a `background-color` style to all `

    ` elements *inside* the component, only if some ancestor element has the CSS class `theme-light`. - - + ### (deprecated) `/deep/`, `>>>`, and `::ng-deep` @@ -115,9 +111,7 @@ can bleed into other components. The following example targets all `

    ` elements, from the host element down through this component to all of its child elements in the DOM. - - - + The `/deep/` combinator also has the aliases `>>>`, and `::ng-deep`. @@ -304,8 +298,7 @@ Choose from the following modes: To set the components encapsulation mode, use the `encapsulation` property in the component metadata: - - + `ShadowDom` view encapsulation only works on browsers that have native support for shadow DOM (see [Shadow DOM v1](https://caniuse.com/#feat=shadowdomv1) on the diff --git a/aio/content/guide/dependency-injection-in-action.md b/aio/content/guide/dependency-injection-in-action.md index e9d91d8a3c..e8fd63fcfe 100644 --- a/aio/content/guide/dependency-injection-in-action.md +++ b/aio/content/guide/dependency-injection-in-action.md @@ -21,18 +21,14 @@ constructor, and lets the framework provide them. The following example shows that `AppComponent` declares its dependence on `LoggerService` and `UserContext`. - - - + `UserContext` in turn depends on both `LoggerService` and `UserService`, another service that gathers information about a particular user. - - - + When Angular creates `AppComponent`, the DI framework creates an instance of `LoggerService` and starts to create `UserContextService`. @@ -185,17 +181,13 @@ This `HeroBiosAndContactsComponent` is a revision of `HeroBiosComponent` which y Focus on the template: - - - + Now there's a new `` element between the `` tags. Angular *projects*, or *transcludes*, the corresponding `HeroContactComponent` into the `HeroBioComponent` view, placing it in the `` slot of the `HeroBioComponent` template. - - - + The result is shown below, with the hero's telephone number from `HeroContactComponent` projected above the hero description. @@ -212,9 +204,7 @@ Here's `HeroContactComponent`, which demonstrates the qualifying decorators. Focus on the constructor parameters. - - - + The `@Host()` function decorating the `heroCache` constructor property ensures that you get a reference to the cache service from the parent `HeroBioComponent`. @@ -299,9 +289,7 @@ whose `nativeElement` property exposes the DOM element for the directive to mani The sample code applies the directive's `myHighlight` attribute to two `
    ` tags, first without a value (yielding the default color) and then with an assigned color value. - - - + The following image shows the effect of mousing over the `` tag. @@ -325,9 +313,7 @@ Angular passes this token to the injector and assigns the result to the paramete The following is a typical example. - - - + Angular asks the injector for the service associated with `LoggerService` @@ -386,9 +372,7 @@ You can also use a value provider in a unit test to provide mock data in place o The `HeroOfTheMonthComponent` example has two value providers. - - - + * The first provides an existing instance of the `Hero` class to use for the `Hero` token, rather than requiring the injector to create a new instance with `new` or use its own cached instance. @@ -427,9 +411,7 @@ extend the default class, or emulate the behavior of the real class in a test ca The following code shows two examples in `HeroOfTheMonthComponent`. - - - + The first provider is the *de-sugared*, expanded form of the most typical case in which the class to be created (`HeroService`) is also the provider's dependency injection token. @@ -448,9 +430,7 @@ Components outside the tree continue to receive the original `LoggerService` ins `DateLoggerService` inherits from `LoggerService`; it appends the current date/time to each message: - - - + {@a useexisting} @@ -472,15 +452,11 @@ You might want to shrink that API surface to just the members you actually need. In this example, the `MinimalLogger` [class-interface](#class-interface) reduces the API to two members: - - - + The following example puts `MinimalLogger` to use in a simplified version of `HeroOfTheMonthComponent`. - - - + The `HeroOfTheMonthComponent` constructor's `logger` parameter is typed as `MinimalLogger`, so only the `logs` and `logInfo` members are visible in a TypeScript-aware editor. @@ -532,9 +508,7 @@ The `runnersUpFactory()` returns the *provider factory function*, which can use the passed-in state value and the injected services `Hero` and `HeroService`. - - - + The provider factory function (returned by `runnersUpFactory()`) returns the actual dependency object, the string of names. @@ -578,9 +552,7 @@ as the token for a provider of `LoggerService`. `MinimalLogger` is an abstract class. - - - + An abstract class is usually a base class that you can extend. In this app, however there is no class that inherits from `MinimalLogger`. @@ -606,9 +578,7 @@ Using a class as an interface gives you the characteristics of an interface in a To minimize memory cost, however, the class should have *no implementation*. The `MinimalLogger` transpiles to this unoptimized, pre-minified JavaScript for a constructor function. - - - + Notice that it doesn't have any members. It never grows no matter how many members you add to the class, as long as those members are typed but not implemented. @@ -635,15 +605,11 @@ another token that happens to have the same name. You encountered them twice in the *Hero of the Month* example, in the *title* value provider and in the *runnersUp* factory provider. - - - + You created the `TITLE` token like this: - - - + The type parameter, while optional, conveys the dependency's type to developers and tooling. The token description is another developer aid. @@ -733,9 +699,7 @@ appear *above* the class definition. Break the circularity with `forwardRef`. - - - + - - + - - + The context for terms in an expression is a blend of the _template variables_, the directive's _context_ object (if it has one), and the component's _members_. @@ -241,8 +234,7 @@ such as an element, component, or directive. You'll see template statements in the [event binding](guide/template-syntax#event-binding) section, appearing in quotes to the right of the `=` symbol as in `(event)="statement"`. - - + A template statement *has a side effect*. That's the whole point of an event. @@ -272,8 +264,7 @@ such as an event handling method of the component instance. The *statement context* is typically the component instance. The *deleteHero* in `(click)="deleteHero()"` is a method of the data-bound component. - - + The statement context may also refer to properties of the template's own context. In the following examples, the template `$event` object, @@ -281,8 +272,7 @@ a [template input variable](guide/template-syntax#template-input-variable) (`let and a [template reference variable](guide/template-syntax#ref-vars) (`#heroForm`) are passed to an event handling method of the component. - - + Template context names take precedence over component context names. In `deleteHero(hero)` above, the `hero` is the template input variable, @@ -419,8 +409,7 @@ you modify those elements by setting element attributes with string constants. With data-binding, you can control things like the state of a button: - - + Notice that the binding is to the `disabled` property of the button's DOM element, **not** the attribute. This applies to data-binding in general. Data-binding works with *properties* of DOM elements, components, and directives, not HTML *attributes*. @@ -564,8 +553,7 @@ The following table summarizes: src, hero, and ngClass in the following: - - + @@ -580,8 +568,7 @@ The following table summarizes: click, deleteRequest, and myClick in the following: - - + @@ -594,8 +581,7 @@ The following table summarizes: Event and property - - + @@ -607,8 +593,7 @@ The following table summarizes: (the exception) - - + @@ -619,8 +604,7 @@ The following table summarizes: class property - - + @@ -631,8 +615,7 @@ The following table summarizes: style property - - + @@ -670,14 +653,12 @@ The most common property binding sets an element property to a component property value. An example is binding the `src` property of an image element to a component's `itemImageUrl` property: - - + Here's an example of binding to the `colSpan` property. Notice that it's not `colspan`, which is the attribute, spelled with a lowercase `s`. - - + For more details, see the [MDN HTMLTableCellElment](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableCellElement) documentation. @@ -686,19 +667,16 @@ For more about `colSpan` and `colspan`, see (Attribute Binding)[guide/template-s Another example is disabling a button when the component says that it `isUnchanged`: - - + Another is setting a property of a directive: - - + Yet another is setting the model property of a custom component—a great way for parent and child components to communicate: - - + ### Binding target @@ -706,13 +684,11 @@ An element property between enclosing square brackets identifies the target property. The target property in the following code is the image element's `src` property. - - + There's also the `bind-` prefix alternative: - - + In most cases, the target name is the name of a property, even @@ -723,8 +699,7 @@ Element properties may be the more common targets, but Angular looks first to see if the name is a property of a known directive, as it is in the following example: - - + Technically, Angular is matching the name to a directive `@Input()`, one of the property names listed in the directive's `inputs` array @@ -769,16 +744,13 @@ expects a number, an object if it expects an object, and so on. In the following example, the `childItem` property of the `ItemDetailComponent` expects a string, which is exactly what you're sending in the property binding: - - + You can confirm this by looking in the `ItemDetailComponent` where the `@Input` type is set to a string: - - + As you can see here, the `parentItem` in `AppComponent` is a string, which the `ItemDetailComponent` expects: - - + #### Passing in an object @@ -787,24 +759,20 @@ the syntax and thinking are the same. In this scenario, `ListItemComponent` is nested within `AppComponent` and the `item` property expects an object. - - + The `item` property is declared in the `ListItemComponent` with a type of `Item` and decorated with `@Input()`: - - + In this sample app, an `Item` is an object that has two properties; an `id` and a `name`. - - + While a list of items exists in another file, `mock-items.ts`, you can specify a different item in `app.component.ts` so that the new item will render: - - + You just have to make sure, in this case, that you're supplying an object because that's the type of `item` and is what the nested component, `ListItemComponent`, expects. @@ -818,8 +786,7 @@ The brackets, `[]`, tell Angular to evaluate the template expression. If you omit the brackets, Angular treats the string as a constant and *initializes the target property* with that string: - - + Omitting the brackets will render the string @@ -838,8 +805,7 @@ just as well for directive and component property initialization. The following example initializes the `prefix` property of the `StringInitComponent` to a fixed string, not a template expression. Angular sets it and forgets about it. - - + The `[item]` binding, on the other hand, remains a live binding to the component's `currentItem` property. @@ -848,8 +814,7 @@ The `[item]` binding, on the other hand, remains a live binding to the component You often have a choice between interpolation and property binding. The following binding pairs do the same thing: - - + Interpolation is a convenient alternative to property binding in many cases. When rendering data values as strings, there is no @@ -861,13 +826,11 @@ property to a non-string data value, you must use property binding*. Imagine the following malicious content. - - + In the component template, the content might be used with interpolation: - - + Fortunately, Angular data binding is on alert for dangerous HTML. In the above case, the HTML displays as is, and the Javascript does not execute. Angular **does not** @@ -877,8 +840,7 @@ nor property binding. In the following example, however, Angular [sanitizes](guide/security#sanitization-and-security-contexts) the values before displaying them. - - + Interpolation handles the `