356 lines
15 KiB
Plaintext
356 lines
15 KiB
Plaintext
include ../_util-fns
|
||
|
||
:marked
|
||
As the Tour of Heroes app evolves, you'll add more components that need access to hero data.
|
||
|
||
Instead of copying and pasting the same code over and over,
|
||
you'll create a single reusable data service and
|
||
inject it into the components that need it.
|
||
Using a separate service keeps components lean and focused on supporting the view,
|
||
and makes it easy to unit-test components with a mock service.
|
||
|
||
Because data services are invariably asynchronous,
|
||
you'll finish the page with a *!{_Promise}*-based version of the data service.
|
||
|
||
When you're done with this page, the app should look like this <live-example></live-example>.
|
||
|
||
.l-main-section
|
||
:marked
|
||
## Where you left off
|
||
Before continuing with the Tour of Heroes, verify that you have the following structure.
|
||
If not, go back to the previous pages.
|
||
|
||
.filetree
|
||
.file angular-tour-of-heroes
|
||
.children
|
||
.file src
|
||
.children
|
||
.file app
|
||
.children
|
||
.file app.component.ts
|
||
.file app.module.ts
|
||
.file hero.ts
|
||
.file hero-detail.component.ts
|
||
.file main.ts
|
||
.file index.html
|
||
.file styles.css
|
||
.file systemjs.config.js
|
||
.file tsconfig.json
|
||
.file node_modules ...
|
||
.file package.json
|
||
|
||
:marked
|
||
## Keep the app transpiling and running
|
||
Enter the following command in the terminal window:
|
||
|
||
code-example(language="sh" class="code-shell").
|
||
npm start
|
||
|
||
:marked
|
||
This command runs the TypeScript compiler in "watch mode", recompiling automatically when the code changes.
|
||
The command simultaneously launches the app in a browser and refreshes the browser when the code changes.
|
||
|
||
You can keep building the Tour of Heroes without pausing to recompile or refresh the browser.
|
||
|
||
## Creating a hero service
|
||
The stakeholders want to show the heroes in various ways on different pages.
|
||
Users can already select a hero from a list.
|
||
Soon you'll add a dashboard with the top performing heroes and create a separate view for editing hero details.
|
||
All three views need hero data.
|
||
|
||
At the moment, the `AppComponent` defines mock heroes for display.
|
||
However, defining heroes is not the component's job,
|
||
and you can't easily share the list of heroes with other components and views.
|
||
In this page, you'll move the hero data acquisition business to a single service that provides the data and
|
||
share that service with all components that need the data.
|
||
|
||
### Create the HeroService
|
||
Create a file in the `app` folder called `hero.service.ts`.
|
||
.l-sub-section
|
||
:marked
|
||
The naming convention for service files is the service name in lowercase followed by `.service`.
|
||
For a multi-word service name, use lower [dash-case](../guide/glossary.html#!#dash-case).
|
||
For example, the filename for `SpecialSuperHeroService` is `special-super-hero.service.ts`.
|
||
:marked
|
||
Name the class `HeroService` and export it for others to import.
|
||
|
||
+makeExample('toh-4/ts/src/app/hero.service.1.ts', 'empty-class', 'src/app/hero.service.ts (starting point)')(format=".")
|
||
|
||
:marked
|
||
### Injectable services
|
||
Notice that you imported the Angular `Injectable` function and applied that function as an `@Injectable()` decorator.
|
||
.callout.is-helpful
|
||
:marked
|
||
Don't forget the parentheses. Omitting them leads to an error that's difficult to diagnose.
|
||
:marked
|
||
The `@Injectable()` decorator tells TypeScript to emit metadata about the service.
|
||
The metadata specifies that Angular may need to inject other dependencies into this service.
|
||
|
||
Although the `HeroService` doesn't have any dependencies at the moment,
|
||
applying the `@Injectable()` decorator from the start ensures
|
||
consistency and future-proofing.
|
||
|
||
:marked
|
||
### Getting hero data
|
||
Add a `getHeroes()` method stub.
|
||
|
||
+makeExample('toh-4/ts/src/app/hero.service.1.ts', 'getHeroes-stub', 'src/app/hero.service.ts (getHeroes stub)')(format=".")
|
||
|
||
|
||
:marked
|
||
The `HeroService` could get `Hero` data from anywhere—a
|
||
web service, local storage, or a mock data source.
|
||
Removing data access from the component means
|
||
you can change your mind about the implementation anytime,
|
||
without touching the components that need hero data.
|
||
|
||
### Move the mock hero data
|
||
Cut the `HEROES` array from `app.component.ts` and paste it to a new file in the `app` folder named `mock-heroes.ts`.
|
||
Additionally, copy the `import {Hero} ...` statement because the heroes array uses the `Hero` class.
|
||
|
||
+makeExample('toh-4/ts/src/app/mock-heroes.ts', null, 'src/app/mock-heroes.ts')
|
||
:marked
|
||
The `HEROES` constant is exported so it can be imported elsewhere, such as the `HeroService`.
|
||
|
||
In `app.component.ts`, where you cut the `HEROES` array,
|
||
add an uninitialized `heroes` property:
|
||
+makeExample('toh-4/ts/src/app/app.component.1.ts', 'heroes-prop', 'src/app/app.component.ts (heroes property)')(format=".")
|
||
:marked
|
||
### Return mocked hero data
|
||
Back in the `HeroService`, import the mock `HEROES` and return it from the `getHeroes()` method.
|
||
The `HeroService` looks like this:
|
||
+makeExample('toh-4/ts/src/app/hero.service.1.ts', 'full', 'src/app/hero.service.ts')(format=".")
|
||
|
||
:marked
|
||
### Import the hero service
|
||
You're ready to use the `HeroService` in other components, starting with `AppComponent`.
|
||
|
||
Import the `HeroService` so that you can reference it in the code.
|
||
+makeExcerpt('toh-4/ts/src/app/app.component.ts', 'hero-service-import', 'src/app/app.component.ts')
|
||
:marked
|
||
### Don't use *new* with the *HeroService*
|
||
How should the `AppComponent` acquire a runtime concrete `HeroService` instance?
|
||
|
||
You could create a new instance of the `HeroService` with `new` like this:
|
||
+makeExample('toh-4/ts/src/app/app.component.1.ts', 'new-service')(format=".")
|
||
|
||
:marked
|
||
However, this option isn't ideal for the following reasons:
|
||
|
||
* The component has to know how to create a `HeroService`.
|
||
If you change the `HeroService` constructor,
|
||
you must find and update every place you created the service.
|
||
Patching code in multiple places is error prone and adds to the test burden.
|
||
* You create a service each time you use `new`.
|
||
What if the service caches heroes and shares that cache with others?
|
||
You couldn't do that.
|
||
* With the `AppComponent` locked into a specific implementation of the `HeroService`,
|
||
switching implementations for different scenarios, such as operating offline or using
|
||
different mocked versions for testing, would be difficult.
|
||
|
||
|
||
### Inject the *HeroService*
|
||
|
||
Instead of using the *new* line, you'll add two lines.
|
||
* Add a constructor that also defines a private property.
|
||
* Add to the component's `providers` metadata.
|
||
|
||
Add the constructor:
|
||
+makeExample('toh-4/ts/src/app/app.component.1.ts', 'ctor', 'src/app/app.component.ts (constructor)')
|
||
:marked
|
||
The constructor itself does nothing. The parameter simultaneously
|
||
defines a private `heroService` property and identifies it as a `HeroService` injection site.
|
||
:marked
|
||
Now Angular knows to supply an instance of the `HeroService` when it creates an `AppComponent`.
|
||
|
||
.l-sub-section
|
||
:marked
|
||
Read more about dependency injection in the [Dependency Injection](../guide/dependency-injection.html) page.
|
||
:marked
|
||
The *injector* doesn't know yet how to create a `HeroService`.
|
||
If you ran the code now, Angular would fail with this error:
|
||
code-example(format="nocode").
|
||
EXCEPTION: No provider for HeroService! (AppComponent -> HeroService)
|
||
:marked
|
||
To teach the injector how to make a `HeroService`,
|
||
add the following `providers` array property to the bottom of the component metadata
|
||
in the `@Component` call.
|
||
|
||
|
||
+makeExcerpt('toh-4/ts/src/app/app.component.1.ts', 'providers', 'src/app/app.component.ts')
|
||
|
||
:marked
|
||
The `providers` array tells Angular to create a fresh instance of the `HeroService` when it creates an `AppComponent`.
|
||
The `AppComponent`, as well as its child components, can use that service to get hero data.
|
||
a#child-component
|
||
:marked
|
||
### *getHeroes()* in the *AppComponent*
|
||
The service is in a `heroService` private variable.
|
||
|
||
You could call the service and get the data in one line.
|
||
+makeExample('toh-4/ts/src/app/app.component.1.ts', 'get-heroes')(format=".")
|
||
:marked
|
||
You don't really need a dedicated method to wrap one line. Write it anyway:
|
||
|
||
+makeExcerpt('toh-4/ts/src/app/app.component.1.ts', 'getHeroes', 'src/app/app.component.ts')
|
||
<a id="oninit"></a>
|
||
:marked
|
||
### The *ngOnInit* lifecycle hook
|
||
`AppComponent` should fetch and display hero data with no issues.
|
||
|
||
You might be tempted to call the `getHeroes()` method in a constructor, but
|
||
a constructor should not contain complex logic,
|
||
especially a constructor that calls a server, such as as a data access method.
|
||
The constructor is for simple initializations, like wiring constructor parameters to properties.
|
||
|
||
To have Angular call `getHeroes()`, you can implement the Angular *ngOnInit lifecycle hook*.
|
||
Angular offers interfaces for tapping into critical moments in the component lifecycle:
|
||
at creation, after each change, and at its eventual destruction.
|
||
|
||
Each interface has a single method. When the component implements that method, Angular calls it at the appropriate time.
|
||
.l-sub-section
|
||
:marked
|
||
Read more about lifecycle hooks in the [Lifecycle Hooks](../guide/lifecycle-hooks.html) page.
|
||
:marked
|
||
Here's the essential outline for the `OnInit` interface (don't copy this into your code):
|
||
+makeExample('toh-4/ts/src/app/app.component.1.ts', 'on-init')(format=".")
|
||
|
||
:marked
|
||
Add the implementation for the `OnInit` interface to your export statement:
|
||
code-example(format="nocode").
|
||
export class AppComponent implements OnInit {}
|
||
:marked
|
||
Write an `ngOnInit` method with the initialization logic inside. Angular will call it
|
||
at the right time. In this case, initialize by calling `getHeroes()`.
|
||
+makeExcerpt('toh-4/ts/src/app/app.component.1.ts', 'ng-on-init', 'app/app.component.ts')
|
||
:marked
|
||
The app should run as expected, showing a list of heroes and a hero detail view
|
||
when you click on a hero name.
|
||
|
||
<a id="async"></a>
|
||
:marked
|
||
## Async services and !{_Promise}s
|
||
The `HeroService` returns a list of mock heroes immediately;
|
||
its `getHeroes()` signature is synchronous.
|
||
+makeExample('toh-4/ts/src/app/app.component.1.ts', 'get-heroes')(format=".")
|
||
:marked
|
||
Eventually, the hero data will come from a remote server.
|
||
When using a remote server, users don't have to wait for the server to respond;
|
||
additionally, you aren't able to block the UI during the wait.
|
||
|
||
:marked
|
||
To coordinate the view with the response,
|
||
you can use *!{_Promise}s*, which is an asynchronous
|
||
technique that changes the signature of the `getHeroes()` method.
|
||
|
||
### The hero service makes a !{_Promise}
|
||
|
||
A *!{_Promise}* essentially promises to call back when the results are ready.
|
||
You ask an asynchronous service to do some work and give it a callback function.
|
||
The service does that work and eventually calls the function with the results or an error.
|
||
.l-sub-section
|
||
:marked
|
||
This is a simplified explanation. Read more about ES2015 Promises in the
|
||
[Promises for asynchronous programming](http://exploringjs.com/es6/ch_promises.html) page of
|
||
[Exploring ES6](http://http://exploringjs.com/es6.html).
|
||
|
||
:marked
|
||
Update the `HeroService` with this !{_Promise}-returning `getHeroes()` method:
|
||
+makeExample('toh-4/ts/src/app/hero.service.ts', 'get-heroes', 'src/app/hero.service.ts (excerpt)')(format=".")
|
||
:marked
|
||
You're still mocking the data. You're simulating the behavior of an ultra-fast, zero-latency server,
|
||
by returning an *immediately resolved !{_Promise}* with the mock heroes as the result.
|
||
|
||
### Act on the !{_Promise}
|
||
|
||
As a result of the change to `HeroService`, `this.heroes` is now set to a !{_Promise} rather than an array of heroes.
|
||
+makeExample('toh-4/ts/src/app/app.component.1.ts', 'getHeroes', 'src/app/app.component.ts (getHeroes - old)')(format=".")
|
||
|
||
:marked
|
||
You have to change the implementation to *act on the !{_Promise} when it resolves*.
|
||
When the !{_Promise} resolves successfully, you'll have heroes to display.
|
||
|
||
Pass the callback function as an argument to the !{_Promise}'s `then()` method:
|
||
+makeExample('toh-4/ts/src/app/app.component.ts', 'get-heroes', 'src/app/app.component.ts (getHeroes - revised)')(format=".")
|
||
.l-sub-section
|
||
:marked
|
||
As described in [Arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions),
|
||
the ES2015 arrow function
|
||
in the callback is more succinct than the equivalent function expression and gracefully handles `this`.
|
||
:marked
|
||
The callback sets the component's `heroes` property to the array of heroes returned by the service.
|
||
|
||
The app is still running, showing a list of heroes, and
|
||
responding to a name selection with a detail view.
|
||
.l-sub-section
|
||
:marked
|
||
At the end of this page, [Appendix: take it slow](#slow) describes what the app might be like with a poor connection.
|
||
:marked
|
||
## Review the app structure
|
||
Verify that you have the following structure after all of your refactoring:
|
||
|
||
.filetree
|
||
.file angular-tour-of-heroes
|
||
.children
|
||
.file src
|
||
.children
|
||
.file app
|
||
.children
|
||
.file app.component.ts
|
||
.file app.module.ts
|
||
.file hero.ts
|
||
.file hero-detail.component.ts
|
||
.file hero.service.ts
|
||
.file mock-heroes.ts
|
||
.file main.ts
|
||
.file index.html
|
||
.file styles.css
|
||
.file systemjs.config.js
|
||
.file tsconfig.json
|
||
.file node_modules ...
|
||
.file package.json
|
||
:marked
|
||
Here are the code files discussed in this page.
|
||
|
||
+makeTabs(`
|
||
toh-4/ts/src/app/hero.service.ts,
|
||
toh-4/ts/src/app/app.component.ts,
|
||
toh-4/ts/src/app/mock-heroes.ts
|
||
`,'',`
|
||
src/app/hero.service.ts,
|
||
src/app/app.component.ts,
|
||
src/app/mock-heroes.ts
|
||
`)
|
||
:marked
|
||
## The road you've travelled
|
||
Here's what you achieved in this page:
|
||
|
||
* You created a service class that can be shared by many components.
|
||
* You used the `ngOnInit` lifecycle hook to get the hero data when the `AppComponent` activates.
|
||
* You defined the `HeroService` as a provider for the `AppComponent`.
|
||
* You created mock hero data and imported them into the service.
|
||
* You designed the service to return a !{_Promise} and the component to get the data from the !{_Promise}.
|
||
|
||
Your app should look like this <live-example></live-example>.
|
||
|
||
## The road ahead
|
||
The Tour of Heroes has become more reusable using shared components and services.
|
||
The next goal is to create a dashboard, add menu links that route between the views, and format data in a template.
|
||
As the app evolves, you'll discover how to design it to make it easier to grow and maintain.
|
||
|
||
Read about the Angular component router and navigation among the views in the [next tutorial](toh-pt5.html) page.
|
||
|
||
.l-main-section
|
||
<a id="slow"></a>
|
||
:marked
|
||
## Appendix: Take it slow
|
||
To simulate a slow connection,
|
||
import the `Hero` symbol and add the following `getHeroesSlowly()` method to the `HeroService`.
|
||
+makeExample('toh-4/ts/src/app/hero.service.ts', 'get-heroes-slowly', 'app/hero.service.ts (getHeroesSlowly)')(format=".")
|
||
:marked
|
||
Like `getHeroes()`, it also returns a !{_Promise}.
|
||
But this !{_Promise} waits two seconds before resolving the !{_Promise} with mock heroes.
|
||
|
||
Back in the `AppComponent`, replace `getHeroes()` with `getHeroesSlowly()`
|
||
and see how the app behaves.
|