attribute-directives.
Create the following source file in the indicated folder:
@@ -97,7 +97,7 @@ block includes
:marked
After the `@Directive` metadata comes the directive's controller class,
called `HighlightDirective`, which contains the logic for the directive.
- Exporting `HighlightDirective` makes it accessible to other components.
+ Exporting `HighlightDirective` makes it accessible to other components.
Angular creates a new instance of the directive's controller class for
each matching element, injecting an Angular `ElementRef`
@@ -113,7 +113,7 @@ block includes
applies the directive as an attribute to a paragraph (``) element. In Angular terms, the `
` element is the attribute **host**.
- Put the template in its own app.component.html
+ Put the template in its own app.component.html
file that looks like this:
+makeExample('src/app/app.component.1.html')
@@ -176,12 +176,12 @@ figure.image-display
:marked
Then add two eventhandlers that respond when the mouse enters or leaves,
- each adorned by the `HostListener` !{_decorator}.
+ each adorned by the `HostListener` decorator.
+makeExcerpt('src/app/highlight.directive.2.ts','mouse-methods', '')
:marked
- The `@HostListener` !{_decorator} lets you subscribe to events of the DOM
+ The `@HostListener` decorator lets you subscribe to events of the DOM
element that hosts an attribute directive, the `
` in this case.
.l-sub-section
@@ -194,7 +194,7 @@ figure.image-display
1. Talking to DOM API directly isn't a best practice.
:marked
- The handlers delegate to a helper method that sets the color on the DOM element, `#{_priv}el`,
+ The handlers delegate to a helper method that sets the color on the DOM element, `el`,
which you declare and initialize in the constructor.
+makeExcerpt('src/app/highlight.directive.2.ts (constructor)', 'ctor')
@@ -226,7 +226,7 @@ a#input
:marked
### 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.
Without that input metadata, Angular rejects the binding; see [below](#why-input "Why add @Input?") for more about that.
@@ -299,7 +299,7 @@ a#input-alias
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.
- Update app.component.html as follows:
+ Update app.component.html as follows:
+makeExcerpt('src/app/app.component.html', 'v2', '')
@@ -345,7 +345,7 @@ figure.image-display
:marked
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.
@@ -400,7 +400,7 @@ figure.image-display
+makeExcerpt('src/app/highlight.directive.ts', 'color', '')
: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.
Without `@Input`, Angular refuses to bind to the property.
@@ -411,22 +411,22 @@ figure.image-display
Angular treats a component's template as _belonging_ to the component.
The component and its template trust each other implicitly.
Therefore, the component's own template may bind to _any_ property of that component,
- with or without the `@Input` !{_decorator}.
+ with or without the `@Input` decorator.
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.
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.
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 (=),
- it belongs to the template's component and does not require the `@Input` !{_decorator}.
+ it belongs to the template's component and does not require the `@Input` decorator.
* When it appears in **square brackets** ([ ]) to the **left** of the equals (=),
the property belongs to some _other_ component or directive;
- that property must be adorned with the `@Input` !{_decorator}.
+ that property must be adorned with the `@Input` decorator.
Now apply that reasoning to the following example:
@@ -435,8 +435,8 @@ figure.image-display
:marked
* The `color` property in the expression on the right belongs to the template's component.
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.
* The `myHighlight` property on the left refers to an _aliased_ property of the `HighlightDirective`,
not a property of the template's component. There are trust issues.
- Therefore, the directive property must carry the `@Input` !{_decorator}.
+ Therefore, the directive property must carry the `@Input` decorator.
diff --git a/public/docs/ts/latest/guide/browser-support.jade b/public/docs/ts/latest/guide/browser-support.jade
index 55204994af..0cd1d8b52a 100644
--- a/public/docs/ts/latest/guide/browser-support.jade
+++ b/public/docs/ts/latest/guide/browser-support.jade
@@ -1,6 +1,5 @@
block includes
include ../_util-fns
- - var _at_angular = '@angular'
:marked
Angular supports most recent browsers. This includes the following specific versions:
diff --git a/public/docs/ts/latest/guide/component-styles.jade b/public/docs/ts/latest/guide/component-styles.jade
index bf608ae90e..e1aea3c1dc 100644
--- a/public/docs/ts/latest/guide/component-styles.jade
+++ b/public/docs/ts/latest/guide/component-styles.jade
@@ -31,7 +31,7 @@ block includes
specifying any selectors, rules, and media queries that you need.
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.
+ The `styles` property takes an array of strings that contain CSS code.
Usually you give it one string, as in the following example:
+makeExample('component-styles/ts/src/app/hero-app.component.ts')(format='.')
@@ -134,8 +134,8 @@ a(id='loading-styles')
### Styles in metadata
- You can add a `styles` #{_array} property to the `@Component` #{_decorator}.
- Each string in the #{_array} (usually just one string) defines the CSS.
+ You can add a `styles` array property to the `@Component` decorator.
+ Each string in the array (usually just one string) defines the CSS.
+makeExample('component-styles/ts/src/app/hero-app.component.ts')
@@ -143,32 +143,30 @@ a(id='loading-styles')
### Style URLs in metadata
You can load styles from external CSS files by adding a `styleUrls` attribute
- into a component's `@Component` #{_decorator}:
+ into a component's `@Component` decorator:
+makeExample('component-styles/ts/src/app/hero-details.component.ts', 'styleurls')
-block style-url
- .alert.is-important
- :marked
- The URL is relative to the *application root*, which is usually the
- location of the `index.html` web page that hosts the application.
- The style file URL is *not* relative to the component file.
- That's why the example URL begins `src/app/`.
- To specify a URL relative to the component file, see [Appendix 2](#relative-urls).
+.alert.is-important
+ :marked
+ The URL is relative to the *application root*, which is usually the
+ location of the `index.html` web page that hosts the application.
+ The style file URL is *not* relative to the component file.
+ That's why the example URL begins `src/app/`.
+ To specify a URL relative to the component file, see [Appendix 2](#relative-urls).
-block module-bundlers
- .l-sub-section
- :marked
- If you use module bundlers like Webpack, you can also use the `styles` attribute
- to load styles from external files at build time. You could write:
+.l-sub-section
+ :marked
+ If you use module bundlers like Webpack, you can also use the `styles` attribute
+ to load styles from external files at build time. You could write:
- `styles: [require('my.component.css')]`
+ `styles: [require('my.component.css')]`
- Set the `styles` property, not the `styleUrls` property. The module
- bundler loads the CSS strings, not Angular.
- Angular sees the CSS strings only after the bundler loads them.
- To Angular, it's as if you wrote the `styles` array by hand.
- For information on loading CSS in this manner, refer to the module bundler's documentation.
+ Set the `styles` property, not the `styleUrls` property. The module
+ bundler loads the CSS strings, not Angular.
+ Angular sees the CSS strings only after the bundler loads them.
+ To Angular, it's as if you wrote the `styles` array by hand.
+ For information on loading CSS in this manner, refer to the module bundler's documentation.
:marked
### Template inline styles
@@ -195,9 +193,8 @@ block module-bundlers
For details, see [`@import`](https://developer.mozilla.org/en/docs/Web/CSS/@import)
on the [MDN](https://developer.mozilla.org) site.
-block css-import-url
- :marked
- In this case, the URL is relative to the CSS file into which you're importing.
+:marked
+ In this case, the URL is relative to the CSS file into which you're importing.
+makeExample('component-styles/ts/src/app/hero-details.component.css', 'import', 'src/app/hero-details.component.css (excerpt)')
@@ -300,9 +297,8 @@ code-example(format="nocode").
Because these files are co-located with the component,
it would be nice to refer to them by name without also having to specify a path back to the root of the application.
-block module-id
- :marked
- You can use a relative URL by prefixing your filenames with `./`:
+:marked
+ You can use a relative URL by prefixing your filenames with `./`:
- +makeExample('src/app/quest-summary.component.ts')
++makeExample('src/app/quest-summary.component.ts')
diff --git a/public/docs/ts/latest/guide/dependency-injection.jade b/public/docs/ts/latest/guide/dependency-injection.jade
index 209b9ea0f9..c203d67263 100644
--- a/public/docs/ts/latest/guide/dependency-injection.jade
+++ b/public/docs/ts/latest/guide/dependency-injection.jade
@@ -1,6 +1,5 @@
block includes
include ../_util-fns
- - var _thisDot = 'this.';
:marked
**Dependency injection** is an important application design pattern.
@@ -62,7 +61,7 @@ block includes
What if the `Engine` class evolves and its constructor requires a parameter?
That would break the `Car` class and it would stay broken until you rewrote it along the lines of
- `#{_thisDot}engine = new Engine(theNewParameter)`.
+ `this.engine = new Engine(theNewParameter)`.
The `Engine` constructor parameters weren't even a consideration when you first wrote `Car`.
You may not anticipate them even now.
But you'll *have* to start caring because
@@ -108,11 +107,10 @@ block includes
The `Car` class no longer creates an `engine` or `tires`.
It just consumes them.
-block ctor-syntax
- .l-sub-section
- :marked
- This example leverages TypeScript's constructor syntax for declaring
- parameters and properties simultaneously.
+.l-sub-section
+ :marked
+ This example leverages TypeScript's constructor syntax for declaring
+ parameters and properties simultaneously.
:marked
Now you can create a car by passing the engine and tires to the constructor.
@@ -133,8 +131,7 @@ block ctor-syntax
The _consumer_ of `Car` has the problem. The consumer must update the car creation code to
something like this:
- - var stylePattern = { otl: /(new Car.*$)/gm };
- +makeExample('dependency-injection/ts/src/app/car/car-creations.ts', 'car-ctor-instantiation-with-param', '', stylePattern)(format=".")
+ +makeExample('dependency-injection/ts/src/app/car/car-creations.ts', 'car-ctor-instantiation-with-param', '', { otl: /(new Car.*$)/gm })(format=".")
:marked
The critical point is this: the `Car` class did not have to change.
@@ -146,8 +143,7 @@ block ctor-syntax
You can pass mocks to the constructor that do exactly what you want them to do
during each test:
-- var stylePattern = { otl: /(new Car.*$)/gm };
-+makeExample('dependency-injection/ts/src/app/car/car-creations.ts', 'car-ctor-instantiation-with-mocks', '', stylePattern)(format=".")
++makeExample('dependency-injection/ts/src/app/car/car-creations.ts', 'car-ctor-instantiation-with-mocks', '', { otl: /(new Car.*$)/gm })(format=".")
:marked
**You just learned what dependency injection is**.
@@ -236,9 +232,8 @@ block ctor-syntax
Given that the service is a
[separate concern](https://en.wikipedia.org/wiki/Separation_of_concerns),
consider writing the service code in its own file.
- +ifDocsFor('ts')
- :marked
- See [this note](#one-class-per-file) for details.
+
+ See [this note](#one-class-per-file) for details.
:marked
The following `HeroService` exposes a `getHeroes` method that returns
the same mock data as before, but none of its consumers need to know that.
@@ -248,15 +243,14 @@ block ctor-syntax
:marked
.l-sub-section
:marked
- The `@Injectable()` #{_decorator} above the service class is
+ The `@Injectable()` decorator above the service class is
covered [shortly](#injectable).
-- var _perhaps = _docsFor == 'dart' ? '' : 'perhaps';
.l-sub-section
:marked
Of course, this isn't a real service.
If the app were actually getting data from a remote server, the API would have to be
- asynchronous, #{_perhaps} returning a !{_PromiseLinked}.
+ asynchronous, perhaps returning a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
You'd also have to rewrite the way components consume the service.
This is important in general, but not in this example.
@@ -279,18 +273,16 @@ a#injector-config
that create the services the application requires.
This guide explains what [providers](#providers) are later.
-block register-provider-ngmodule
- :marked
- You can either register a provider within an [NgModule](ngmodule.html) or in application components.
+:marked
+ You can either register a provider within an [NgModule](ngmodule.html) or in application components.
- a#register-providers-ngmodule
- :marked
- ### Registering providers in an _NgModule_
- Here's the `AppModule` that registers two providers, `UserService` and an `APP_CONFIG` provider,
- in its `providers` !{_array}.
+a#register-providers-ngmodule
+:marked
+ ### Registering providers in an _NgModule_
+ Here's the `AppModule` that registers two providers, `UserService` and an `APP_CONFIG` provider,
+ in its `providers` array.
- - var app_module_ts = 'src/app/app.module.ts';
- +makeExcerpt(app_module_ts + ' (excerpt)', 'ngmodule', app_module_ts)
++makeExcerpt('src/app/app.module.ts (excerpt)', 'ngmodule', app_module_ts)
:marked
Because the `HeroService` is used _only_ within the `HeroesComponent`
and its subcomponents, the top-level `HeroesComponent` is the ideal
@@ -300,31 +292,30 @@ a#register-providers-component
:marked
### Registering providers in a component
- Here's a revised `HeroesComponent` that registers the `HeroService` in its `providers` !{_array}.
+ Here's a revised `HeroesComponent` that registers the `HeroService` in its `providers` array.
+makeExample('src/app/heroes/heroes.component.1.ts', 'full', 'src/app/heroes/heroes.component.ts', stylePattern)(format='.')
-block ngmodule-vs-component
- a#ngmodule-vs-comp
+a#ngmodule-vs-comp
+:marked
+ ### When to use _NgModule_ versus an application component
+
+ On the one hand, a provider in an `NgModule` is registered in the root injector. That means that every provider
+ registered within an `NgModule` will be accessible in the _entire application_.
+
+ On the other hand, a provider registered in an application component is available only on
+ that component and all its children.
+
+ Here, the `APP_CONFIG` service needs to be available all across the application, so it's
+ registered in the `AppModule` `@NgModule` `providers` array.
+ But since the `HeroService` is only used within the *Heroes*
+ feature area and nowhere else, it makes sense to register it in
+ the `HeroesComponent`.
+
+.l-sub-section
:marked
- ### When to use _NgModule_ versus an application component
-
- On the one hand, a provider in an `NgModule` is registered in the root injector. That means that every provider
- registered within an `NgModule` will be accessible in the _entire application_.
-
- On the other hand, a provider registered in an application component is available only on
- that component and all its children.
-
- Here, the `APP_CONFIG` service needs to be available all across the application, so it's
- registered in the `AppModule` `@NgModule` `providers` !{_array}.
- But since the `HeroService` is only used within the *Heroes*
- feature area and nowhere else, it makes sense to register it in
- the `HeroesComponent`.
-
- .l-sub-section
- :marked
- Also see *"Should I add app-wide providers to the root `AppModule` or
- the root `AppComponent`?"* in the [NgModule FAQ](../cookbook/ngmodule-faq.html#q-root-component-or-module).
+ Also see *"Should I add app-wide providers to the root `AppModule` or
+ the root `AppComponent`?"* in the [NgModule FAQ](../cookbook/ngmodule-faq.html#q-root-component-or-module).
a#prep-for-injection
:marked
@@ -352,12 +343,12 @@ a#prep-for-injection
:marked
Note that the constructor parameter has the type `HeroService`, and that
- the `HeroListComponent` class has an `@Component` #{_decorator}
+ the `HeroListComponent` class has an `@Component` decorator
(scroll up to confirm that fact).
Also recall that the parent component (`HeroesComponent`)
has `providers` information for `HeroService`.
- The constructor parameter type, the `@Component` #{_decorator},
+ The constructor parameter type, the `@Component` decorator,
and the parent's `providers` information combine to tell the
Angular injector to inject an instance of
`HeroService` whenever it creates a new `HeroListComponent`.
@@ -432,37 +423,35 @@ a#service-needs-service
src/app/heroes/hero.service (v1)`)
:marked
- The constructor now asks for an injected instance of a `Logger` and stores it in a private property called `#{_priv}logger`.
+ The constructor now asks for an injected instance of a `Logger` and stores it in a private property called `logger`.
You call that property within the `getHeroes()` method when anyone asks for heroes.
-- var injUrl = '../api/core/index/Injectable-decorator.html';
a#injectable
:marked
### Why _@Injectable()_?
- **@Injectable()** marks a class as available to an
+ **@Injectable()** marks a class as available to an
injector for instantiation. Generally speaking, an injector reports an
error when trying to instantiate a class that is not marked as
`@Injectable()`.
-block injectable-not-always-needed-in-ts
- .l-sub-section
- :marked
- As it happens, you could have omitted `@Injectable()` from the first
- version of `HeroService` because it had no injected parameters.
- But you must have it now that the service has an injected dependency.
- You need it because Angular requires constructor parameter metadata
- in order to inject a `Logger`.
+.l-sub-section
+ :marked
+ As it happens, you could have omitted `@Injectable()` from the first
+ version of `HeroService` because it had no injected parameters.
+ But you must have it now that the service has an injected dependency.
+ You need it because Angular requires constructor parameter metadata
+ in order to inject a `Logger`.
- .callout.is-helpful
- header Suggestion: add @Injectable() to every service class
- :marked
- Consider adding `@Injectable()` to every service class, even those that don't have dependencies
- and, therefore, do not technically require it. Here's why:
+.callout.is-helpful
+ header Suggestion: add @Injectable() to every service class
+ :marked
+ Consider adding `@Injectable()` to every service class, even those that don't have dependencies
+ and, therefore, do not technically require it. Here's why:
- ul(style="font-size:inherit")
- li Future proofing: No need to remember @Injectable() when you add a dependency later.
- li Consistency: All services follow the same rules, and you don't have to wonder why #{_a} #{_decorator} is missing.
+ ul(style="font-size:inherit")
+ li Future proofing: No need to remember @Injectable() when you add a dependency later.
+ li Consistency: All services follow the same rules, and you don't have to wonder why a decorator is missing.
:marked
Injectors are also responsible for instantiating components
@@ -471,35 +460,33 @@ block injectable-not-always-needed-in-ts
You *can* add it if you really want to. It isn't necessary because the
`HeroesComponent` is already marked with `@Component`, and this
- !{_decorator} class (like `@Directive` and `@Pipe`, which you learn about later)
- is a subtype of @Injectable(). It is in
- fact `@Injectable()` #{_decorator}s that
+ decorator class (like `@Directive` and `@Pipe`, which you learn about later)
+ is a subtype of @Injectable(). It is in
+ fact `@Injectable()` decorators that
identify a class as a target for instantiation by an injector.
-+ifDocsFor('ts')
- .l-sub-section
- :marked
- At runtime, injectors can read class metadata in the transpiled JavaScript code
- and use the constructor parameter type information
- to determine what things to inject.
+.l-sub-section
+ :marked
+ At runtime, injectors can read class metadata in the transpiled JavaScript code
+ and use the constructor parameter type information
+ to determine what things to inject.
- Not every JavaScript class has metadata.
- The TypeScript compiler discards metadata by default.
- If the `emitDecoratorMetadata` compiler option is true
- (as it should be in the `tsconfig.json`),
- the compiler adds the metadata to the generated JavaScript
- for _every class with at least one decorator_.
+ Not every JavaScript class has metadata.
+ The TypeScript compiler discards metadata by default.
+ If the `emitDecoratorMetadata` compiler option is true
+ (as it should be in the `tsconfig.json`),
+ the compiler adds the metadata to the generated JavaScript
+ for _every class with at least one decorator_.
- While any decorator will trigger this effect, mark the service class with the
- @Injectable() #{_decorator}
- to make the intent clear.
+ While any decorator will trigger this effect, mark the service class with the
+ @Injectable() decorator
+ to make the intent clear.
.callout.is-critical
header Always include the parentheses
- block always-include-paren
- :marked
- Always write `@Injectable()`, not just `@Injectable`.
- The application will fail mysteriously if you forget the parentheses.
+ :marked
+ Always write `@Injectable()`, not just `@Injectable`.
+ The application will fail mysteriously if you forget the parentheses.
.l-main-section#logger-service
:marked
@@ -513,13 +500,10 @@ block injectable-not-always-needed-in-ts
+makeExample('src/app/logger.service.ts')
-block real-logger
- //- N/A
-
:marked
You're likely to need the same logger service everywhere in your application,
- so put it in the project's `#{_appDir}` folder and
- register it in the `providers` #{_array} of the application !{_moduleVsComp}, `!{_AppModuleVsAppComp}`.
+ so put it in the project's `app` folder and
+ register it in the `providers` array of the application module, `AppModule`.
+makeExcerpt('src/app/providers.component.ts (excerpt)', 'providers-logger','src/app/app.module.ts')
@@ -546,51 +530,44 @@ code-example(format="nocode").
You must register a service *provider* with the injector, or it won't know how to create the service.
- Earlier you registered the `Logger` service in the `providers` #{_array} of the metadata for the `AppModule` like this:
+ Earlier you registered the `Logger` service in the `providers` array of the metadata for the `AppModule` like this:
+makeExample('dependency-injection/ts/src/app/providers.component.ts','providers-logger')
-- var implements = _docsFor == 'dart' ? 'implements' : 'looks and behaves like a '
-- var objectlike = _docsFor == 'dart' ? '' : 'an object that behaves like '
-- var loggerlike = _docsFor == 'dart' ? '' : 'You could provide a logger-like object. '
:marked
- There are many ways to *provide* something that #{implements} `Logger`.
+ There are many ways to *provide* something that looks and behaves like a `Logger`.
The `Logger` class itself is an obvious and natural provider.
But it's not the only way.
- You can configure the injector with alternative providers that can deliver #{objectlike} a `Logger`.
- You could provide a substitute class. #{loggerlike}
+ You can configure the injector with alternative providers that can deliver an object that behaves like a `Logger`.
+ You could provide a substitute class. You could provide a logger-like object.
You could give it a provider that calls a logger factory function.
Any of these approaches might be a good choice under the right circumstances.
What matters is that the injector has a provider to go to when it needs a `Logger`.
//- Dart limitation: the provide function isn't const so it cannot be used in an annotation.
-- var _andProvideFn = _docsFor == 'dart' ? '' : 'and provide object literal';
+
#provide
:marked
- ### The *Provider* class !{_andProvideFn}
+ ### The *Provider* class and _provide_ object literal
:marked
- You wrote the `providers` #{_array} like this:
+ You wrote the `providers` array like this:
+makeExample('dependency-injection/ts/src/app/providers.component.ts','providers-1')
-block provider-shorthand
- :marked
- This is actually a shorthand expression for a provider registration
- using a _provider_ object literal with two properties:
+:marked
+ This is actually a shorthand expression for a provider registration
+ using a _provider_ object literal with two properties:
+makeExample('dependency-injection/ts/src/app/providers.component.ts','providers-3')
-block provider-ctor-args
- - var _secondParam = 'provider definition object';
-
:marked
The first is the [token](#token) that serves as the key for both locating a dependency value
and registering the provider.
- The second is a !{_secondParam},
+ The second is a provider definition object,
which you can think of as a *recipe* for creating the dependency value.
There are many ways to create dependency values just as there are many ways to write a recipe.
@@ -604,9 +581,6 @@ block provider-ctor-args
+makeExample('dependency-injection/ts/src/app/providers.component.ts','providers-4')
-block dart-diff-const-metadata
- //- N/A
-
a#class-provider-dependencies
:marked
### Class provider with dependencies
@@ -653,9 +627,6 @@ a#value-provider
:marked
Sometimes it's easier to provide a ready-made object rather than ask the injector to create it from a class.
-block dart-diff-const-metadata-ctor
- //- N/A
-
+makeExample('dependency-injection/ts/src/app/providers.component.ts','silent-logger')(format=".")
:marked
@@ -720,19 +691,17 @@ block dart-diff-const-metadata-ctor
The `useFactory` field tells Angular that the provider is a factory function
whose implementation is the `heroServiceFactory`.
- The `deps` property is #{_an} #{_array} of [provider tokens](#token).
+ The `deps` property is an array of [provider tokens](#token).
The `Logger` and `UserService` classes serve as tokens for their own class providers.
The injector resolves these tokens and injects the corresponding services into the matching factory function parameters.
-- var exportedvar = _docsFor == 'dart' ? 'constant' : 'exported variable'
-- var variable = _docsFor == 'dart' ? 'constant' : 'variable'
:marked
- Notice that you captured the factory provider in #{_an} #{exportedvar}, `heroServiceProvider`.
+ Notice that you captured the factory provider in an exported variable, `heroServiceProvider`.
This extra step makes the factory provider reusable.
- You can register the `HeroService` with this #{variable} wherever you need it.
+ You can register the `HeroService` with this variable wherever you need it.
In this sample, you need it only in the `HeroesComponent`,
- where it replaces the previous `HeroService` registration in the metadata `providers` #{_array}.
+ where it replaces the previous `HeroService` registration in the metadata `providers` array.
Here you see the new and the old implementation side-by-side:
+makeTabs(
@@ -774,14 +743,12 @@ a#non-class-dependencies
### Non-class dependencies
p
| What if the dependency value isn't a class? Sometimes the thing you want to inject is a
- block non-class-dep-eg
- | span string, function, or object.
+ | span string, function, or object.
p
| Applications often define configuration objects with lots of small facts
| (like the title of the application or the address of a web API endpoint)
- block config-obj-maps
- | but these configuration objects aren't always instances of a class.
- | They can be object literals such as this one:
+ | but these configuration objects aren't always instances of a class.
+ | They can be object literals such as this one:
+makeExample('dependency-injection/ts/src/app/app.config.ts','config','src/app/app-config.ts (excerpt)')(format='.')
@@ -789,36 +756,33 @@ p
What if you'd like to make this configuration object available for injection?
You know you can register an object with a [value provider](#value-provider).
-block what-should-we-use-as-token
+:marked
+ But what should you use as the token?
+ You don't have a class to serve as a token.
+ There is no `AppConfig` class.
+
+.l-sub-section#interface
:marked
- But what should you use as the token?
- You don't have a class to serve as a token.
- There is no `AppConfig` class.
+ ### TypeScript interfaces aren't valid tokens
- .l-sub-section#interface
- :marked
- ### TypeScript interfaces aren't valid tokens
+ The `HERO_DI_CONFIG` constant has an interface, `AppConfig`. Unfortunately, you
+ cannot use a TypeScript interface as a token:
+ +makeExample('dependency-injection/ts/src/app/providers.component.ts','providers-9-interface')(format=".")
+ +makeExample('dependency-injection/ts/src/app/providers.component.ts','provider-9-ctor-interface')(format=".")
+ :marked
+ That seems strange if you're used to dependency injection in strongly typed languages, where
+ an interface is the preferred dependency lookup key.
- The `HERO_DI_CONFIG` constant has an interface, `AppConfig`. Unfortunately, you
- cannot use a TypeScript interface as a token:
- +makeExample('dependency-injection/ts/src/app/providers.component.ts','providers-9-interface')(format=".")
- +makeExample('dependency-injection/ts/src/app/providers.component.ts','provider-9-ctor-interface')(format=".")
- :marked
- That seems strange if you're used to dependency injection in strongly typed languages, where
- an interface is the preferred dependency lookup key.
+ It's not Angular's doing. An interface is a TypeScript design-time artifact. JavaScript doesn't have interfaces.
+ The TypeScript interface disappears from the generated JavaScript.
+ There is no interface type information left for Angular to find at runtime.
- It's not Angular's doing. An interface is a TypeScript design-time artifact. JavaScript doesn't have interfaces.
- The TypeScript interface disappears from the generated JavaScript.
- There is no interface type information left for Angular to find at runtime.
-
-//- FIXME update once https://github.com/dart-lang/angular2/issues/16 is addressed.
-- var opaquetoken = _docsFor == 'dart' ? 'OpaqueToken' : 'OpaqueToken'
a#opaquetoken
:marked
### _OpaqueToken_
One solution to choosing a provider token for non-class dependencies is
- to define and use an !{opaquetoken}.
+ to define and use an OpaqueToken.
The definition looks like this:
+makeExample('dependency-injection/ts/src/app/app.config.ts','token')(format='.')
@@ -830,19 +794,17 @@ a#opaquetoken
:marked
Now you can inject the configuration object into any constructor that needs it, with
- the help of an `@Inject` #{_decorator}:
+ the help of an `@Inject` decorator:
+makeExample('dependency-injection/ts/src/app/app.component.2.ts','ctor')(format=".")
-- var configType = _docsFor == 'dart' ? 'Map' : 'AppConfig'
.l-sub-section
:marked
- Although the !{configType} interface plays no role in dependency injection,
+ Although the `AppConfig` interface plays no role in dependency injection,
it supports typing of the configuration object within the class.
-block dart-map-alternative
- :marked
- Aternatively, you can provide and inject the configuration object in an ngModule like `AppModule`.
+:marked
+ Aternatively, you can provide and inject the configuration object in an ngModule like `AppModule`.
+makeExcerpt('src/app/app.module.ts','ngmodule-providers')
@@ -855,8 +817,7 @@ block dart-map-alternative
You can tell Angular that the dependency is optional by annotating the
constructor argument with `@Optional()`:
-+ifDocsFor('ts')
- +makeExample('dependency-injection/ts/src/app/providers.component.ts','import-optional', '')
++makeExample('dependency-injection/ts/src/app/providers.component.ts','import-optional', '')
+makeExample('dependency-injection/ts/src/app/providers.component.ts','provider-10-ctor', '')(format='.')
:marked
@@ -915,23 +876,22 @@ block dart-map-alternative
Framework developers may take this approach when they
must acquire services generically and dynamically.
-+ifDocsFor('ts')
- .l-main-section#one-class-per-file
+.l-main-section#one-class-per-file
+:marked
+ ## Appendix: Why have one class per file
+
+ Having multiple classes in the same file is confusing and best avoided.
+ Developers expect one class per file. Keep them happy.
+
+ If you combine the `HeroService` class with
+ the `HeroesComponent` in the same file,
+ **define the component last**.
+ If you define the component before the service,
+ you'll get a runtime null reference error.
+
+.l-sub-section
:marked
- ## Appendix: Why have one class per file
-
- Having multiple classes in the same file is confusing and best avoided.
- Developers expect one class per file. Keep them happy.
-
- If you combine the `HeroService` class with
- the `HeroesComponent` in the same file,
- **define the component last**.
- If you define the component before the service,
- you'll get a runtime null reference error.
-
- .l-sub-section
- :marked
- You actually can define the component first with the help of the `forwardRef()` method as explained
- in this [blog post](http://blog.thoughtram.io/angular/2015/09/03/forward-references-in-angular-2.html).
- But why flirt with trouble?
- Avoid the problem altogether by defining components and services in separate files.
+ You actually can define the component first with the help of the `forwardRef()` method as explained
+ in this [blog post](http://blog.thoughtram.io/angular/2015/09/03/forward-references-in-angular-2.html).
+ But why flirt with trouble?
+ Avoid the problem altogether by defining components and services in separate files.
diff --git a/public/docs/ts/latest/guide/deployment.jade b/public/docs/ts/latest/guide/deployment.jade
index 7f44f9f9cf..ea3c170c29 100644
--- a/public/docs/ts/latest/guide/deployment.jade
+++ b/public/docs/ts/latest/guide/deployment.jade
@@ -156,7 +156,7 @@ a#node-modules
Practice with this sample before attempting these techniques on your application.
1. Follow the [setup instructions](../guide/setup.html "Angular QuickStart setup") for creating a new project
- named simple-deployment.
1. Add the "Simple deployment" sample files shown above.
diff --git a/public/docs/ts/latest/guide/displaying-data.jade b/public/docs/ts/latest/guide/displaying-data.jade
index 6584a1d170..772d63ae3b 100644
--- a/public/docs/ts/latest/guide/displaying-data.jade
+++ b/public/docs/ts/latest/guide/displaying-data.jade
@@ -1,7 +1,5 @@
block includes
include ../_util-fns
- - var _iterableUrl = 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols';
- - var _boolean = 'truthy/falsy';
:marked
You can display data by binding controls in an HTML template to properties of an Angular component.
@@ -19,7 +17,7 @@ figure.image-display
# Contents
* [Showing component properties with interpolation](#interpolation).
- * [Showing !{_an} !{_array} property with NgFor](#ngFor).
+ * [Showing an array property with NgFor](#ngFor).
* [Conditional display with NgIf](#ngIf).
.l-sub-section
@@ -35,9 +33,9 @@ figure.image-display
With interpolation, you put the property name in the view template, enclosed in double curly braces: `{{myHero}}`.
Follow the [setup](setup.html) instructions for creating a new project
- named displaying-data.
- Then modify the app.component.ts file by
changing the template and the body of the component.
When you're done, it should look like this:
@@ -52,13 +50,12 @@ figure.image-display
+makeExcerpt('src/app/app.component.1.ts', 'template', '')
-+ifDocsFor('ts')
- .l-sub-section
- :marked
- The template is a multi-line string within ECMAScript 2015 backticks (\`).
- The backtick (\`)—which is *not* the same character as a single
- quote (`'`)—allows you to compose a string over several lines, which makes the
- HTML more readable.
+.l-sub-section
+ :marked
+ The template is a multi-line string within ECMAScript 2015 backticks (\`).
+ The backtick (\`)—which is *not* the same character as a single
+ quote (`'`)—allows you to compose a string over several lines, which makes the
+ HTML more readable.
:marked
Angular automatically pulls the value of the `title` and `myHero` properties from the component and
@@ -74,13 +71,13 @@ figure.image-display
Notice that you don't call **new** to create an instance of the `AppComponent` class.
Angular is creating an instance for you. How?
- The CSS `selector` in the `@Component` !{_decorator} specifies an element named `main.ts), Angular looks for a `app.component.ts" and delete or comment out one of the elements from the hero array.
The browser should refresh automatically and the message should disappear.
.l-main-section
@@ -259,16 +253,15 @@ block hero-class
## Summary
Now you know how to use:
- **Interpolation** with double curly braces to display a component property.
- - **ngFor** to display !{_an} !{_array} of items.
- - A !{_Lang} class to shape the **model data** for your component and display properties of that model.
+ - **ngFor** to display an array of items.
+ - A TypeScript class to shape the **model data** for your component and display properties of that model.
- **ngIf** to conditionally display a chunk of HTML based on a boolean expression.
Here's the final code:
-block final-code
- +makeTabs(`displaying-data/ts/src/app/app.component.ts,
- displaying-data/ts/src/app/hero.ts,
- displaying-data/ts/src/app/app.module.ts,
- displaying-data/ts/src/main.ts`,
- 'final,,,',
- 'src/app/app.component.ts, src/app/hero.ts, src/app/app.module.ts, main.ts')
++makeTabs(`displaying-data/ts/src/app/app.component.ts,
+ displaying-data/ts/src/app/hero.ts,
+ displaying-data/ts/src/app/app.module.ts,
+ displaying-data/ts/src/main.ts`,
+ 'final,,,',
+ 'src/app/app.component.ts, src/app/hero.ts, src/app/app.module.ts, main.ts')
diff --git a/public/docs/ts/latest/guide/forms.jade b/public/docs/ts/latest/guide/forms.jade
index 93102adcc7..a27156a43e 100644
--- a/public/docs/ts/latest/guide/forms.jade
+++ b/public/docs/ts/latest/guide/forms.jade
@@ -83,7 +83,7 @@ figure.image-display
## Setup
Follow the [setup](setup.html) instructions for creating a new project
- named angular-forms.
+ named angular-forms.
## Create the Hero model class
@@ -94,7 +94,7 @@ figure.image-display
That describes well the `Hero` class with its three required fields (`id`, `name`, `power`)
and one optional field (`alterEgo`).
- In the `!{_appDir}` directory, create the following file with the given content:
+ In the `app` directory, create the following file with the given content:
+makeExample('src/app/hero.ts')
diff --git a/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade b/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade
index a1dc5c4d1f..456d15e7af 100644
--- a/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade
+++ b/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade
@@ -70,7 +70,7 @@ figure.image-display
It effectively "reconfigures" and "shadows" a provider at a higher level in the tree.
If you only specify providers at the top level (typically the root `AppModule`), the tree of injectors appears to be flat.
- All requests bubble up to the root NgModule injector that you configured with the `!{_bootstrapModule}` method.
+ All requests bubble up to the root NgModule injector that you configured with the `bootstrapModule` method.
.l-main-section
:marked
diff --git a/public/docs/ts/latest/guide/lifecycle-hooks.jade b/public/docs/ts/latest/guide/lifecycle-hooks.jade
index ecdb8f4947..0da9407b5d 100644
--- a/public/docs/ts/latest/guide/lifecycle-hooks.jade
+++ b/public/docs/ts/latest/guide/lifecycle-hooks.jade
@@ -1,8 +1,6 @@
block includes
include ../_util-fns
-- var top="vertical-align:top"
-
figure
img(src="/resources/images/devguide/lifecycle-hooks/hooks-in-sequence.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:30px")
@@ -17,6 +15,7 @@ figure
A directive has the same set of lifecycle hooks, minus the hooks that are specific to component content and views.
+<<<<<<< 93d3db1fd4f61c9c6078b2000dea164c87fa071c
+ifDocsFor('ts|js')
:marked
## Contents
@@ -38,6 +37,28 @@ figure
* [Content projection](#content-projection)
* [AfterContent hooks](#aftercontent-hooks)
* [No unidirectional flow worries with _AfterContent_](#no-unidirectional-flow-worries)
+=======
+
+:marked
+ ## Contents
+ * [Component lifecycle hooks overview](#hooks-overview)
+ * [Lifecycle sequence](#hooks-purpose-timing)
+ * [Interfaces are optional (technically)](#interface-optional)
+ * [Other Angular lifecycle hooks](#other-lifecycle-hooks)
+ * [Lifecycle examples](#the-sample)
+ * [Peek-a-boo: all hooks](#peek-a-boo)
+ * [Spying OnInit and OnDestroy](#spy)
+ * [OnInit](#oninit)
+ * [OnDestroy](#ondestroy)
+ * [OnChanges](#onchanges)
+ * [DoCheck](#docheck)
+ * [AfterView](#afterview)
+ * [Abide by the unidirectional data flow rule](#wait-a-tick)
+ * [AfterContent](#aftercontent)
+ * [Content projection](#content-projection)
+ * [AfterContent hooks](#aftercontent-hooks)
+ * [No unidirectional flow worries with _AfterContent_](#no-unidirectional-flow-worries)
+>>>>>>> chore: remove dart remains
:marked
Try the ngOnChanges()
td
:marked
@@ -81,7 +102,7 @@ table(width="100%")
Called before `ngOnInit()` and whenever one or more data-bound input properties change.
- tr(style=top)
+ tr(style=vertical-align:top)
td ngOnInit()
td
:marked
@@ -90,7 +111,7 @@ table(width="100%")
Called _once_, after the _first_ `ngOnChanges()`.
- tr(style=top)
+ tr(style=vertical-align:top)
td ngDoCheck()
td
:marked
@@ -98,7 +119,7 @@ table(width="100%")
Called during every change detection run, immediately after `ngOnChanges()` and `ngOnInit()`.
- tr(style=top)
+ tr(style=vertical-align:top)
td ngAfterContentInit()
td
:marked
@@ -108,7 +129,7 @@ table(width="100%")
_A component-only hook_.
- tr(style=top)
+ tr(style=vertical-align:top)
td ngAfterContentChecked()
td
:marked
@@ -118,7 +139,7 @@ table(width="100%")
_A component-only hook_.
- tr(style=top)
+ tr(style=vertical-align:top)
td ngAfterViewInit()
td
:marked
@@ -128,7 +149,7 @@ table(width="100%")
_A component-only hook_.
- tr(style=top)
+ tr(style=vertical-align:top)
td ngAfterViewChecked()
td
:marked
@@ -138,7 +159,7 @@ table(width="100%")
_A component-only hook_.
- tr(style=top)
+ tr(style=vertical-align:top)
td ngOnDestroy
td
:marked
@@ -147,24 +168,23 @@ table(width="100%")
Called _just before_ Angular destroys the directive/component.
-+ifDocsFor('ts|js')
- a#interface-optional
- .l-main-section
- :marked
- ## Interfaces are optional (technically)
+a#interface-optional
+.l-main-section
+:marked
+ ## Interfaces are optional (technically)
- The interfaces are optional for JavaScript and Typescript developers from a purely technical perspective.
- The JavaScript language doesn't have interfaces.
- Angular can't see TypeScript interfaces at runtime because they disappear from the transpiled JavaScript.
+ The interfaces are optional for JavaScript and Typescript developers from a purely technical perspective.
+ The JavaScript language doesn't have interfaces.
+ Angular can't see TypeScript interfaces at runtime because they disappear from the transpiled JavaScript.
- Fortunately, they aren't necessary.
- You don't have to add the lifecycle hook interfaces to directives and components to benefit from the hooks themselves.
+ Fortunately, they aren't necessary.
+ You don't have to add the lifecycle hook interfaces to directives and components to benefit from the hooks themselves.
- Angular instead inspects directive and component classes and calls the hook methods *if they are defined*.
- Angular finds and calls methods like `ngOnInit()`, with or without the interfaces.
+ Angular instead inspects directive and component classes and calls the hook methods *if they are defined*.
+ Angular finds and calls methods like `ngOnInit()`, with or without the interfaces.
- Nonetheless, it's good practice to add interfaces to TypeScript directive classes
- in order to benefit from strong typing and editor tooling.
+ Nonetheless, it's good practice to add interfaces to TypeScript directive classes
+ in order to benefit from strong typing and editor tooling.
a#other-lifecycle-hooks
.l-main-section
@@ -173,9 +193,6 @@ a#other-lifecycle-hooks
Other Angular sub-systems may have their own lifecycle hooks apart from these component hooks.
-block other-angular-subsystems
- //- N/A for TS.
-
:marked
3rd party libraries might implement their hooks as well in order to give developers more
control over how these libraries are used.
@@ -199,13 +216,13 @@ table(width="100%")
tr
th Component
th Description
- tr(style=top)
+ tr(style=vertical-align:top)
td Peek-a-boo
td
:marked
Demonstrates every lifecycle hook.
Each hook method writes to the on-screen log.
- tr(style=top)
+ tr(style=vertical-align:top)
td Spy
td
:marked
@@ -215,33 +232,33 @@ table(width="100%")
This example applies the `SpyDirective` to a `