docs(testing): tech edits (#3269)

This commit is contained in:
Kapunahele Wong 2017-02-20 18:29:42 -05:00 committed by Ward Bell
parent c5c4ad0c4d
commit 894ff63d36
3 changed files with 622 additions and 518 deletions

View File

@ -184,7 +184,7 @@
"testing": { "testing": {
"title": "Testing", "title": "Testing",
"intro": "Techniques and practices for testing an Angular app" "intro": "Techniques and practices for testing an Angular app."
}, },
"typescript-configuration": { "typescript-configuration": {

View File

@ -24,7 +24,7 @@ a#directive-overview
## Directives overview ## Directives overview
There are three kinds of directives in Angular: There are three kinds of directives in Angular:
1. Components — directives with a template. 1. Components — directives with a template.
1. Structural directives — change the DOM layout by adding and removing DOM elements. 1. Structural directives — change the DOM layout by adding and removing DOM elements.
1. Attribute directives — change the appearance or behavior of an element, component, or another directive. 1. Attribute directives — change the appearance or behavior of an element, component, or another directive.
@ -32,11 +32,11 @@ a#directive-overview
*Components* are the most common of the three directives. *Components* are the most common of the three directives.
You saw a component for the first time in the [QuickStart](../quickstart.html) example. You saw a component for the first time in the [QuickStart](../quickstart.html) example.
*Structural Directives* change the structure of the view. *Structural Directives* change the structure of the view.
Two examples are [NgFor](template-syntax.html#ngFor) and [NgIf](template-syntax.html#ngIf). Two examples are [NgFor](template-syntax.html#ngFor) and [NgIf](template-syntax.html#ngIf).
Learn about them in the [Structural Directives](structural-directives.html) guide. Learn about them in the [Structural Directives](structural-directives.html) guide.
*Attribute directives* are used as attributes of elements. *Attribute directives* are used as attributes of elements.
The built-in [NgStyle](template-syntax.html#ngStyle) directive in the [Template Syntax](template-syntax.html) guide, for example, The built-in [NgStyle](template-syntax.html#ngStyle) directive in the [Template Syntax](template-syntax.html) guide, for example,
can change several element styles at the same time. can change several element styles at the same time.
@ -151,12 +151,12 @@ figure.image-display
:marked :marked
Angular detects that you're trying to bind to *something* but it can't find this directive Angular detects that you're trying to bind to *something* but it can't find this directive
in the module's `declarations` array. in the module's `declarations` array.
After specifying `HighlightDirective` in the `declarations` array, After specifying `HighlightDirective` in the `declarations` array,
Angular knows it can apply the directive to components declared in this module. Angular knows it can apply the directive to components declared in this module.
:marked :marked
To summarize, Angular found the `myHighlight` attribute on the `<p>` element. To summarize, Angular found the `myHighlight` attribute on the `<p>` element.
It created an instance of the `HighlightDirective` class and It created an instance of the `HighlightDirective` class and
injected a reference to the `<p>` element into the directive's constructor injected a reference to the `<p>` element into the directive's constructor
which sets the `<p>` element's background style to yellow. which sets the `<p>` element's background style to yellow.
@ -220,8 +220,8 @@ a#input
### Binding to an _@Input_ property ### Binding to an _@Input_ property
Notice the `@Input` !{_decorator}. It adds metadata to the class that makes the directive's `highlightColor` property available for binding. Notice the `@Input` !{_decorator}. It adds metadata to the class that makes the directive's `highlightColor` property available for binding.
It's called an *input* property because data flows from the binding expression _into_ the directive. It's called an *input* property because data flows from the binding expression _into_ the directive.
Without that input metadata, Angular rejects the binding; see [below](#why-input "Why add @Input?") for more about that. Without that input metadata, Angular rejects the binding; see [below](#why-input "Why add @Input?") for more about that.
Try it by adding the following directive binding variations to the `AppComponent` template: Try it by adding the following directive binding variations to the `AppComponent` template:
@ -239,7 +239,7 @@ a#input
+makeExample('attribute-directives/ts/src/app/app.component.html','color') +makeExample('attribute-directives/ts/src/app/app.component.html','color')
:marked :marked
The `[myHighlight]` attribute binding both applies the highlighting directive to the `<p>` element The `[myHighlight]` attribute binding both applies the highlighting directive to the `<p>` element
and sets the directive's highlight color with a property binding. and sets the directive's highlight color with a property binding.
You're re-using the directive's attribute selector (`[myHighlight]`) to do both jobs. You're re-using the directive's attribute selector (`[myHighlight]`) to do both jobs.
That's a crisp, compact syntax. That's a crisp, compact syntax.
@ -254,8 +254,8 @@ a#input-alias
### Bind to an _@Input_ alias ### Bind to an _@Input_ alias
Fortunately you can name the directive property whatever you want _and_ **_alias it_** for binding purposes. Fortunately you can name the directive property whatever you want _and_ **_alias it_** for binding purposes.
Restore the original property name and specify the selector as the alias in the argument to `@Input`. Restore the original property name and specify the selector as the alias in the argument to `@Input`.
+makeExcerpt('src/app/highlight.directive.ts', 'color', 'src/app/highlight.directive.ts (color property with alias') +makeExcerpt('src/app/highlight.directive.ts', 'color', 'src/app/highlight.directive.ts (color property with alias')
:marked :marked
@ -266,7 +266,7 @@ a#input-alias
+makeExample('attribute-directives/ts/src/app/app.component.html','color') +makeExample('attribute-directives/ts/src/app/app.component.html','color')
:marked :marked
Now that you're binding to `highlightColor`, modify the `onMouseEnter()` method to use it. Now that you're binding to `highlightColor`, modify the `onMouseEnter()` method to use it.
If someone neglects to bind to `highlightColor`, highlight in "red" by default. If someone neglects to bind to `highlightColor`, highlight in "red" by default.
+makeExample('attribute-directives/ts/src/app/highlight.directive.3.ts', 'mouse-enter', 'src/app/highlight.directive.ts (mouse enter)')(format='.') +makeExample('attribute-directives/ts/src/app/highlight.directive.3.ts', 'mouse-enter', 'src/app/highlight.directive.ts (mouse enter)')(format='.')
@ -280,7 +280,7 @@ a#input-alias
It may be difficult to imagine how this directive actually works. It may be difficult to imagine how this directive actually works.
In this section, you'll turn `AppComponent` into a harness that In this section, you'll turn `AppComponent` into a harness that
lets you pick the highlight color with a radio button and bind your color choice to the directive. lets you pick the highlight color with a radio button and bind your color choice to the directive.
Update `app.component.html` as follows: Update `app.component.html` as follows:
+makeExcerpt('attribute-directives/ts/src/app/app.component.html', 'v2', '') +makeExcerpt('attribute-directives/ts/src/app/app.component.html', 'v2', '')
@ -300,7 +300,7 @@ a#second-property
## Bind to a second property ## Bind to a second property
This highlight directive has a single customizable property. In a real app, it may need more. This highlight directive has a single customizable property. In a real app, it may need more.
At the moment, the default color &mdash; the color that prevails until the user picks a highlight color &mdash; At the moment, the default color &mdash; the color that prevails until the user picks a highlight color &mdash;
is hard-coded as "red". Let the template developer set the default color. is hard-coded as "red". Let the template developer set the default color.
Add a second **input** property to `HighlightDirective` called `defaultColor`: Add a second **input** property to `HighlightDirective` called `defaultColor`:
@ -313,11 +313,11 @@ a#second-property
How do you bind to a second property when you're already binding to the `myHighlight` attribute name? How do you bind to a second property when you're already binding to the `myHighlight` attribute name?
As with components, you can add as many directive property bindings as you need by stringing them along in the template. As with components, you can add as many directive property bindings as you need by stringing them along in the template.
The developer should be able to write the following template HTML to both bind to the `AppComponent.color` 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. and fall back to "violet" as the default color.
+makeExample('attribute-directives/ts/src/app/app.component.html', 'defaultColor')(format=".") +makeExample('attribute-directives/ts/src/app/app.component.html', 'defaultColor')(format=".")
:marked :marked
Angular knows that the `defaultColor` binding belongs to the `HighlightDirective` Angular knows that the `defaultColor` binding belongs to the `HighlightDirective`
because you made it _public_ with the `@Input` !{_decorator}. because you made it _public_ with the `@Input` !{_decorator}.
Here's how the harness should work when you're done coding. Here's how the harness should work when you're done coding.
@ -368,11 +368,11 @@ a#why-input
+makeExample('attribute-directives/ts/src/app/highlight.directive.ts','color') +makeExample('attribute-directives/ts/src/app/highlight.directive.ts','color')
:marked :marked
Either way, the `@Input` !{_decorator} tells Angular that this property is Either way, the `@Input` !{_decorator} tells Angular that this property is
_public_ and available for binding by a parent component. _public_ and available for binding by a parent component.
Without `@Input`, Angular refuses to bind to the property. Without `@Input`, Angular refuses to bind to the property.
You've bound template HTML to component properties before and never used `@Input`. You've bound template HTML to component properties before and never used `@Input`.
What's different? What's different?
The difference is a matter of trust. The difference is a matter of trust.
@ -384,9 +384,9 @@ a#why-input
But a component or directive shouldn't blindly trust _other_ components and directives. But a component or directive shouldn't blindly trust _other_ components and directives.
The properties of a component or directive are hidden from binding by default. The properties of a component or directive are hidden from binding by default.
They are _private_ from an Angular binding perspective. They are _private_ from an Angular binding perspective.
When adorned with the `@Input` !{_decorator}, the property becomes _public_ from an Angular binding perspective. When adorned with the `@Input` !{_decorator}, the property becomes _public_ from an Angular binding perspective.
Only then can it be bound by some other component or directive. Only then can it be bound by some other component or directive.
You can tell if `@Input` is needed by the position of the property name in a binding. You can tell if `@Input` is needed by the position of the property name in a binding.
* When it appears in the template expression to the ***right*** of the equals (=), * When it appears in the template expression to the ***right*** of the equals (=),
@ -399,7 +399,7 @@ a#why-input
Now apply that reasoning to the following example: Now apply that reasoning to the following example:
+makeExample('attribute-directives/ts/src/app/app.component.html','color')(format=".") +makeExample('attribute-directives/ts/src/app/app.component.html','color')(format=".")
:marked :marked
* The `color` property in the expression on the right belongs to the template's component. * The `color` property in the expression on the right belongs to the template's component.
The template and its component trust each other. The template and its component trust each other.
The `color` property doesn't require the `@Input` !{_decorator}. The `color` property doesn't require the `@Input` !{_decorator}.

File diff suppressed because it is too large Load Diff