` tag in Angular:
When AngularJS content gets projected inside an Angular component, it still
remains in "AngularJS land" and is managed by the AngularJS framework.
### Transcluding Angular Content into AngularJS Component Directives
Just like we can project AngularJS content into Angular components,
we can *transclude* Angular content into AngularJS components, whenever
we are using upgraded versions from them.
When an AngularJS component directive supports transclusion, it may use
the `ng-transclude` directive in its template to mark the transclusion
point:
The directive also needs to have the `transclude: true` option enabled.
It is on by default for component directives defined with the
1.5 component API.
If we upgrade this component and use it from Angular, we can populate
the component tag with contents that will then get transcluded:
### Making AngularJS Dependencies Injectable to Angular
When running a hybrid app, we may bump into situations where we need to have
some AngularJS dependencies to be injected to Angular code. This may be
because we have some business logic still in AngularJS services, or because
we need some of AngularJS's built-in services like `$location` or `$timeout`.
In these situations, it is possible to *upgrade* an AngularJS provider to
Angular. This makes it possible to then inject it somewhere in Angular
code. For example, we might have a service called `HeroesService` in AngularJS:
We can upgrade the service using a Angular [Factory provider](guide/dependency-injection#factory-providers)
that requests the service from the AngularJS `$injector`.
We recommend declaring the Factory Provider in a separate `ajs-upgraded-providers.ts` file
so that they are all together, making it easier to reference them, create new ones and
delete them once the upgrade is over.
It's also recommended to export the `heroesServiceFactory` function so that Ahead-of-Time
compilation can pick it up.
We can then inject it in Angular using it's class as a type annotation:
In this example we upgraded a service class, which has the added benefit that
we can use a TypeScript type annotation when we inject it. While it doesn't
affect how the dependency is handled, it enables the benefits of static type
checking. This is not required though, and any AngularJS service, factory, or
provider can be upgraded.
### Making Angular Dependencies Injectable to AngularJS
In addition to upgrading AngularJS dependencies, we can also *downgrade*
Angular dependencies, so that we can use them from AngularJS. This can be
useful when we start migrating services to Angular or creating new services
in Angular while we still have components written in AngularJS.
For example, we might have an Angular service called `Heroes`:
Again, as with Angular components, register the provider with the `NgModule` by adding it to the module's `providers` list.
Now wrap the Angular `Heroes` in an *AngularJS factory function* using `downgradeInjectable()`.
and plug the factory into an AngularJS module.
The name of the AngularJS dependency is up to you:
After this, the service is injectable anywhere in our AngularJS code:
## Using Ahead-of-time compilation with hybrid apps
We can take advantage of Ahead-of-time (AoT) compilation on hybrid apps just like on any other
Angular application.
The setup for an hybrid app is mostly the same as described in
[the Ahead-of-time Compilation chapter](guide/aot-compiler)
save for differences in `index.html` and `main-aot.ts`
Our `index.html` will likely have script tags loading AngularJS files, so the `index.html` we
use for AoT must also load those files.
An easy way to copy them is by adding each to the `copy-dist-files.js` file.
We also need to use `UpgradeModule` to bootstrap a hybrid app after bootstrapping the
Module Factory:
And that's all we need to get the full benefit of AoT for Angular apps!
The AoT metadata collector will not detect lifecycle hook methods on a parent class' prototype,
so in order for upgraded components to work we needs to implement the lifecycle hooks
on the upgraded component class and forward them to the `UpgradeComponent` parent.
## Dividing routes between Angular and AngularJS
Another important part of upgrading is upgrading routes.
We could upgrade our whole app while still using the AngularJS router and then
migrate all the routes in one fell swoop.
But it would be much better to migrate routes one by one as they become upgraded.
The first step to have a dual router setup is to add an Angular root component containing
one outlet for each router.
AngularJS will use `ng-view`, and Angular will use `router-outlet`.
When one is using it's router, the other outlet will be empty.
We want to use this component in the body of our `index.html` instead of an AngularJS component:
Next we declare both AngularJS and Angular routes as normal:
In our `app.module.ts` we need to add `AppComponent` to the declarations and boostrap array.
Next we configure the router itself.
We want to use [hash navigation](guide/router#hashlocationstrategy) in Angular
because that's what we're also using in AngularJS.
Lastly, and most importantly, we want to use a custom `UrlHandlingStrategy` that will tell
the Angular router which routes it should render - and only those.
That's it! Now we're running both routers at the same time.
## PhoneCat Upgrade Tutorial
In this section and we will look at a complete example of
preparing and upgrading an application using the `upgrade` module. The app
we're going to work on is [Angular PhoneCat](https://github.com/angular/angular-phonecat)
from [the original AngularJS tutorial](https://docs.angularjs.org/tutorial),
which is where many of us began our Angular adventures. Now we'll see how to
bring that application to the brave new world of Angular.
During the process we'll learn how to apply the steps outlined in the
[preparation guide](guide/upgrade#preparation) in practice: We'll align the application
with Angular and also take TypeScript into use.
To follow along with the tutorial, clone the
[angular-phonecat](https://github.com/angular/angular-phonecat) repository
and apply the steps as we go.
In terms of project structure, this is where our work begins:
angular-phonecat
bower.json
karma.conf.js
package.json
app
core
checkmark
checkmark.filter.js
checkmark.filter.spec.js
phone
phone.module.js
phone.service.js
phone.service.spec.js
core.module.js
phone-detail
phone-detail.component.js
phone-detail.component.spec.js
phone-detail.module.js
phone-detail.template.html
phone-list
phone-list.component.js
phone-list.component.spec.js
phone-list.module.js
phone-list.template.html
img
phones
app.animations.js
app.config.js
app.css
app.module.js
index.html
e2e-tests
protractor-conf.js
scenarios.js
This is actually a pretty good starting point. The code uses the AngularJS 1.5
component API and the organization follows the
[AngularJS Style Guide](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md),
which is an important [preparation step](guide/upgrade#follow-the-angular-styleguide) before
a successful upgrade.
* Each component, service, and filter is in its own source file, as per the
[Rule of 1](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#single-responsibility).
* The `core`, `phone-detail`, and `phone-list` modules are each in their
own subdirectory. Those subdirectories contain the JavaScript code as well as
the HTML templates that go with each particular feature. This is in line with the
[Folders-by-Feature Structure](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y152)
and [Modularity](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#modularity)
rules.
* Unit tests are located side-by-side with application code where they are easily
found, as described in the rules for
[Organizing Tests](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y197).
### Switching to TypeScript
Since we're going to be writing our Angular code in TypeScript, it makes sense to
bring in the TypeScript compiler even before we begin upgrading.
We will also start to gradually phase out the Bower package manager in favor
of NPM. We'll install all new dependencies using NPM, and will eventually be
able to remove Bower from the project.
Let's begin by installing TypeScript to the project.
npm i typescript --save-dev
Let's also add run scripts for the `tsc` TypeScript compiler to `package.json`:
We can now install type definitions for the existing libraries that
we're using but that don't come with prepackaged types: AngularJS and the
Jasmine unit test framework.
npm install @types/jasmine @types/angular @types/angular-animate @types/angular-cookies @types/angular-mocks @types/angular-resource @types/angular-route @types/angular-sanitize --save-dev
We should also configure the TypeScript compiler so that it can understand our
project. We'll add a `tsconfig.json` file to the project directory, just like we do
in the documentation [setup](guide/setup). It instructs the TypeScript compiler how
to interpret our source files.
We are telling the TypeScript compiler to turn our TypeScript files to ES5 code
bundled into CommonJS modules.
We can now launch the TypeScript compiler from the command line. It will watch
our `.ts` source files and compile them to JavaScript on the fly. Those compiled
`.js` files are then loaded into the browser by SystemJS. This is a process we'll
want to have continuously running in the background as we go along.
npm run tsc:w
The next thing we'll do is convert our JavaScript files to TypeScript. Since
TypeScript is a superset of ECMAScript 2015, which in turn is a superset
of ECMAScript 5, we can simply switch the file extensions from `.js` to `.ts`
and everything will work just like it did before. As the TypeScript compiler
runs, it emits the corresponding `.js` file for every `.ts` file and the
compiled JavaScript is what actually gets executed. If you start
the project HTTP server with `npm start`, you should see the fully functional
application in your browser.
Now that we have TypeScript though, we can start benefiting from some of its
features. There's a lot of value the language can provide to AngularJS applications.
For one thing, TypeScript is a superset of ES2015. Any app that has previously
been written in ES5 - like the PhoneCat example has - can with TypeScript
start incorporating all of the JavaScript features that are new to ES2015.
These include things like `let`s and `const`s, arrow functions, default function
parameters, and destructuring assignments.
Another thing we can do is start adding *type safety* to our code. This has
actually partially already happened because of the AngularJS typings we installed.
TypeScript are checking that we are calling AngularJS APIs correctly when we do
things like register components to Angular modules.
But we can also start adding *type annotations* for our own code to get even more
out of TypeScript's type system. For instance, we can annotate the checkmark
filter so that it explicitly expects booleans as arguments. This makes it clearer
what the filter is supposed to do.
In the `Phone` service we can explicitly annotate the `$resource` service dependency
as an `angular.resource.IResourceService` - a type defined by the AngularJS typings.
We can apply the same trick to the application's route configuration file in `app.config.ts`,
where we are using the location and route services. By annotating them accordingly TypeScript
can verify we're calling their APIs with the correct kinds of arguments.
The [AngularJS 1.x type definitions](https://www.npmjs.com/package/@types/angular)
we installed are not officially maintained by the Angular team,
but are quite comprehensive. It is possible to make an AngularJS 1.x application
fully type-annotated with the help of these definitions.
If this is something we wanted to do, it would be a good idea to enable
the `noImplicitAny` configuration option in `tsconfig.json`. This would
cause the TypeScript compiler to display a warning when there's any code that
does not yet have type annotations. We could use it as a guide to inform
us about how close we are to having a fully annotated project.
Another TypeScript feature we can make use of is *classes*. In particular, we
can turn our component controllers into classes. That way they'll be a step
closer to becoming Angular component classes, which will make our life
easier once we do the upgrade.
AngularJS expects controllers to be constructor functions. That's exactly what
ES2015/TypeScript classes are under the hood, so that means we can just plug in a
class as a component controller and AngularJS will happily use it.
Here's what our new class for the phone list component controller looks like:
What was previously done in the controller function is now done in the class
constructor function. The dependency injection annotations are attached
to the class using a static property `$inject`. At runtime this becomes the
`PhoneListController.$inject` property.
The class additionally declares three members: The array of phones, the name of
the current sort key, and the search query. These are all things we have already
been attaching to the controller but that weren't explicitly declared anywhere.
The last one of these isn't actually used in the TypeScript code since it's only
referred to in the template, but for the sake of clarity we want to define all the
members our controller will have.
In the Phone detail controller we'll have two members: One for the phone
that the user is looking at and another for the URL of the currently displayed image:
This makes our controller code look a lot more like Angular already. We're
all set to actually introduce Angular into the project.
If we had any AngularJS services in the project, those would also be
a good candidate for converting to classes, since like controllers,
they're also constructor functions. But we only have the `Phone` factory
in this project, and that's a bit special since it's an `ngResource`
factory. So we won't be doing anything to it in the preparation stage.
We'll instead turn it directly into an Angular service.
### Installing Angular
Having completed our preparation work, let's get going with the Angular
upgrade of PhoneCat. We'll do this incrementally with the help of the
[upgrade module](guide/upgrade#upgrading-with-the-upgrade-module) that comes with Angular.
By the time we're done, we'll be able to remove AngularJS from the project
completely, but the key is to do this piece by piece without breaking the application.
The project also contains some animations, which we are not yet upgrading in this version of the guide. This will change in a later release.
Let's install Angular into the project, along with the SystemJS module loader.
Take a look at the results of the [Setup](guide/setup) instructions
and get the following configurations from there:
* Add Angular and the other new dependencies to `package.json`
* The SystemJS configuration file `systemjs.config.js` to the project root directory.
Once these are done, run:
npm install
We can soon load Angular dependencies into the application via `index.html`,
but first we need to do some directory path adjustments. This is because we're going
to need to load files from `node_modules` and the project root, whereas so far
in this project everything has been loaded from the `/app` directory.
Move the `app/index.html` file to the project root directory. Then change the
development server root path in `package.json` to also point to the project root
instead of `app`:
Now we're able to serve everything from the project root to the web browser. But we do *not*
want to have to change all the image and data paths used in the application code to match
our development setup. For that reason, we'll add a `` tag to `index.html`, which will
cause relative URLs to be resolved back to the `/app` directory:
Now we can load Angular via SystemJS. We'll add the Angular polyfills and the
SystemJS config to the end of the `` section, and then we'll use `System.import`
to load the actual application:
We also need to make a couple of adjustments
to the `systemjs.config.js` file installed during [setup](guide/setup).
We want to point the browser to the project root when loading things through SystemJS,
instead of using the `` URL.
We also need to install the `upgrade` package via `npm install @angular/upgrade --save`
and add a mapping for the `@angular/upgrade/static` package.
### Creating the _AppModule_
Now create the root `NgModule` class called `AppModule`.
There is already a file named `app.module.ts` that holds the AngularJS module.
Rename it to `app.module.ajs.ts` and update the corresponding script name in the `index.html` as well.
The file contents remain:
Now create a new `app.module.ts` with the minimum `NgModule` class:
### Bootstrapping a hybrid PhoneCat
What we'll do next is bootstrap the application as a *hybrid application*
that supports both AngularJS and Angular components. Once we've done that
we can start converting the individual pieces to Angular.
To [bootstrap a hybrid application](guide/upgrade#bootstrapping-hybrid-applications),
we first need to import `UpgradeModule` in our `AppModule`, and override it's bootstrap method:
Our application is currently bootstrapped using the AngularJS `ng-app` directive
attached to the `` element of the host page. This will no longer work with
Angular. We should switch to a JavaScript-driven bootstrap instead.
So, remove the `ng-app` attribute from `index.html`, and instead bootstrap via `src/main.ts`.
This file has been configured as the application entrypoint in `systemjs.config.js`,
so it is already being loaded by the browser.
The arguments used here are the root element of the application (which is
the same element we had `ng-app` on earlier), and the AngularJS 1.x modules
that we want to load. Since we're bootstrapping the app through
an `UpgradeModule`, we're actually now running the app as a **hybrid app**.
This means we are now running both AngularJS and Angular at the same time. That's pretty
exciting! We're not running any actual Angular components yet though,
so let's do that next.
#### Why declare _angular_ as _angular.IAngularStatic_?
`@types/angular` is declared as a UMD module, and due to the way
UMD typings
work, once you have an ES6 `import` statement in a file all UMD typed modules must also be
imported via `import` statements instead of being globally available.
AngularJS is currently loaded by a script tag in `index.html`, which means that the whole app
has access to it as a global and uses the same instance of the `angular` variable.
If we used `import * as angular from 'angular'` instead we would also need to overhaul how we
load every file in our AngularJS app to use ES6 modules in order to ensure AngularJS was being
loaded correctly.
This is a considerable effort and it often isn't worth it, especially since we are in the
process of moving our code to Angular.
Instead we declare `angular` as `angular.IAngularStatic` to indicate it is a global variable
and still have full typing support.
We could also use the `toPromise` method of `Observable` to turn those
Observables into Promises in the service. This can in many cases further
reduce the amount of changes needed in the component controllers.
### Upgrading Components
Next, let's upgrade our AngularJS components to Angular components. We'll
do it one at a time, while still keeping the application in hybrid mode.
As we make these conversions, we'll also be defining our first Angular *pipes*.
Let's look at the phone list component first. Right now it contains a TypeScript
controller class and a component definition object. We can morph this into
an Angular component by just renaming the controller class and turning the
AngularJS component definition object into an Angular `@Component` decorator.
We can then also remove the static `$inject` property from the class:
The `selector` attribute is a CSS selector that defines where on the page the component
should go. In AngularJS we do matching based on component names, but in Angular we
have these explicit selectors. This one will match elements with the name `phone-list`,
just like the AngularJS version did.
We now also need to convert the template of this component into Angular syntax.
The search controls replace the AngularJS `$ctrl` expressions
with Angular's two-way `[(ngModel)]` binding syntax:
Replace the list's `ng-repeat` with an `*ngFor` as
[described in the Template Syntax page](guide/template-syntax#directives).
Replace the image tag's `ng-src` with a binding to the native `src` property.
#### No Angular _filter_ or _orderBy_ filters
The built-in AngularJS `filter` and `orderBy` filters do not exist in Angular,
so we need to do the filtering and sorting ourselves.
We replaced the `filter` and `orderBy` filters with bindings to the `getPhones()` controller method,
which implements the filtering and ordering logic inside the component itself.
Now we need to downgrade our Angular component so we can use it in AngularJS.
Instead of registering a component, we register a `phoneList` *directive*,
a downgraded version of the Angular component.
The `as angular.IDirectiveFactory` cast tells the TypeScript compiler
that the return value of the `downgradeComponent` method is a directive factory.
The new `PhoneListComponent` uses the Angular `ngModel` directive, located in the `FormsModule`.
Add the `FormsModule` to `NgModule` imports, declare the new `PhoneListComponent` and
finally add it to `entryComponents` since we downgraded it:
Remove the <script> tag for the phone list component from `index.html`.
Now set the remaining `phone-detail.component.ts` as follows:
This is similar to the phone list component.
The new wrinkle is the `RouteParams` type annotation that identifies the `routeParams` dependency.
The AngularJS injector has an AngularJS router dependency called `$routeParams`,
which was injected into `PhoneDetails` when it was still an AngularJS controller.
We intend to inject it into the new `PhoneDetailsComponent`.
Unfortunately, AngularJS dependencies are not automatically available to Angular components.
We must use a [Factory provider](guide/upgrade#making-angularjs-dependencies-injectable-to-angular)
to make `$routeParams` an Angular provider.
Do that in a new file called `ajs-upgraded-providers.ts` and import it in `app.module.ts`:
Convert the phone detail component template into Angular syntax as follows:
There are several notable changes here:
* We've removed the `$ctrl.` prefix from all expressions.
* Just like we did in the phone list, we've replaced `ng-src` with property
bindings for the standard `src` property.
* We're using the property binding syntax around `ng-class`. Though Angular
does have [a very similar `ngClass`](guide/template-syntax#directives)
as AngularJS does, its value is not magically evaluated as an expression.
In Angular we always specify in the template when an attribute's value is
a property expression, as opposed to a literal string.
* We've replaced `ng-repeat`s with `*ngFor`s.
* We've replaced `ng-click` with an event binding for the standard `click`.
* We've wrapped the whole template in an `ngIf` that causes it only to be
rendered when there is a phone present. We need this because when the component
first loads, we don't have `phone` yet and the expressions will refer to a
non-existing value. Unlike in AngularJS, Angular expressions do not fail silently
when we try to refer to properties on undefined objects. We need to be explicit
about cases where this is expected.
Add `PhoneDetailComponent` component to the `NgModule` _declarations_ and _entryComponents_:
We should now also remove the phone detail component <script> tag from `index.html`.
#### Add the _CheckmarkPipe_
The AngularJS directive had a `checkmark` _filter_.
Let's turn that into an Angular **pipe**.
There is no upgrade method to convert filters into pipes.
You won't miss it.
It's easy to turn the filter function into an equivalent Pipe class.
The implementation is the same as before, repackaged in the `transform` method.
Rename the file to `checkmark.pipe.ts` to conform with Angular conventions:
Now import and declare the newly created pipe and
remove the filter <script> tag from `index.html`:
## AoT compile the hybrid app
To use AoT with our hybrid app we have to first set it up like any other Angular application,
as shown in [the Ahead-of-time Compilation chapter](guide/aot-compiler).
Then we have to change `main-aot.ts` bootstrap also bootstrap the AngularJS app
via `UpgradeModule`:
We need to load all the AngularJS files we already use in `index.html` in `aot/index.html`
as well:
These files need to be copied together with the polyfills. Files our application
needs at runtime, like the `.json` phone lists and images, also need to be copied.
Install `fs-extra` via `npm install fs-extra --save-dev` for better file copying, and change
`copy-dist-files.js` to the following:
And that's all you need to use AoT while upgrading your app!
### Adding The Angular Router And Bootstrap
At this point we've replaced all AngularJS application components with
their Angular counterparts, even though we're still serving them from the AngularJS router.
Most AngularJS apps have more than a couple of routes though, and it's very helpful to migrate
one route at a time.
Let's start by migrating the initial `/` and `/phones` routes to Angular,
while keeping `/phones/:phoneId` in the AngularJS router.
#### Add the Angular router
Angular has an [all-new router](guide/router).
Like all routers, it needs a place in the UI to display routed views.
For Angular that's the `` and it belongs in a *root component*
at the top of the applications component tree.
We don't yet have such a root component, because the app is still managed as an AngularJS app.
Create a new `app.component.ts` file with the following `AppComponent` class:
It has a simple template that only includes the `` for Angular routes
and `ng-view` for AngularJS routes.
This component just renders the contents of the active route and nothing else.
The selector tells Angular to plug this root component into the ``
element on the host web page when the application launches.
Add this `` element to the `index.html`.
It replaces the old AngularJS `ng-view` directive:
#### Create the _Routing Module_
A router needs configuration whether it's the AngularJS or Angular or any other router.
The details of Angular router configuration are best left to the [Routing documentation](guide/router)
which recommends that you create a `NgModule` dedicated to router configuration
(called a _Routing Module_).
This module defines a `routes` object with one route to the phone list component
and a default route for the empty path.
It passes the `routes` to the `RouterModule.forRoot` method which does the rest.
A couple of extra providers enable routing with "hash" URLs such as `#!/phones`
instead of the default "push state" strategy.
There's a twist to our Routing Module though: we're also adding a custom `UrlHandlingStrategy`
that tells the Angular router to only process the `/` and `/phones` routes.
Now update the `AppModule` to import this `AppRoutingModule` and also the
declare the root `AppComponent` as the bootstrap component.
That tells Angular that it should bootstrap the app with the _root_ `AppComponent` and
insert it's view into the host web page.
We can also remove the `ngDoBootstrap()` override from `app.module.ts` since we are now
bootstrapping from Angular.
And since `PhoneListComponent` isn't being rendered from a `` tag anymore,
but rather routed to, we can do away with it's Angular selector as well.
Now we need to tell the AngularJS router to only process the `/phones/:phoneId` route:
#### Generate links for each phone
We no longer have to hardcode the links to phone details in the phone list.
We can generate data bindings for each phone's `id` to the `routerLink` directive
and let that directive construct the appropriate URL to the `PhoneDetailComponent`:
See the [Routing](guide/router) page for details.
We are now running both routers at the same time!
Angular is handling the initial `/` url, redirecting to `/phones`.
Meanwhile when we click a link to the phone detail, AngularJS takes over.
This way we can incrementally upgrade our app, reducing the risk of a massive one step router
swap.
The next step is to migrate the `/phones/:phoneId` route.
The Angular router passes route parameters differently.
Correct the `PhoneDetail` component constructor to expect an injected `ActivatedRoute` object.
Extract the `phoneId` from the `ActivatedRoute.snapshot.params` and fetch the phone data as before:
Since this was the last route we want to migrate over, we can also now delete the last
route config from `app/app.config.ts`, and add it to the Angular router configuration.
We don't need our `UrlHandlingStrategy` anymore either, since now Angular is processing all
routes.
You are now running a pure Angular application!
### Say Goodbye to AngularJS
It is time to take off the training wheels and let our application begin
its new life as a pure, shiny Angular app. The remaining tasks all have to
do with removing code - which of course is every programmer's favorite task!
The application is still bootstrapped as a hybrid app.
There's no need for that anymore.
Switch the bootstrap method of the application from the `UpgradeAdapter`
to the Angular way.
If you haven't already, remove all references to the `UpgradeModule` from `app.module.ts`,
as well as any [Factory provider](guide/upgrade#making-angularjs-dependencies-injectable-to-angular)
for AngularJS services, and the `app/ajs-upgraded-providers.ts` file.
Also remove any `downgradeInjectable()` or `downgradeComponent()` you find,
together with the associated AngularJS factory or directive declarations.
Since we have no downgraded components anymore, we also don't need to have them listed
in `entryComponents` either.
You may also completely remove the following files. They are AngularJS
module configuration files and not needed in Angular:
* `app/app.module.ajs.ts`
* `app/app.config.ts`
* `app/core/core.module.ts`
* `app/core/phone/phone.module.ts`
* `app/phone-detail/phone-detail.module.ts`
* `app/phone-list/phone-list.module.ts`
The external typings for AngularJS may be uninstalled as well. The only ones
we still need are for Jasmine and Angular polyfills.
The `@angular/upgrade` package and it's mapping in `systemjs.config.js` can also go.
npm uninstall @angular/upgrade --save
npm uninstall @types/angular @types/angular-animate @types/angular-cookies @types/angular-mocks @types/angular-resource @types/angular-route @types/angular-sanitize --save-dev
Finally, from `index.html`, remove all references to
AngularJS scripts, the Angular upgrade module, and jQuery. When we're done,
this is what it should look like:
That is the last we'll see of AngularJS! It has served us well but now
it's time to say goodbye.
## Appendix: Upgrading PhoneCat Tests
Tests can not only be retained through an upgrade process, but they can also be
used as a valuable safety measure when ensuring that the application does not
break during the upgrade. E2E tests are especially useful for this purpose.
### E2E Tests
The PhoneCat project has both E2E Protractor tests and some Karma unit tests in it.
Of these two, E2E tests can be dealt with much more easily: By definition,
E2E tests access our application from the *outside* by interacting with
the various UI elements the app puts on the screen. E2E tests aren't really that
concerned with the internal structure of the application components. That
also means that although we modify our project quite a bit during the upgrade, the E2E
test suite should keep passing with just minor modifications. This is because
we don't change how the application behaves from the user's point of view.
During TypeScript conversion, there is nothing we have to do to keep E2E tests
working. It is only when we change our bootstrap to that of a Hybrid app that we need to
make some changes.
The following change is needed in `protractor-conf.js` to sync with hybrid apps:
ng12Hybrid: true
The next set of changes is when we start to upgrade components and their template to Angular.
This is because the E2E tests have matchers that are specific to AngularJS.
For PhoneCat we need to make the following changes in order to make things work with Angular:
|
Previous code
|
New code
|
Notes
|
|
`by.repeater('phone in $ctrl.phones').column('phone.name')`
|
`by.css('.phones .name')`
|
The repeater matcher relies on AngularJS `ng-repeat`
|
|
`by.repeater('phone in $ctrl.phones')`
|
`by.css('.phones li')`
|
The repeater matcher relies on AngularJS `ng-repeat`
|
|
`by.model('$ctrl.query')`
|
`by.css('input')`
|
The model matcher relies on AngularJS `ng-model`
|
|
`by.model('$ctrl.orderProp')`
|
`by.css('select')`
|
The model matcher relies on AngularJS `ng-model`
|
|
`by.binding('$ctrl.phone.name')`
|
`by.css('h1')`
|
The binding matcher relies on AngularJS data binding
|
When the bootstrap method is switched from that of `UpgradeModule` to
pure Angular, AngularJS ceases to exist on the page completely.
At this point we need to tell Protractor that it should not be looking for
an AngularJS app anymore, but instead it should find *Angular apps* from
the page.
Replace the `ng12Hybrid` previously added with the following in `protractor-conf.js`:
useAllAngular2AppRoots: true,
Also, there are a couple of Protractor API calls in the PhoneCat test code that
are using the AngularJS `$location` service under the hood. As that
service is no longer there after the upgrade, we need to replace those calls with ones
that use WebDriver's generic URL APIs instead. The first of these is
the redirection spec:
And the second is the phone links spec:
### Unit Tests
For unit tests, on the other hand, more conversion work is needed. Effectively
they need to be *upgraded* along with the production code.
During TypeScript conversion no changes are strictly necessary. But it may be
a good idea to convert the unit test code into TypeScript as well, as the same
benefits we from TypeScript in production code also applies to tests.
For instance, in the phone detail component spec we can use not only ES2015
features like arrow functions and block-scoped variables, but also type
definitions for some of the AngularJS services we're consuming:
Once we start the upgrade process and bring in SystemJS, configuration changes
are needed for Karma. We need to let SystemJS load all the new Angular code,
which can be done with the following kind of shim file:
The shim first loads the SystemJS configuration, then Angular's test support libraries,
and then the application's spec files themselves.
Karma configuration should then be changed so that it uses the application root dir
as the base directory, instead of `app`.
Once this is done, we can load SystemJS and other dependencies, and also switch the configuration
for loading application files so that they are *not* included to the page by Karma. We'll let
the shim and SystemJS load them.
Since the HTML templates of Angular components will be loaded as well, we need to help
Karma out a bit so that it can route them to the right paths:
The unit test files themselves also need to be switched to Angular when their production
counterparts are switched. The specs for the checkmark pipe are probably the most straightforward,
as the pipe has no dependencies:
The unit test for the phone service is a bit more involved. We need to switch from the mocked-out
AngularJS `$httpBackend` to a mocked-out Angular Http backend.
For the component specs we can mock out the `Phone` service itself, and have it provide
canned phone data. We use Angular's component unit testing APIs for both components.
Finally, we need to revisit both of the component tests when we switch to the Angular
router. For the details component we need to provide a mock of Angular `ActivatedRoute` object
instead of using the AngularJS `$routeParams`.
And for the phone list component we need to set up a few things for the router itself so that
the route link directive will work.
Once we're running a hybrid app, we can start the gradual process of upgrading
code. One of the more common patterns for doing that is to use an Angular component
in an AngularJS context. This could be a completely new component or one that was
previously AngularJS but has been rewritten for Angular.
Say we have a simple Angular component that shows information about a hero:
So, we can write an Angular component and then use it from AngularJS
code. This is very useful when we start our migration from lower-level
components and work our way up. But in some cases it is more convenient
to do things in the opposite order: To start with higher-level components
and work our way down. This too can be done using the `UpgradeModule`.
We can *upgrade* AngularJS component directives and then use them from
Angular.
Not all kinds of AngularJS directives can be upgraded. The directive
really has to be a *component directive*, with the characteristics
[described in the preparation guide above](guide/upgrade#using-component-directives).
Our safest bet for ensuring compatibility is using the
[component API](https://docs.angularjs.org/api/ng/type/angular.Module)
introduced in AngularJS 1.5.
A simple example of an upgradable component is one that just has a template
and a controller:
When we are using a downgraded Angular component from an AngularJS
template, the need may arise to *transclude* some content into it. This
is also possible. While there is no such thing as transclusion in Angular,
there is a very similar concept called *content projection*. The `UpgradeModule`
is able to make these two features interoperate.
Angular components that support content projection make use of an `