docs: edit to remove jargon (#41282)

PR Close #41282
This commit is contained in:
Teri Glover 2021-03-19 19:03:22 +00:00 committed by Zach Arend
parent 99f5b872e1
commit 57540f0e75
15 changed files with 100 additions and 79 deletions

View File

@ -334,7 +334,7 @@ However, if `dirWithHostBinding` sets its binding to `null`, the `width` propert
There are cases where you need to differentiate the behavior of a [Component](api/core/Component) or [Directive](api/core/Directive) based on a static value set on the host element as an HTML attribute. For example, you might have a directive that needs to know the `type` of a `<button>` or `<input>` element. There are cases where you need to differentiate the behavior of a [Component](api/core/Component) or [Directive](api/core/Directive) based on a static value set on the host element as an HTML attribute. For example, you might have a directive that needs to know the `type` of a `<button>` or `<input>` element.
The [Attribute](api/core/Attribute) parameter decorator is great for passing the value of an HTML attribute to a component/directive constructor via [dependency injection](guide/dependency-injection). The [Attribute](api/core/Attribute) parameter decorator is great for passing the value of an HTML attribute to a component/directive constructor using [dependency injection](guide/dependency-injection).
<div class="alert is-helpful"> <div class="alert is-helpful">

View File

@ -227,7 +227,7 @@ Test that clicking the *Agree* and *Disagree* buttons update the appropriate cou
## Parent interacts with child via *local variable* ## Parent interacts with child using *local variable*
A parent component cannot use data binding to read child properties A parent component cannot use data binding to read child properties
or invoke child methods. You can do both or invoke child methods. You can do both
@ -296,7 +296,7 @@ Test also that clicking the *Stop* button pauses the countdown timer:
## Parent calls an _@ViewChild()_ ## Parent calls an _@ViewChild()_
The *local variable* approach is simple and easy. But it is limited because The *local variable* approach is easy. But it is limited because
the parent-child wiring must be done entirely within the parent template. the parent-child wiring must be done entirely within the parent template.
The parent component *itself* has no access to the child. The parent component *itself* has no access to the child.
@ -335,7 +335,7 @@ It takes a bit more work to get the child view into the parent component *class*
First, you have to import references to the `ViewChild` decorator and the `AfterViewInit` lifecycle hook. First, you have to import references to the `ViewChild` decorator and the `AfterViewInit` lifecycle hook.
Next, inject the child `CountdownTimerComponent` into the private `timerComponent` property Next, inject the child `CountdownTimerComponent` into the private `timerComponent` property
via the `@ViewChild` property decoration. using the `@ViewChild` property decoration.
The `#timer` local variable is gone from the component metadata. The `#timer` local variable is gone from the component metadata.
Instead, bind the buttons to the parent component's own `start` and `stop` methods and Instead, bind the buttons to the parent component's own `start` and `stop` methods and
@ -350,7 +350,7 @@ So it displays `0` seconds initially.
Then Angular calls the `ngAfterViewInit` lifecycle hook at which time it is *too late* Then Angular calls the `ngAfterViewInit` lifecycle hook at which time it is *too late*
to update the parent view's display of the countdown seconds. to update the parent view's display of the countdown seconds.
Angular's unidirectional data flow rule prevents updating the parent view's Angular's unidirectional data flow rule prevents updating the parent view's
in the same cycle. The app has to *wait one turn* before it can display the seconds. in the same cycle. The application has to *wait one turn* before it can display the seconds.
Use `setTimeout()` to wait one tick and then revise the `seconds()` method so Use `setTimeout()` to wait one tick and then revise the `seconds()` method so
that it takes future values from the timer component. that it takes future values from the timer component.
@ -363,7 +363,7 @@ Use [the same countdown timer tests](guide/component-interaction#countdown-tests
{@a bidirectional-service} {@a bidirectional-service}
## Parent and children communicate via a service ## Parent and children communicate using a service
A parent component and its children share a service whose interface enables bi-directional communication A parent component and its children share a service whose interface enables bi-directional communication
*within the family*. *within the family*.
@ -405,8 +405,8 @@ Each `AstronautComponent` is a child of the `MissionControlComponent` and theref
Notice that this example captures the `subscription` and `unsubscribe()` when the `AstronautComponent` is destroyed. Notice that this example captures the `subscription` and `unsubscribe()` when the `AstronautComponent` is destroyed.
This is a memory-leak guard step. There is no actual risk in this app because the This is a memory-leak guard step. There is no actual risk in this application because the
lifetime of a `AstronautComponent` is the same as the lifetime of the app itself. lifetime of a `AstronautComponent` is the same as the lifetime of the application itself.
That *would not* always be true in a more complex application. That *would not* always be true in a more complex application.
You don't add this guard to the `MissionControlComponent` because, as the parent, You don't add this guard to the `MissionControlComponent` because, as the parent,

View File

@ -187,7 +187,7 @@ without making any hardcoded assumptions about specific questions.
It adds both control metadata and validation criteria dynamically. It adds both control metadata and validation criteria dynamically.
To ensure valid input, the *Save* button is disabled until the form is in a valid state. To ensure valid input, the *Save* button is disabled until the form is in a valid state.
When the form is valid, you can click *Save* and the app renders the current form values as JSON. When the form is valid, you can click *Save* and the application renders the current form values as JSON.
The following figure shows the final form. The following figure shows the final form.

View File

@ -4,7 +4,7 @@ _Angular elements_ are Angular components packaged as _custom elements_ (also ca
<div class="alert is-helpful"> <div class="alert is-helpful">
For the sample app that this page describes, see the <live-example></live-example>. For the sample application that this page describes, see the <live-example></live-example>.
</div> </div>
@ -29,13 +29,13 @@ Creating a custom element is simple and straightforward, and automatically conne
Custom elements bootstrap themselves - they start automatically when they are added to the DOM, and are automatically destroyed when removed from the DOM. Once a custom element is added to the DOM for any page, it looks and behaves like any other HTML element, and does not require any special knowledge of Angular terms or usage conventions. Custom elements bootstrap themselves - they start automatically when they are added to the DOM, and are automatically destroyed when removed from the DOM. Once a custom element is added to the DOM for any page, it looks and behaves like any other HTML element, and does not require any special knowledge of Angular terms or usage conventions.
- <b>Easy dynamic content in an Angular app</b> - <b>Easy dynamic content in an Angular application</b>
Transforming a component to a custom element provides an easy path to creating dynamic HTML content in your Angular app. HTML content that you add directly to the DOM in an Angular app is normally displayed without Angular processing, unless you define a _dynamic component_, adding your own code to connect the HTML tag to your app data, and participate in change detection. With a custom element, all of that wiring is taken care of automatically. Transforming a component to a custom element provides an easy path to creating dynamic HTML content in your Angular application. HTML content that you add directly to the DOM in an Angular application is normally displayed without Angular processing, unless you define a _dynamic component_, adding your own code to connect the HTML tag to your application data, and participate in change detection. With a custom element, all of that wiring is taken care of automatically.
- <b>Content-rich applications</b> - <b>Content-rich applications</b>
If you have a content-rich app, such as the Angular app that presents this documentation, custom elements let you give your content providers sophisticated Angular functionality without requiring knowledge of Angular. For example, an Angular guide like this one is added directly to the DOM by the Angular navigation tools, but can include special elements like `<code-snippet>` that perform complex operations. All you need to tell your content provider is the syntax of your custom element. They don't need to know anything about Angular, or anything about your component's data structures or implementation. If you have a content-rich application, such as the Angular app that presents this documentation, custom elements let you give your content providers sophisticated Angular functionality without requiring knowledge of Angular. For example, an Angular guide like this one is added directly to the DOM by the Angular navigation tools, but can include special elements like `<code-snippet>` that perform complex operations. All you need to tell your content provider is the syntax of your custom element. They don't need to know anything about Angular, or anything about your component's data structures or implementation.
### How it works ### How it works
@ -140,16 +140,16 @@ ng add @angular/elements --project=*your_project_name*
## Example: A Popup Service ## Example: A Popup Service
Previously, when you wanted to add a component to an app at runtime, you had to define a _dynamic component_, and then you would have to load it, attach it to an element in the DOM, and wire up all of the dependencies, change detection, and event handling, as described in [Dynamic Component Loader](guide/dynamic-component-loader). Previously, when you wanted to add a component to an application at runtime, you had to define a _dynamic component_, and then you would have to load it, attach it to an element in the DOM, and wire up all of the dependencies, change detection, and event handling, as described in [Dynamic Component Loader](guide/dynamic-component-loader).
Using an Angular custom element makes the process much simpler and more transparent, by providing all of the infrastructure and framework automatically&mdash;all you have to do is define the kind of event handling you want. (You do still have to exclude the component from compilation, if you are not going to use it in your app.) Using an Angular custom element makes the process much simpler and more transparent, by providing all of the infrastructure and framework automatically&mdash;all you have to do is define the kind of event handling you want. (You do still have to exclude the component from compilation, if you are not going to use it in your application.)
The Popup Service example app (shown below) defines a component that you can either load dynamically or convert to a custom element. The Popup Service example application (shown below) defines a component that you can either load dynamically or convert to a custom element.
- `popup.component.ts` defines a simple pop-up element that displays an input message, with some animation and styling. - `popup.component.ts` defines a simple pop-up element that displays an input message, with some animation and styling.
- `popup.service.ts` creates an injectable service that provides two different ways to invoke the PopupComponent; as a dynamic component, or as a custom element. Notice how much more setup is required for the dynamic-loading method. - `popup.service.ts` creates an injectable service that provides two different ways to invoke the PopupComponent; as a dynamic component, or as a custom element. Notice how much more setup is required for the dynamic-loading method.
- `app.module.ts` adds the PopupComponent in the module's `entryComponents` list, to exclude it from compilation and avoid startup warnings or errors. - `app.module.ts` adds the PopupComponent in the module's `entryComponents` list, to exclude it from compilation and avoid startup warnings or errors.
- `app.component.ts` defines the app's root component, which uses the PopupService to add the pop-up to the DOM at run time. When the app runs, the root component's constructor converts PopupComponent to a custom element. - `app.component.ts` defines the application's root component, which uses the PopupService to add the pop-up to the DOM at run time. When the application runs, the root component's constructor converts PopupComponent to a custom element.
For comparison, the demo shows both methods. One button adds the popup using the dynamic-loading method, and the other uses the custom element. You can see that the result is the same; only the preparation is different. For comparison, the demo shows both methods. One button adds the popup using the dynamic-loading method, and the other uses the custom element. You can see that the result is the same; only the preparation is different.

View File

@ -385,7 +385,7 @@ You can't touch the implementation of a native `<div>`, or modify a third party
You can, however watch these elements with a directive. You can, however watch these elements with a directive.
The directive defines `ngOnInit()` and `ngOnDestroy()` hooks The directive defines `ngOnInit()` and `ngOnDestroy()` hooks
that log messages to the parent via an injected `LoggerService`. that log messages to the parent using an injected `LoggerService`.
<code-example path="lifecycle-hooks/src/app/spy.directive.ts" region="spy-directive" header="src/app/spy.directive.ts"></code-example> <code-example path="lifecycle-hooks/src/app/spy.directive.ts" region="spy-directive" header="src/app/spy.directive.ts"></code-example>
@ -471,7 +471,7 @@ The `AfterViewComponent` displays this child view *within its template*:
<code-example path="lifecycle-hooks/src/app/after-view.component.ts" region="template" header="AfterViewComponent (template)"></code-example> <code-example path="lifecycle-hooks/src/app/after-view.component.ts" region="template" header="AfterViewComponent (template)"></code-example>
The following hooks take action based on changing values *within the child view*, The following hooks take action based on changing values *within the child view*,
which can only be reached by querying for the child view via the property decorated with which can only be reached by querying for the child view using the property decorated with
[@ViewChild](api/core/ViewChild). [@ViewChild](api/core/ViewChild).
<code-example path="lifecycle-hooks/src/app/after-view.component.ts" region="hooks" header="AfterViewComponent (class excerpts)"></code-example> <code-example path="lifecycle-hooks/src/app/after-view.component.ts" region="hooks" header="AfterViewComponent (class excerpts)"></code-example>
@ -559,7 +559,7 @@ appear *within* the component's template.
projected into the component. projected into the component.
The following *AfterContent* hooks take action based on changing values in a *content child*, The following *AfterContent* hooks take action based on changing values in a *content child*,
which can only be reached by querying for them via the property decorated with which can only be reached by querying for them using the property decorated with
[@ContentChild](api/core/ContentChild). [@ContentChild](api/core/ContentChild).
<code-example path="lifecycle-hooks/src/app/after-content.component.ts" region="hooks" header="AfterContentComponent (class excerpts)"></code-example> <code-example path="lifecycle-hooks/src/app/after-content.component.ts" region="hooks" header="AfterContentComponent (class excerpts)"></code-example>

View File

@ -6,7 +6,7 @@ For example, you would use a pipe to show a date as **April 15, 1988** rather th
<div class="alert is-helpful"> <div class="alert is-helpful">
For the sample app used in this topic, see the <live-example></live-example>. For the sample application used in this topic, see the <live-example></live-example>.
</div> </div>
@ -153,7 +153,7 @@ Use `name` in template expressions as you would for a built-in pipe.
<div class="alert is-important"> <div class="alert is-important">
* Include your pipe in the `declarations` field of the `NgModule` metadata in order for it to be available to a template. See the `app.module.ts` file in the example app (<live-example></live-example>). For details, see [NgModules](guide/ngmodules "NgModules introduction"). * Include your pipe in the `declarations` field of the `NgModule` metadata in order for it to be available to a template. See the `app.module.ts` file in the example application (<live-example></live-example>). For details, see [NgModules](guide/ngmodules "NgModules introduction").
* Register your custom pipes. The [Angular CLI](cli "CLI Overview and Command Reference") [`ng generate pipe`](cli/generate#pipe "ng generate pipe in the CLI Command Reference") command registers the pipe automatically. * Register your custom pipes. The [Angular CLI](cli "CLI Overview and Command Reference") [`ng generate pipe`](cli/generate#pipe "ng generate pipe in the CLI Command Reference") command registers the pipe automatically.
</div> </div>
@ -252,7 +252,7 @@ Angular updates the display every time the user adds a hero.
If the user clicks the **Reset** button, Angular replaces `heroes` with a new array of the original heroes and updates the display. If the user clicks the **Reset** button, Angular replaces `heroes` with a new array of the original heroes and updates the display.
If you add the ability to remove or change a hero, Angular would detect those changes and update the display as well. If you add the ability to remove or change a hero, Angular would detect those changes and update the display as well.
However, executing a pipe to update the display with every change would slow down your app's performance. However, executing a pipe to update the display with every change would slow down your application's performance.
So Angular uses a faster change-detection algorithm for executing a pipe, as described in the next section. So Angular uses a faster change-detection algorithm for executing a pipe, as described in the next section.
{@a pure-and-impure-pipes} {@a pure-and-impure-pipes}
@ -291,7 +291,7 @@ The tabs for the example show the following:
</code-pane> </code-pane>
</code-tabs> </code-tabs>
The app now shows unexpected behavior: When the user adds flying heroes, none of them appear under "Heroes who fly." The application now shows unexpected behavior: When the user adds flying heroes, none of them appear under "Heroes who fly."
This happens because the code that adds a hero does so by pushing it onto the `heroes` array: This happens because the code that adds a hero does so by pushing it onto the `heroes` array:
<code-example path="pipes/src/app/flying-heroes.component.ts" region="push" header="src/app/flying-heroes.component.ts"></code-example> <code-example path="pipes/src/app/flying-heroes.component.ts" region="push" header="src/app/flying-heroes.component.ts"></code-example>
@ -327,7 +327,7 @@ Angular executes an impure pipe every time it detects a change with every keystr
<div class="alert is-important"> <div class="alert is-important">
While an impure pipe can be useful, be careful using one. A long-running impure pipe could dramatically slow down your app. While an impure pipe can be useful, be careful using one. A long-running impure pipe could dramatically slow down your application.
</div> </div>

View File

@ -32,7 +32,7 @@ Template-driven forms allow direct access to modify data in your template, but a
There are three steps to using form controls. There are three steps to using form controls.
1. Register the reactive forms module in your app. This module declares the reactive-form directives that you need to use reactive forms. 1. Register the reactive forms module in your application. This module declares the reactive-form directives that you need to use reactive forms.
2. Generate a new `FormControl` instance and save it in the component. 2. Generate a new `FormControl` instance and save it in the component.
3. Register the `FormControl` in the template. 3. Register the `FormControl` in the template.

View File

@ -1,12 +1,33 @@
# Common Routing Tasks # Common Routing Tasks
<<<<<<< HEAD
This topic describes how to implement many of the common tasks associated with adding the Angular router to your application. This topic describes how to implement many of the common tasks associated with adding the Angular router to your application.
=======
In a single-page application, you change what the user sees by showing or hiding portions of the display that correspond to particular components, rather than going out to the server to get a new page.
As users perform application tasks, they need to move between the different [views](guide/glossary#view "Definition of view") that you have defined.
To handle the navigation from one [view](guide/glossary#view) to the next, you use the Angular **`Router`**.
The **`Router`** enables navigation by interpreting a browser URL as an instruction to change the view.
To explore a sample application featuring the router's primary features, see the <live-example></live-example>.
## Prerequisites
Before creating a route, you should be familiar with the following:
* [Basics of components](guide/architecture-components)
* [Basics of templates](guide/glossary#template)
* An Angular app&mdash;you can generate a basic Angular application using the [Angular CLI](cli).
For an introduction to Angular with a ready-made app, see [Getting Started](start).
For a more in-depth experience of building an Angular app, see the [Tour of Heroes](tutorial) tutorial. Both guide you through using component classes and templates.
>>>>>>> 9112c24ec1 (docs: edit to remove jargon)
{@a basics} {@a basics}
## Generate an app with routing enabled ## Generate an application with routing enabled
The following command uses the Angular CLI to generate a basic Angular app with an app routing module, called `AppRoutingModule`, which is an NgModule where you can configure your routes. The following command uses the Angular CLI to generate a basic Angular application with an app routing module, called `AppRoutingModule`, which is an NgModule where you can configure your routes.
The app name in the following example is `routing-app`. The application name in the following example is `routing-app`.
<code-example language="sh"> <code-example language="sh">
ng new routing-app --routing ng new routing-app --routing
@ -17,7 +38,7 @@ For this example, accept the default of `CSS`.
### Adding components for routing ### Adding components for routing
To use the Angular router, an app needs to have at least two components so that it can navigate from one to the other. To create a component using the CLI, enter the following at the command line where `first` is the name of your component: To use the Angular router, an application needs to have at least two components so that it can navigate from one to the other. To create a component using the CLI, enter the following at the command line where `first` is the name of your component:
<code-example language="sh"> <code-example language="sh">
ng generate component first ng generate component first
@ -38,7 +59,7 @@ The CLI automatically appends `Component`, so if you were to write `first-compon
#### `<base href>` #### `<base href>`
This guide works with a CLI-generated Angular app. This guide works with a CLI-generated Angular application.
If you are working manually, make sure that you have `<base href="/">` in the `<head>` of your index.html file. If you are working manually, make sure that you have `<base href="/">` in the `<head>` of your index.html file.
This assumes that the `app` folder is the application root, and uses `"/"`. This assumes that the `app` folder is the application root, and uses `"/"`.
@ -67,7 +88,7 @@ There are three fundamental building blocks to creating a route.
Import the `AppRoutingModule` into `AppModule` and add it to the `imports` array. Import the `AppRoutingModule` into `AppModule` and add it to the `imports` array.
The Angular CLI performs this step for you. The Angular CLI performs this step for you.
However, if you are creating an app manually or working with an existing, non-CLI app, verify that the imports and configuration are correct. However, if you are creating an application manually or working with an existing, non-CLI application, verify that the imports and configuration are correct.
The following is the default `AppModule` using the CLI with the `--routing` flag. The following is the default `AppModule` using the CLI with the `--routing` flag.
<code-example path="router/src/app/app.module.8.ts" header="Default CLI AppModule with routing"> <code-example path="router/src/app/app.module.8.ts" header="Default CLI AppModule with routing">
@ -262,7 +283,7 @@ The `goToItems()` method interprets the destination URI as relative to the activ
## Accessing query parameters and fragments ## Accessing query parameters and fragments
Sometimes, a feature of your application requires accessing a part of a route, such as a query parameter or a fragment. The Tour of Heroes app at this stage in the tutorial uses a list view in which you can click on a hero to see details. The router uses an `id` to show the correct hero's details. Sometimes, a feature of your application requires accessing a part of a route, such as a query parameter or a fragment. The Tour of Heroes application at this stage in the tutorial uses a list view in which you can click on a hero to see details. The router uses an `id` to show the correct hero's details.
First, import the following members in the component you want to navigate from. First, import the following members in the component you want to navigate from.
@ -338,14 +359,14 @@ Inject `ActivatedRoute` and `Router` in the constructor of the component class s
## Lazy loading ## Lazy loading
You can configure your routes to lazy load modules, which means that Angular only loads modules as needed, rather than loading all modules when the app launches. You can configure your routes to lazy load modules, which means that Angular only loads modules as needed, rather than loading all modules when the application launches.
Additionally, you can preload parts of your app in the background to improve the user experience. Additionally, you can preload parts of your application in the background to improve the user experience.
For more information on lazy loading and preloading see the dedicated guide [Lazy loading NgModules](guide/lazy-loading-ngmodules). For more information on lazy loading and preloading see the dedicated guide [Lazy loading NgModules](guide/lazy-loading-ngmodules).
## Preventing unauthorized access ## Preventing unauthorized access
Use route guards to prevent users from navigating to parts of an app without authorization. Use route guards to prevent users from navigating to parts of an application without authorization.
The following route guards are available in Angular: The following route guards are available in Angular:
* [`CanActivate`](api/router/CanActivate) * [`CanActivate`](api/router/CanActivate)
@ -408,7 +429,7 @@ You can provide optional route parameters in an object, as in `{ foo: 'foo' }`:
<code-example path="router/src/app/app.component.3.ts" header="src/app/app.component.ts (cc-query-params)" region="cc-query-params"></code-example> <code-example path="router/src/app/app.component.3.ts" header="src/app/app.component.ts (cc-query-params)" region="cc-query-params"></code-example>
These three examples cover the needs of an app with one level of routing. These three examples cover the needs of an application with one level of routing.
However, with a child router, such as in the crisis center, you create new link array possibilities. However, with a child router, such as in the crisis center, you create new link array possibilities.
The following minimal `RouterLink` example builds upon a specified [default child route](guide/router-tutorial-toh#a-crisis-center-with-child-routes) for the crisis center. The following minimal `RouterLink` example builds upon a specified [default child route](guide/router-tutorial-toh#a-crisis-center-with-child-routes) for the crisis center.
@ -489,8 +510,8 @@ You must choose a routing strategy early in the development of you project becau
Almost all Angular projects should use the default HTML5 style. Almost all Angular projects should use the default HTML5 style.
It produces URLs that are easier for users to understand and it preserves the option to do server-side rendering. It produces URLs that are easier for users to understand and it preserves the option to do server-side rendering.
Rendering critical pages on the server is a technique that can greatly improve perceived responsiveness when the app first loads. Rendering critical pages on the server is a technique that can greatly improve perceived responsiveness when the application first loads.
An app that would otherwise take ten or more seconds to start could be rendered on the server and delivered to the user's device in less than a second. An application that would otherwise take ten or more seconds to start could be rendered on the server and delivered to the user's device in less than a second.
This option is only available if application URLs look like normal web URLs without hashes (#) in the middle. This option is only available if application URLs look like normal web URLs without hashes (#) in the middle.
@ -509,7 +530,7 @@ In the [LocationStrategy and browser URL styles](#browser-url-styles) section, l
</div> </div>
You must add a <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base" title="base href">&lt;base href&gt; element</a> to the app's `index.html` for `pushState` routing to work. You must add a <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base" title="base href">&lt;base href&gt; element</a> to the application's `index.html` for `pushState` routing to work.
The browser uses the `<base href>` value to prefix relative URLs when referencing CSS files, scripts, and images. The browser uses the `<base href>` value to prefix relative URLs when referencing CSS files, scripts, and images.
Add the `<base>` element just after the `<head>` tag. Add the `<base>` element just after the `<head>` tag.
@ -536,7 +557,7 @@ The preferred way to configure the strategy is to add a <a href="https://develop
<code-example path="router/src/index.html" header="src/index.html (base-href)" region="base-href"></code-example> <code-example path="router/src/index.html" header="src/index.html (base-href)" region="base-href"></code-example>
Without that tag, the browser may not be able to load resources Without that tag, the browser may not be able to load resources
(images, CSS, scripts) when "deep linking" into the app. (images, CSS, scripts) when "deep linking" into the application.
Some developers may not be able to add the `<base>` element, perhaps because they don't have access to `<head>` or the `index.html`. Some developers may not be able to add the `<base>` element, perhaps because they don't have access to `<head>` or the `index.html`.

View File

@ -4,7 +4,7 @@ This topic demonstrates how to create a structural directive and provides concep
<div class="alert is-helpful"> <div class="alert is-helpful">
For the example app that this page describes, see the <live-example></live-example>. For the example application that this page describes, see the <live-example></live-example>.
</div> </div>

View File

@ -20,24 +20,24 @@ In Angular, the component plays the part of the controller/viewmodel, and the te
<hr /> <hr />
Each Angular template in your app is a section of HTML that you can include as a part of the page that the browser displays. Each Angular template in your application is a section of HTML that you can include as a part of the page that the browser displays.
An Angular HTML template renders a view, or user interface, in the browser, just like regular HTML, but with a lot more functionality. An Angular HTML template renders a view, or user interface, in the browser, just like regular HTML, but with a lot more functionality.
When you generate an Angular app with the Angular CLI, the `app.component.html` file is the default template containing placeholder HTML. When you generate an Angular application with the Angular CLI, the `app.component.html` file is the default template containing placeholder HTML.
The template syntax guides show you how you can control the UX/UI by coordinating data between the class and the template. The template syntax guides show you how you can control the UX/UI by coordinating data between the class and the template.
<div class="is-helpful alert"> <div class="is-helpful alert">
Most of the Template Syntax guides have dedicated working example apps that demonstrate the individual topic of each guide. Most of the Template Syntax guides have dedicated working example applications that demonstrate the individual topic of each guide.
To see all of them working together in one app, see the comprehensive <live-example title="Template Syntax Live Code"></live-example>. To see all of them working together in one application, see the comprehensive <live-example title="Template Syntax Live Code"></live-example>.
</div> </div>
## Empower your HTML ## Empower your HTML
With special Angular syntax in your templates, you can extend the HTML vocabulary of your apps. With special Angular syntax in your templates, you can extend the HTML vocabulary of your applications.
For example, Angular helps you get and set DOM (Document Object Model) values dynamically with features such as built-in template functions, variables, event listening, and data binding. For example, Angular helps you get and set DOM (Document Object Model) values dynamically with features such as built-in template functions, variables, event listening, and data binding.
Almost all HTML syntax is valid template syntax. Almost all HTML syntax is valid template syntax.
@ -60,7 +60,7 @@ You may also be interested in the following:
* [Interpolation](guide/interpolation)&mdash;learn how to use interpolation and expressions in HTML. * [Interpolation](guide/interpolation)&mdash;learn how to use interpolation and expressions in HTML.
* [Template statements](guide/template-statements)&mdash;respond to events in your templates. * [Template statements](guide/template-statements)&mdash;respond to events in your templates.
* [Binding syntax](guide/binding-syntax)&mdash;use binding to coordinate values in your app. * [Binding syntax](guide/binding-syntax)&mdash;use binding to coordinate values in your application.
* [Property binding](guide/property-binding)&mdash;set properties of target elements or directive `@Input()` decorators. * [Property binding](guide/property-binding)&mdash;set properties of target elements or directive `@Input()` decorators.
* [Attribute, class, and style bindings](guide/attribute-binding)&mdash;set the value of attributes, classes, and styles. * [Attribute, class, and style bindings](guide/attribute-binding)&mdash;set the value of attributes, classes, and styles.
* [Event binding](guide/event-binding)&mdash;listen for events and your HTML. * [Event binding](guide/event-binding)&mdash;listen for events and your HTML.

View File

@ -61,4 +61,4 @@ coverageReporter: {
The `check` property causes the tool to enforce a minimum of 80% code coverage when the unit tests are run in the project. The `check` property causes the tool to enforce a minimum of 80% code coverage when the unit tests are run in the project.
You can find more info about the different coverage configuration options [here](https://github.com/karma-runner/karma-coverage/blob/master/docs/configuration.md). You can find more information about the different coverage configuration options [here](https://github.com/karma-runner/karma-coverage/blob/master/docs/configuration.md).

View File

@ -15,7 +15,7 @@ can validate much of the component's behavior in an easier, more obvious way.
<div class="alert is-helpful"> <div class="alert is-helpful">
For the sample app that the testing guides describe, see the <live-example name="testing" embedded-style noDownload>sample app</live-example>. For the sample application that the testing guides describe, see the <live-example name="testing" embedded-style noDownload>sample app</live-example>.
For the tests features in the testing guides, see <live-example name="testing" stackblitz="specs" noDownload>tests</live-example>. For the tests features in the testing guides, see <live-example name="testing" stackblitz="specs" noDownload>tests</live-example>.
@ -74,7 +74,7 @@ or its parent component.
region="class-only" region="class-only"
header="app/dashboard/dashboard-hero.component.spec.ts (class tests)"></code-example> header="app/dashboard/dashboard-hero.component.spec.ts (class tests)"></code-example>
When a component has dependencies, you may wish to use the `TestBed` to both When a component has dependencies, you may want to use the `TestBed` to both
create the component and its dependencies. create the component and its dependencies.
The following `WelcomeComponent` depends on the `UserService` to know the name of the user to greet. The following `WelcomeComponent` depends on the `UserService` to know the name of the user to greet.
@ -98,7 +98,7 @@ Then provide and inject _both the_ **component** _and the service_ in the `TestB
region="class-only-before-each" region="class-only-before-each"
header="app/welcome/welcome.component.spec.ts (class-only setup)"></code-example> header="app/welcome/welcome.component.spec.ts (class-only setup)"></code-example>
Then exercise the component class, remembering to call the [lifecycle hook methods](guide/lifecycle-hooks) as Angular does when running the app. Then exercise the component class, remembering to call the [lifecycle hook methods](guide/lifecycle-hooks) as Angular does when running the application.
<code-example <code-example
path="testing/src/app/welcome/welcome.component.spec.ts" path="testing/src/app/welcome/welcome.component.spec.ts"
@ -162,7 +162,7 @@ Because `compileComponents` is asynchronous, it uses
the [`waitForAsync`](api/core/testing/waitForAsync) utility the [`waitForAsync`](api/core/testing/waitForAsync) utility
function imported from `@angular/core/testing`. function imported from `@angular/core/testing`.
Please refer to the [waitForAsync](guide/testing-components-scenarios#waitForAsync) section for more details. Refer to the [waitForAsync](guide/testing-components-scenarios#waitForAsync) section for more details.
</div> </div>
@ -270,7 +270,7 @@ Later you'll encounter the `DebugElement.nativeElement` and it too has the `any`
Angular can't know at compile time what kind of HTML element the `nativeElement` is or Angular can't know at compile time what kind of HTML element the `nativeElement` is or
if it even is an HTML element. if it even is an HTML element.
The app might be running on a _non-browser platform_, such as the server or a The application might be running on a _non-browser platform_, such as the server or a
[Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API), [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API),
where the element may have a diminished API or not exist at all. where the element may have a diminished API or not exist at all.
@ -341,7 +341,7 @@ You import the `DebugElement` symbol from the Angular core library.
### _By.css()_ ### _By.css()_
Although the tests in this guide all run in the browser, Although the tests in this guide all run in the browser,
some apps might run on a different platform at least some of the time. some applications might run on a different platform at least some of the time.
For example, the component might render first on the server as part of a strategy to make the application launch faster on poorly connected devices. The server-side renderer might not support the full HTML element API. For example, the component might render first on the server as part of a strategy to make the application launch faster on poorly connected devices. The server-side renderer might not support the full HTML element API.
If it doesn't support `querySelector`, the previous test could fail. If it doesn't support `querySelector`, the previous test could fail.

View File

@ -4,7 +4,7 @@ This guide explores common component testing use cases.
<div class="alert is-helpful"> <div class="alert is-helpful">
For the sample app that the testing guides describe, see the <live-example name="testing" embedded-style noDownload>sample app</live-example>. For the sample application that the testing guides describe, see the <live-example name="testing" embedded-style noDownload>sample app</live-example>.
For the tests features in the testing guides, see <live-example name="testing" stackblitz="specs" noDownload>tests</live-example>. For the tests features in the testing guides, see <live-example name="testing" stackblitz="specs" noDownload>tests</live-example>.
@ -60,7 +60,7 @@ Binding happens when Angular performs **change detection**.
In production, change detection kicks in automatically In production, change detection kicks in automatically
when Angular creates a component or the user enters a keystroke or when Angular creates a component or the user enters a keystroke or
an asynchronous activity (e.g., AJAX) completes. an asynchronous activity (for example, AJAX) completes.
The `TestBed.createComponent` does _not_ trigger change detection; a fact confirmed in the revised test: The `TestBed.createComponent` does _not_ trigger change detection; a fact confirmed in the revised test:
@ -156,7 +156,7 @@ as the following variant of `BannerComponent` does.
This syntax tells the Angular compiler to read the external files during component compilation. This syntax tells the Angular compiler to read the external files during component compilation.
That's not a problem when you run the CLI `ng test` command because it That's not a problem when you run the CLI `ng test` command because it
_compiles the app before running the tests_. _compiles the application before running the tests_.
However, if you run the tests in a **non-CLI environment**, However, if you run the tests in a **non-CLI environment**,
tests of this component may fail. tests of this component may fail.
@ -239,7 +239,7 @@ The component injector is a property of the fixture's `DebugElement`.
#### _TestBed.inject()_ #### _TestBed.inject()_
You _may_ also be able to get the service from the root injector via `TestBed.inject()`. You _may_ also be able to get the service from the root injector using `TestBed.inject()`.
This is easier to remember and less verbose. This is easier to remember and less verbose.
But it only works when Angular injects the component with the service instance in the test's root injector. But it only works when Angular injects the component with the service instance in the test's root injector.
@ -276,7 +276,7 @@ The first is a sanity test; it confirms that the stubbed `UserService` is called
<div class="alert is-helpful"> <div class="alert is-helpful">
The second parameter to the Jasmine matcher (e.g., `'expected name'`) is an optional failure label. The second parameter to the Jasmine matcher (for example, `'expected name'`) is an optional failure label.
If the expectation fails, Jasmine appends this label to the expectation failure message. If the expectation fails, Jasmine appends this label to the expectation failure message.
In a spec with multiple expectations, it can help clarify what went wrong and which expectation failed. In a spec with multiple expectations, it can help clarify what went wrong and which expectation failed.
@ -831,9 +831,9 @@ Here's the meat of the spec file setup.
Note how the setup code assigns a test hero (`expectedHero`) to the component's `hero` property, Note how the setup code assigns a test hero (`expectedHero`) to the component's `hero` property,
emulating the way the `DashboardComponent` would set it emulating the way the `DashboardComponent` would set it
via the property binding in its repeater. using the property binding in its repeater.
The following test verifies that the hero name is propagated to the template via a binding. The following test verifies that the hero name is propagated to the template using a binding.
<code-example <code-example
path="testing/src/app/dashboard/dashboard-hero.component.spec.ts" path="testing/src/app/dashboard/dashboard-hero.component.spec.ts"
@ -927,7 +927,7 @@ in a helper such as the `click()` function below:
region="click-event" region="click-event"
header="testing/index.ts (click helper)"></code-example> header="testing/index.ts (click helper)"></code-example>
The first parameter is the _element-to-click_. If you wish, you can pass a The first parameter is the _element-to-click_. If you want, you can pass a
custom event object as the second parameter. The default is a (partial) custom event object as the second parameter. The default is a (partial)
<a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button">left-button mouse event object</a> <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button">left-button mouse event object</a>
accepted by many handlers including the `RouterLink` directive. accepted by many handlers including the `RouterLink` directive.
@ -1076,7 +1076,7 @@ Here's the `HeroDetailComponent` constructor:
<code-example path="testing/src/app/hero/hero-detail.component.ts" region="ctor" header="app/hero/hero-detail.component.ts (constructor)"></code-example> <code-example path="testing/src/app/hero/hero-detail.component.ts" region="ctor" header="app/hero/hero-detail.component.ts (constructor)"></code-example>
The `HeroDetail` component needs the `id` parameter so it can fetch The `HeroDetail` component needs the `id` parameter so it can fetch
the corresponding hero via the `HeroDetailService`. the corresponding hero using the `HeroDetailService`.
The component has to get the `id` from the `ActivatedRoute.paramMap` property The component has to get the `id` from the `ActivatedRoute.paramMap` property
which is an `Observable`. which is an `Observable`.
@ -1148,7 +1148,7 @@ This test expects the component to try to navigate to the `HeroListComponent`.
<code-example path="testing/src/app/hero/hero-detail.component.spec.ts" region="route-bad-id" header="app/hero/hero-detail.component.spec.ts (bad id)"></code-example> <code-example path="testing/src/app/hero/hero-detail.component.spec.ts" region="route-bad-id" header="app/hero/hero-detail.component.spec.ts (bad id)"></code-example>
While this app doesn't have a route to the `HeroDetailComponent` that omits the `id` parameter, it might add such a route someday. While this application doesn't have a route to the `HeroDetailComponent` that omits the `id` parameter, it might add such a route someday.
The component should do something reasonable when there is no `id`. The component should do something reasonable when there is no `id`.
In this implementation, the component should create and display a new hero. In this implementation, the component should create and display a new hero.
@ -1368,7 +1368,7 @@ re-calculates parameters, or re-arranges navigation options when the user clicks
Stubbed `RouterLink` tests can confirm that a component with links and an outlet is setup properly, Stubbed `RouterLink` tests can confirm that a component with links and an outlet is setup properly,
that the component has the links it should have, and that they are all pointing in the expected direction. that the component has the links it should have, and that they are all pointing in the expected direction.
These tests do not concern whether the app will succeed in navigating to the target component when the user clicks a link. These tests do not concern whether the application will succeed in navigating to the target component when the user clicks a link.
Stubbing the RouterLink and RouterOutlet is the best option for such limited testing goals. Stubbing the RouterLink and RouterOutlet is the best option for such limited testing goals.
Relying on the real router would make them brittle. Relying on the real router would make them brittle.
@ -1474,7 +1474,7 @@ The test fails when the `TestBed` tries to create the component.
header="app/banner/banner.component.spec.ts (setup that fails)" header="app/banner/banner.component.spec.ts (setup that fails)"
avoid></code-example> avoid></code-example>
Recall that the app hasn't been compiled. Recall that the application hasn't been compiled.
So when you call `createComponent()`, the `TestBed` compiles implicitly. So when you call `createComponent()`, the `TestBed` compiles implicitly.
That's not a problem when the source code is in memory. That's not a problem when the source code is in memory.
@ -1494,7 +1494,7 @@ You must call `compileComponents()` within an asynchronous test function.
<div class="alert is-critical"> <div class="alert is-critical">
If you neglect to make the test function async If you neglect to make the test function async
(e.g., forget to use the `async` keyword as described below), (for example, forget to use `waitForAsync()` as described below),
you'll see this error message you'll see this error message
<code-example language="sh" hideCopy> <code-example language="sh" hideCopy>
@ -1621,7 +1621,7 @@ where Angular would have to compile them in the browser.
#### Import a shared module #### Import a shared module
Because many app components need the `FormsModule` and the `TitleCasePipe`, the developer created Because many application components need the `FormsModule` and the `TitleCasePipe`, the developer created
a `SharedModule` to combine these and other frequently requested parts. a `SharedModule` to combine these and other frequently requested parts.
The test configuration can use the `SharedModule` too as seen in this alternative setup: The test configuration can use the `SharedModule` too as seen in this alternative setup:

View File

@ -5,7 +5,7 @@ To check that your services are working as you intend, you can write tests speci
<div class="alert is-helpful"> <div class="alert is-helpful">
For the sample app that the testing guides describe, see the <live-example name="testing" embedded-style noDownload>sample app</live-example>. For the sample application that the testing guides describe, see the <live-example name="testing" embedded-style noDownload>sample app</live-example>.
For the tests features in the testing guides, see <live-example name="testing" stackblitz="specs" noDownload>tests</live-example>. For the tests features in the testing guides, see <live-example name="testing" stackblitz="specs" noDownload>tests</live-example>.
@ -58,7 +58,7 @@ Angular testing utilities make it easy to investigate how injected services beha
## Testing services with the _TestBed_ ## Testing services with the _TestBed_
Your app relies on Angular [dependency injection (DI)](guide/dependency-injection) Your application relies on Angular [dependency injection (DI)](guide/dependency-injection)
to create services. to create services.
When a service has a dependent service, DI finds or creates that dependent service. When a service has a dependent service, DI finds or creates that dependent service.
And if that dependent service has its own dependencies, DI finds-or-creates them as well. And if that dependent service has its own dependencies, DI finds-or-creates them as well.
@ -133,7 +133,7 @@ Begin by putting re-usable, preparatory code in a _setup_ function instead of `b
The `setup()` function returns an object literal The `setup()` function returns an object literal
with the variables, such as `masterService`, that a test might reference. with the variables, such as `masterService`, that a test might reference.
You don't define _semi-global_ variables (e.g., `let masterService: MasterService`) You don't define _semi-global_ variables (for example, `let masterService: MasterService`)
in the body of the `describe()`. in the body of the `describe()`.
Then each test invokes `setup()` in its first line, before continuing Then each test invokes `setup()` in its first line, before continuing

View File

@ -21,7 +21,7 @@ This sample application is much like the one in the [_Tour of Heroes_ tutorial](
<div class="alert is-helpful"> <div class="alert is-helpful">
For the sample app that the testing guides describe, see the <live-example noDownload>sample app</live-example>. For the sample application that the testing guides describe, see the <live-example noDownload>sample app</live-example>.
For the tests features in the testing guides, see <live-example stackblitz="specs" noDownload>tests</live-example>. For the tests features in the testing guides, see <live-example stackblitz="specs" noDownload>tests</live-example>.
@ -40,7 +40,7 @@ Just run the [`ng test`](cli/test) CLI command:
ng test ng test
</code-example> </code-example>
The `ng test` command builds the app in _watch mode_, The `ng test` command builds the application in _watch mode_,
and launches the [Karma test runner](https://karma-runner.github.io). and launches the [Karma test runner](https://karma-runner.github.io).
The console output looks a bit like this: The console output looks a bit like this:
@ -85,7 +85,7 @@ Search the web for more details about Jasmine and Karma configuration.
### Other test frameworks ### Other test frameworks
You can also unit test an Angular app with other testing libraries and test runners. You can also unit test an Angular application with other testing libraries and test runners.
Each library and runner has its own distinctive installation procedures, configuration, and syntax. Each library and runner has its own distinctive installation procedures, configuration, and syntax.
Search the web to learn more. Search the web to learn more.
@ -145,7 +145,7 @@ Continuous integration (CI) servers let you set up your project repository so th
There are paid CI services like Circle CI and Travis CI, and you can also host your own for free using Jenkins and others. There are paid CI services like Circle CI and Travis CI, and you can also host your own for free using Jenkins and others.
Although Circle CI and Travis CI are paid services, they are provided free for open source projects. Although Circle CI and Travis CI are paid services, they are provided free for open source projects.
You can create a public project on GitHub and add these services without paying. You can create a public project on GitHub and add these services without paying.
Contributions to the Angular repo are automatically run through a whole suite of Circle CI tests. Contributions to the Angular repository are automatically run through a whole suite of Circle CI tests.
This article explains how to configure your project to run Circle CI and Travis CI, and also update your test configuration to be able to run tests in the Chrome browser in either environment. This article explains how to configure your project to run Circle CI and Travis CI, and also update your test configuration to be able to run tests in the Chrome browser in either environment.
@ -335,12 +335,12 @@ Now you can run the following command to use the `--no-sandbox` flag:
</div> </div>
## More info on testing ## More information on testing
After you've set up your app for testing, you may find the following testing guides useful. After you've set up your application for testing, you may find the following testing guides useful.
* [Code coverage](guide/testing-code-coverage)&mdash;find out how much of your app your tests are covering and how to specify required amounts. * [Code coverage](guide/testing-code-coverage)&mdash;find out how much of your app your tests are covering and how to specify required amounts.
* [Testing services](guide/testing-services)&mdash;learn how to test the services your app uses. * [Testing services](guide/testing-services)&mdash;learn how to test the services your application uses.
* [Basics of testing components](guide/testing-components-basics)&mdash;discover the basics of testing Angular components. * [Basics of testing components](guide/testing-components-basics)&mdash;discover the basics of testing Angular components.
* [Component testing scenarios](guide/testing-components-scenarios)&mdash;read about the various kinds of component testing scenarios and use cases. * [Component testing scenarios](guide/testing-components-scenarios)&mdash;read about the various kinds of component testing scenarios and use cases.
* [Testing attribute directives](guide/testing-attribute-directives)&mdash;learn about how to test your attribute directives. * [Testing attribute directives](guide/testing-attribute-directives)&mdash;learn about how to test your attribute directives.