rename upgrade-adapter example to upgrade-module

This commit is contained in:
Filipe Silva 2016-11-12 15:31:40 +00:00
parent 37b57fa9bb
commit 8e27ff9162
43 changed files with 38 additions and 43 deletions

View File

@ -27,8 +27,8 @@ include ../_util-fns
2. [Using a Module Loader](#using-a-module-loader)
3. [Migrating to TypeScript](#migrating-to-typescript)
4. [Using Component Directives](#using-component-directives)
2. [Upgrading with The Upgrade Adapter](#upgrading-with-the-upgrade-adapter)
1. [How The Upgrade Adapter Works](#how-the-upgrade-adapter-works)
2. [Upgrading with The Upgrade Module](#upgrading-with-the-upgrade-module)
1. [How The Upgrade Module Works](#how-the-upgrade-module-works)
2. [Bootstrapping hybrid Angular 1+2 Applications](#bootstrapping-hybrid-angular-1-2-applications)
3. [Using Angular 2 Components from Angular 1 Code](#using-angular-2-components-from-angular-1-code)
4. [Using Angular 1 Component Directives from Angular 2 Code](#using-angular-1-component-directives-from-angular-2-code)
@ -181,7 +181,7 @@ include ../_util-fns
An Angular 1 component directive that is fully aligned with the Angular 2
architecture may look something like this:
+makeExample('upgrade-adapter/ts/app/hero-detail.directive.ts')
+makeExample('upgrade-module/ts/app/hero-detail.directive.ts')
:marked
Angular 1.5 introduces the [component API](https://docs.angularjs.org/api/ng/type/angular.Module)
@ -195,7 +195,7 @@ include ../_util-fns
The component directive example from above looks like this when expressed
using the component API:
+makeExample('upgrade-adapter/ts/app/upgrade-io/hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/upgrade-io/hero-detail.component.ts')
:marked
Controller lifecycle hook methods `$onInit()`, `$onDestroy()`, and `$onChanges()`
@ -205,7 +205,7 @@ include ../_util-fns
.l-main-section
:marked
# Upgrading with The Upgrade Adapter
# Upgrading with The Upgrade Module
The `upgrade` module in Angular 2 is a very useful tool for upgrading
anything but the smallest of applications. With it we can mix and match
@ -214,7 +214,7 @@ include ../_util-fns
since there's a natural coexistence between the two frameworks during the
transition period.
## How The Upgrade Adapter Works
## How The Upgrade Module Works
The primary tool provided by the upgrade module is called the `UpgradeModule`.
This is a service that can bootstrap and manage hybrid applications that support
@ -422,14 +422,14 @@ figure.image-display
Say we have an `ng-app` driven bootstrap such as this one:
+makeExample('upgrade-adapter/ts/index-ng-app.html', null, null, {otl: /(ng-app.*ng-strict-di)/})
+makeExample('upgrade-module/ts/index-ng-app.html', null, null, {otl: /(ng-app.*ng-strict-di)/})
:marked
We can remove the `ng-app` and `ng-strict-di` directives from the HTML
and instead switch to calling `angular.bootstrap` from JavaScript, which
will result in the same thing:
+makeExample('upgrade-adapter/ts/app/1-bootstrap/app.module.ts', 'bootstrap')
+makeExample('upgrade-module/ts/app/1-bootstrap/app.module.ts', 'bootstrap')
:marked
Now introduce Angular 2 to the project. Inspired by instructions in
@ -438,7 +438,7 @@ figure.image-display
Next, create an `app.module.ts` file and add the following `NgModule` class:
+makeExample('upgrade-adapter/ts/app/1-2-hybrid-bootstrap/app.module.ts', 'ngmodule')
+makeExample('upgrade-module/ts/app/1-2-hybrid-bootstrap/app.module.ts', 'ngmodule')
:marked
This bare minimum `NgModule` imports `BrowserModule`, the module every Angular browser-based app must have.
@ -451,7 +451,7 @@ figure.image-display
and use it to bootstrap our Angular 1 app.
The `upgrade.bootstrap` method takes the exact same arguments as [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap):
+makeExample('upgrade-adapter/ts/app/1-2-hybrid-bootstrap/app.module.ts', 'bootstrap')
+makeExample('upgrade-module/ts/app/1-2-hybrid-bootstrap/app.module.ts', 'bootstrap')
:marked
Congratulations! You're running a hybrid Angular 1+2 application! The
@ -469,14 +469,14 @@ figure
Say we have a simple Angular 2 component that shows information about a hero:
+makeExample('upgrade-adapter/ts/app/downgrade-static/hero-detail.component.ts', null, 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/downgrade-static/hero-detail.component.ts', null, 'hero-detail.component.ts')
:marked
If we want to use this component from Angular 1, we need to *downgrade* it
using the `downgradeComponent()` method. What we get when we do that is an Angular 1
*directive*, which we can then register into our Angular 1 module:
+makeExample('upgrade-adapter/ts/app/downgrade-static/app.module.ts', 'downgradecomponent')
+makeExample('upgrade-module/ts/app/downgrade-static/app.module.ts', 'downgradecomponent')
:marked
Because `HeroDetailComponent` is an Angular 2 component, we must also add it to the
@ -486,7 +486,7 @@ figure
our Angular 2 application, we also need to add it to the `entryComponents` for our
Angular 2 module.
+makeExample('upgrade-adapter/ts/app/downgrade-static/app.module.ts', 'ngmodule')
+makeExample('upgrade-module/ts/app/downgrade-static/app.module.ts', 'ngmodule')
.l-sub-section
:marked
All Angular 2 components, directives and pipes must be declared in an NgModule.
@ -495,7 +495,7 @@ figure
The net resulit is an Angular 1 directive called `heroDetail`, that we can
use like any other directive in our Angular 1 templates.
+makeExample('upgrade-adapter/ts/index-downgrade-static.html', 'usecomponent')
+makeExample('upgrade-module/ts/index-downgrade-static.html', 'usecomponent')
.alert.is-helpful
:marked
@ -510,15 +510,15 @@ figure
Angular 2 hero detail component with inputs and outputs might look
like this:
+makeExample('upgrade-adapter/ts/app/downgrade-io/hero-detail.component.ts', null, 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/downgrade-io/hero-detail.component.ts', null, 'hero-detail.component.ts')
:marked
These inputs and outputs can be supplied from the Angular 1 template, and the
`downgradeComponent()` method takes care of bridging them over via the `inputs`
and `outputs` arrays:
+makeExample('upgrade-adapter/ts/app/downgrade-io/app.module.ts', 'downgradecomponent')
+makeExample('upgrade-adapter/ts/index-downgrade-io.html', 'usecomponent')
+makeExample('upgrade-module/ts/app/downgrade-io/app.module.ts', 'downgradecomponent')
+makeExample('upgrade-module/ts/index-downgrade-io.html', 'usecomponent')
:marked
Note that even though we are in an Angular 1 template, **we're using Angular 2
@ -547,7 +547,7 @@ figure
directives on the element, even though it has Angular 2 binding attributes on it.
For example, we can easily make multiple copies of the component using `ng-repeat`:
+makeExample('upgrade-adapter/ts/index-downgrade-io.html', 'userepeatedcomponent')
+makeExample('upgrade-module/ts/index-downgrade-io.html', 'userepeatedcomponent')
:marked
## Using Angular 1 Component Directives from Angular 2 Code
@ -572,21 +572,16 @@ figure
A simple example of an upgradable component is one that just has a template
and a controller:
+makeExample('upgrade-adapter/ts/app/upgrade-static/hero-detail.component.ts', 'hero-detail', 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/upgrade-static/hero-detail.component.ts', 'hero-detail', 'hero-detail.component.ts')
:marked
We can *upgrade* this component to Angular 2 using the `UpgradeAdapter`'s
`upgradeNg1Component` method. It takes the name of an Angular 1 component
directive and returns an Angular 2 **component class**.
Declare it in an `NgModule` as with other Angular 2 components:
We can *upgrade* this component to Angular 2 using the `UpgradeComponent` class.
By creating a new Angular 2 **directive** that extends `UpgradeComponent` and doing a `super` call
inside it's constructor, we have a fully upgrade Angular 1 component to be used inside Angular 2.
All that is left is to add it to `AppModule`'s `declarations` array.
+makeExample('upgrade-adapter/ts/app/upgrade-static/hero-detail.component.ts', 'hero-detail-upgrade', 'hero-detail.component.ts')
+makeExample('upgrade-adapter/ts/app/upgrade-static/app.module.ts', 'hero-detail-upgrade', 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/upgrade-static/hero-detail.component.ts', 'hero-detail-upgrade', 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/upgrade-static/app.module.ts', 'hero-detail-upgrade', 'hero-detail.component.ts')
.alert.is-helpful
:marked
@ -644,14 +639,14 @@ table
As an example, say we have a hero detail Angular 1 component directive
with one input and one output:
+makeExample('upgrade-adapter/ts/app/upgrade-io/hero-detail.component.ts', 'hero-detail-io', 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/upgrade-io/hero-detail.component.ts', 'hero-detail-io', 'hero-detail.component.ts')
:marked
We can upgrade this component to Angular 2, annotate inputs and outputs in the upgrade directive,
and then provide the input and output using Angular 2 template syntax:
+makeExample('upgrade-adapter/ts/app/upgrade-io/hero-detail.component.ts', 'hero-detail-io-upgrade', 'hero-detail.component.ts')
+makeExample('upgrade-adapter/ts/app/upgrade-io/container.component.ts', null, 'container.component.ts')
+makeExample('upgrade-module/ts/app/upgrade-io/hero-detail.component.ts', 'hero-detail-io-upgrade', 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/upgrade-io/container.component.ts', null, 'container.component.ts')
:marked
@ -662,20 +657,20 @@ figure
When we are using a downgraded Angular 2 component from an Angular 1
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 2,
there is a very similar concept called *content projection*. The `UpgradeAdapter`
there is a very similar concept called *content projection*. The `UpgradeModule`
is able to make these two features interoperate.
Angular 2 components that support content projection make use of an `<ng-content>`
tag within them. Here's an example of such a component:
+makeExample('upgrade-adapter/ts/app/1-to-2-projection/hero-detail.component.ts', null, 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/1-to-2-projection/hero-detail.component.ts', null, 'hero-detail.component.ts')
:marked
When using the component from Angular 1, we can supply contents for it. Just
like they would be transcluded in Angular 1, they get projected to the location
of the `<ng-content>` tag in Angular 2:
+makeExample('upgrade-adapter/ts/index-1-to-2-projection.html', 'usecomponent')
+makeExample('upgrade-module/ts/index-1-to-2-projection.html', 'usecomponent')
.alert.is-helpful
:marked
@ -695,7 +690,7 @@ figure
the `ng-transclude` directive in its template to mark the transclusion
point:
+makeExample('upgrade-adapter/ts/app/2-to-1-transclusion/hero-detail.component.ts', null, 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/2-to-1-transclusion/hero-detail.component.ts', null, 'hero-detail.component.ts')
.alert.is-helpful
:marked
@ -707,7 +702,7 @@ figure
If we upgrade this component and use it from Angular 2, we can populate
the component tag with contents that will then get transcluded:
+makeExample('upgrade-adapter/ts/app/2-to-1-transclusion/container.component.ts', null, 'container.component.ts')
+makeExample('upgrade-module/ts/app/2-to-1-transclusion/container.component.ts', null, 'container.component.ts')
:marked
## Making Angular 1 Dependencies Injectable to Angular 2
@ -721,18 +716,18 @@ figure
Angular 2. This makes it possible to then inject it somewhere in Angular 2
code. For example, we might have a service called `HeroesService` in Angular 1:
+makeExample('upgrade-adapter/ts/app/1-to-2-providers/heroes.service.ts', null, 'heroes.service.ts')
+makeExample('upgrade-module/ts/app/1-to-2-providers/heroes.service.ts', null, 'heroes.service.ts')
:marked
We can upgrade the service using a Angular 2 [Factory provider](../guide/dependency-injection.html#!#factory-providers)
that requests the service from the Angular 1 `$injector`. The name of the Angular 2 dependency is up to you:
+makeExample('upgrade-adapter/ts/app/1-to-2-providers/app.module.ts', 'register', 'app.module.ts')
+makeExample('upgrade-module/ts/app/1-to-2-providers/app.module.ts', 'register', 'app.module.ts')
:marked
We can then inject it in Angular 2 using a string token:
+makeExample('upgrade-adapter/ts/app/1-to-2-providers/hero-detail.component.ts', null, 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/1-to-2-providers/hero-detail.component.ts', null, 'hero-detail.component.ts')
.alert.is-helpful
:marked
@ -752,24 +747,24 @@ figure
For example, we might have an Angular 2 service called `Heroes`:
+makeExample('upgrade-adapter/ts/app/2-to-1-providers/heroes.ts', null, 'heroes.ts')
+makeExample('upgrade-module/ts/app/2-to-1-providers/heroes.ts', null, 'heroes.ts')
:marked
Again, as with Angular 2 components, register the provider with the `NgModule` by adding it to the module's `providers` list.
+makeExample('upgrade-adapter/ts/app/2-to-1-providers/app.module.ts', 'ngmodule', 'app.module.ts')
+makeExample('upgrade-module/ts/app/2-to-1-providers/app.module.ts', 'ngmodule', 'app.module.ts')
:marked
Now wrap the Angular 2 `Heroes` in an *Angular 1 factory function* using `downgradeInjectable()`.
and plug the factory into an Angular 1 module.
The name of the Angular 1 dependency is up to you:
+makeExample('upgrade-adapter/ts/app/2-to-1-providers/app.module.ts', 'register', 'app.module.ts')
+makeExample('upgrade-module/ts/app/2-to-1-providers/app.module.ts', 'register', 'app.module.ts')
:marked
After this, the service is injectable anywhere in our Angular 1 code:
+makeExample('upgrade-adapter/ts/app/2-to-1-providers/hero-detail.component.ts', null, 'hero-detail.component.ts')
+makeExample('upgrade-module/ts/app/2-to-1-providers/hero-detail.component.ts', null, 'hero-detail.component.ts')
@ -1016,7 +1011,7 @@ code-example(format="").
Having completed our preparation work, let's get going with the Angular 2
upgrade of PhoneCat. We'll do this incrementally with the help of the
[upgrade module](#upgrading-with-the-upgrade-adapter) that comes with Angular 2.
[upgrade module](#upgrading-with-the-upgrade-module) that comes with Angular 2.
By the time we're done, we'll be able to remove Angular 1 from the project
completely, but the key is to do this piece by piece without breaking the application.
@ -1091,7 +1086,7 @@ code-example(format="").
we can start converting the individual pieces to Angular 2.
To bootstrap a hybrid application, we first need to initialize an `UpgradeAdapter`,
which [provides the glue](#upgrading-with-the-upgrade-adapter) that joins the two
which [provides the glue](#upgrading-with-the-upgrade-module) that joins the two
versions of the framework together. Let's import the `UpgradeAdapter` class into a
new file `app/main.ts`. This file has been configured as the application entrypoint
in `systemjs.config.js`, so it is already being loaded by the browser.