upgrade.jade

include ../_util-fns

:marked
  Having an existing Angular 1 application doesn't mean that we can't
  begin enjoying everything Angular 2 has to offer. That's because Angular 2
  comes with built-in tools for migrating Angular 1 projects over to the
  Angular 2 platform.

  Some applications will be easier to upgrade than others, and there are
  ways in which we can make it easier for ourselves. It is possible to
  prepare and align Angular 1 applications with Angular 2 even before beginning
  the upgrade process. These preparation steps are all about making the code
  more decoupled, more maintainable, and up to speed with modern development
  tools. That means the preparation work will not only make the eventual upgrade
  easier, but will also generally improve our Angular 1 applications.

  One of the keys to a successful upgrade is to do it incrementally,
  by running the two frameworks side by side in the same application, and
  porting Angular 1 components to Angular 2 one by one. This makes it possible
  to upgrade even large and complex applications without disrupting other
  business, because the work can be done collaboratively and spread over
  a period of time. The `upgrade` module in Angular 2 has been designed to
  make incremental upgrading seamless.

  1. [Preparation](#preparation)
      1. [Follow the Angular Style Guide](#follow-the-angular-style-guide)
      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 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)
      5. [Projecting Angular 1 Content into Angular 2 Components](#projecting-angular-1-content-into-angular-2-components)
      6. [Transcluding Angular 2 Content into Angular 1 Component Directives](#transcluding-angular-2-content-into-angular-1-component-directives)
      7. [Making Angular 1 Dependencies Injectable to Angular 2](#making-angular-1-dependencies-injectable-to-angular-2)
      8. [Making Angular 2 Dependencies Injectable to Angular 1](#making-angular-2-dependencies-injectable-to-angular-1)
  3. [PhoneCat Upgrade Tutorial](#phonecat-upgrade-tutorial)
      1. [Switching to TypeScript](#switching-to-typescript)
      2. [Installing Angular 2](#installing-angular-2)
      3. [Bootstrapping a hybrid 1+2 PhoneCat](#bootstrapping-a-hybrid-1-2-phonecat)
      4. [Upgrading the Phone service](#upgrading-the-phone-service)
      5. [Upgrading Components](#upgrading-components)
      6. [Switching To The Angular 2 Router And Bootstrap](#switching-to-the-angular-2-router-and-bootstrap)
      7. [Saying Goodbye to Angular 1](#saying-goodbye-to-angular-1)
  3. [Appendix: Upgrading PhoneCat Tests](#appendix-upgrading-phonecat-tests)

.l-main-section
:marked
  # Preparation

  There are many ways to structure Angular 1 applications. When we begin
  to upgrade these applications to Angular 2, some will turn out to be
  much more easy to work with than others. There are a few key techniques
  and patterns that we can apply to future proof our apps even before we
  begin the migration.

  ## Follow the Angular Style Guide

  The [Angular 1 Style Guide](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#single-responsibility)
  collects patterns and practices that have been proven to result in
  cleaner and more maintainable Angular 1 applications. It contains a wealth
  of information about how to write and organize Angular code - and equally
  importantly - how **not** to write and organize Angular code.

  Angular 2 is a reimagined version of the best parts of Angular 1. In that
  sense, its goals are the same as the Angular Style Guide's: To preserve
  the good parts of Angular 1, and to avoid the bad parts. There's a lot
  more to Angular 2 than just that of course, but this does mean that
  *following the style guide helps make your Angular 1 app more closely
  aligned with Angular 2*.

  There are a few rules in particular that will make it much easier to do
  *an incremental upgrade* using the Angular 2 `upgrade` module:

  * The [Rule of 1](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#single-responsibility)
    states that there should be one component per file. This not only makes
    components easy to navigate and find, but will also allow us to migrate
    them between languages and frameworks one at a time. In this example application,
    each controller, component, service, and filter is in its own source file.

  * The [Folders-by-Feature Structure](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#folders-by-feature-structure)
    and [Modularity](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#modularity)
    rules define similar principles on a higher level of abstraction: Different parts of the
    application should reside in different directories and Angular modules.

  When an application is laid out feature per feature in this way, it can also be
  migrated one feature at a time. For applications that don't already look like
  this, applying the rules in the Angular style guide is a highly recommended
  preparation step. And this is not just for the sake of the upgrade - it is just
  solid advice in general!

  ## Using a Module Loader

  When we break application code down into one component per file, we often end
  up with a project structure with a large number of relatively small files. This is
  a much neater way to organize things than a small number of large files, but it
  doesn't work that well if you have to load all those files to the HTML page with
  <script> tags. Especially when you also have to maintain those tags in the correct
  order. That's why it's a good idea to start using a *module loader*.

  Using a module loader such as [SystemJS](https://github.com/systemjs/systemjs),
  [Webpack](http://webpack.github.io/), or [Browserify](http://browserify.org/)
  allows us to use the built-in module systems of the TypeScript or ES2015 languages in our apps.
  We can use the `import` and `export` features that explicitly specify what code can
  and will be shared between different parts of the application. For ES5 applications
  we can use CommonJS style `require` and `module.exports` features. In both cases,
  the module loader will then take care of loading all the code the application needs
  in the correct order.

  When we then take our applications into production, module loaders also make it easier
  to package them all up into production bundles with batteries included.

:marked
  ## Migrating to TypeScript

  If part of our Angular 2 upgrade plan is to also take TypeScript into use, it makes
  sense to bring in the TypeScript compiler even before the upgrade itself begins.
  This means there's one less thing to learn and think about during the actual upgrade.
  It also means we can start using TypeScript features in our Angular 1 code.

  Since TypeScript is a superset of ECMAScript 2015, which in turn is a superset
  of ECMAScript 5, "switching" to TypeScript doesn't necessarily require anything
  more than installing the TypeScript compiler and switching renaming files from
  `*.js` to `*.ts`. But just doing that is not hugely useful or exciting, of course.
  Additional steps like the following can give us much more bang for the buck:

  * For applications that use a module loader, TypeScript imports and exports
    (which are really ECMAScript 2015 imports and exports) can be used to organize
    code into modules.
  * Type annotations can be gradually added to existing functions and variables
    to pin down their types and get benefits like build-time error checking,
    great autocompletion support and inline documentation.
  * JavaScript features new to ES2015, like arrow functions, `let`s and `const`s,
    default function parameters, and destructuring assignments can also be gradually
    added to make the code more expressive.
  * Services and controllers can be turned into *classes*. That way they'll be a step
    closer to becoming Angular 2 service and component classes, which will make our
    life easier once we do the upgrade.

  ## Using Component Directives

  In Angular 2, components are the main primitive from which user interfaces
  are built. We define the different parts of our UIs as components, and then
  compose the UI by using components in our templates.

  You can also do this in Angular 1, using *component directives*. These are
  directives that define their own templates, controllers, and input/output bindings -
  the same things that Angular 2 components define. Applications built with
  component directives are much easier to migrate to Angular 2 than applications
  built with lower-level features like `ng-controller`,  `ng-include`, and scope
  inheritance.

  To be Angular 2 compatible, an Angular 1 component directive should configure
  these attributes:

  * `restrict: 'E'`. Components are usually used as elements.
  * `scope: {}` - an isolate scope. In Angular 2, components are always isolated
    from their surroundings, and we should do this in Angular 1 too.
  * `bindToController: {}`. Component inputs and outputs should be bound
    to the controller instead of using the `$scope`.
  * `controller` and `controllerAs`. Components have their own controllers.
  * `template` or `templateUrl`. Components have their own templates.

  Component directives may also use the following attributes:

  * `transclude: true`, if the component needs to transclude content from elsewhere.
  * `require`, if the component needs to communicate with some parent component's
    controller.

  Component directives **may not** use the following attributes:

  * `compile`. This will not be supported in Angular 2.
  * `replace: true`. Angular 2 never replaces a component element with the
    component template. This attribute is also deprecated in Angular 1.
  * `priority` and `terminal`. While Angular 1 components may use these,
    they are not used in Angular 2 and it is better not to write code
    that relies on them.

  An Angular 1 component directive that is fully aligned with the Angular 2
  architecture may look something like this:

+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)
  that makes it easier to define directives like these. It is a good idea to use
  this API for component directives for several reasons:

  * It requires less boilerplate code.
  * It enforces the use of component best practices like `controllerAs`.
  * It has good default values for directive attributes like `scope` and `restrict`.

  The component directive example from above looks like this when expressed
  using the component API:

+makeExample('upgrade-module/ts/app/upgrade-io/hero-detail.component.ts')

:marked
  Controller lifecycle hook methods `$onInit()`, `$onDestroy()`, and `$onChanges()`
  are another convenient feature that Angular 1.5 introduces. They all have nearly
  exact [equivalents in Angular 2](lifecycle-hooks.html), so organizing component lifecycle
  logic around them will ease the eventual Angular 2 upgrade process.

.l-main-section
:marked
  # 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
  Angular 1 and 2 components in the same application and have them interoperate
  seamlessly. That means we don't have to do the upgrade work all at once,
  since there's a natural coexistence between the two frameworks during the
  transition period.

  ## 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
  both Angular 2 and Angular 1 code.

  When we use `UpgradeModule`, what we're really doing is *running both versions
  of Angular at the same time*. All Angular 2 code is running in the Angular 2
  framework, and Angular 1 code in the Angular 1 framework. Both of these are the
  actual, fully featured versions of the frameworks. There is no emulation going on,
  so we can expect to have all the features and natural behavior of both frameworks.

  What happens on top of this is that components and services managed by one
  framework can interoperate with those from the other framework. This happens
  in three main areas: Dependency injection, the DOM, and change detection.

  ### Dependency Injection

  Dependency injection is front and center in both Angular 1 and
  Angular 2, but there are some key differences between the two
  frameworks in how it actually works.

table
  tr
    th Angular 1
    th Angular 2
  tr
    td
      :marked
        Dependency injection tokens are always strings
    td
      :marked
        Tokens [can have different types](../guide/dependency-injection.html).
        They are often classes. They may also be strings.
  tr
    td
      :marked
        There is exactly one injector. Even in multi-module applications,
        everything is poured into one big namespace.
    td
      :marked
        There is a [tree hierarchy of injectors](../guide/hierarchical-dependency-injection.html),
        with a root injector and an additional injector for each component.

:marked
  Even accounting for these differences we can still have dependency injection
  interoperability. The `UpgradeModule` resolves the differences and makes
  everything work seamlessly:

  * We can make Angular 1 services available for injection to Angular 2 code
    by *upgrading* them. The same singleton instance of each service is shared
    between the frameworks. In Angular 2 these services will always be in the
    *root injector* and available to all components. They will always have
    *string tokens* - the same tokens that they have in Angular 1.
  * We can also make Angular 2 services available for injection to Angular 1 code
    by *downgrading* them. Only services from the Angular 2 root injector can
    be downgraded. Again, the same singleton instances are shared between the frameworks.
    When we register a downgrade, we explicitly specify a *string token* that we want to
    use in Angular 1.

figure.image-display
  img(src="/resources/images/devguide/upgrade/injectors.png" alt="The two injectors in a hybrid application" width="700")

:marked
  ### Components and the DOM

  What we'll find in the DOM of a hybrid application are components and
  directives from both Angular 1 and Angular 2. These components
  communicate with each other by using the input and output bindings
  of their respective frameworks, which the `UpgradeModule` bridges
  together. They may also communicate through shared injected dependencies,
  as described above.

  There are two key things to understand about what happens in the DOM
  of a hybrid application:

  1. Every element in the DOM is owned by exactly one of the two
     frameworks. The other framework ignores it. If an element is
     owned by Angular 1, Angular 2 treats it as if it didn't exist,
     and vice versa.
  2. The root of the application *is always an Angular 1 template*.

  So a hybrid application begins life as an Angular 1 application,
  and it is Angular 1 that processes its root template. Angular 2 then steps
  into the picture when an Angular 2 component is used somewhere in
  the application templates. That component's view will then be managed
  by Angular 2, and it may use any number of Angular 2 components and
  directives.

  Beyond that, we may interleave the two frameworks as much as we need to.
  We always cross the boundary between the two frameworks by one of two
  ways:

  1. By using a component from the other framework: An Angular 1 template
     using an Angular 2 component, or an Angular 2 template using an
     Angular 1 component.
  2. By transcluding or projecting content from the other framework. The
    `UpgradeModule` bridges the related concepts of  Angular 1 transclusion
     and Angular 2 content projection together.

figure.image-display
 img(src="/resources/images/devguide/upgrade/dom.png" alt="DOM element ownership in a hybrid application" width="500")

:marked
  Whenever we use a component that belongs to the other framework, a
  switch between framework boundaries occurs. However, that switch only
  happens to the *children* of the component element. Consider a situation
  where we use an Angular 2 component from Angular 1 like this:

  ```
  <ng2-component></ng2-component>
  ```

  The DOM element `<ng2-component>` will remain to be an Angular 1 managed
  element, because it's defined in an Angular 1 template. That also
  means you can apply additional Angular 1 directives to it, but *not*
  Angular 2 directives. It is only in the template of the `Ng2Component`
  component where Angular 2 steps in. This same rule also applies when you
  use Angular 1 component directives from Angular 2.

:marked
  ### Change Detection

  Change detection in Angular 1 is all about `scope.$apply()`. After every
  event that occurs, `scope.$apply()` gets called. This is done either
  automatically by the framework, or in some cases manually by our own
  code. It is the point in time when change detection occurs and data
  bindings get updated.

  In Angular 2 things are different. While change detection still
  occurs after every event, no one needs to call `scope.$apply()` for
  that to happen. This is because all Angular 2 code runs inside something
  called the [Angular zone](../api/core/index/NgZone-class.html). Angular always
  knows when the code finishes, so it also knows when it should kick off
  change detection. The code itself doesn't have to call `scope.$apply()`
  or anything like it.

  In the case of hybrid applications, the `UpgradeModule` bridges the
  Angular 1 and Angular 2 approaches. Here's what happens:

  * Everything that happens in the application runs inside the Angular 2 zone.
    This is true whether the event originated in Angular 1 or Angular 2 code.
    The zone triggers Angular 2 change detection after every event.
  * The `UpgradeModule` will invoke the Angular 1 `$rootScope.$apply()` after
    every turn of the Angular zone. This also triggers Angular 1 change
    detection after every event.

figure.image-display
  img(src="/resources/images/devguide/upgrade/change_detection.png" alt="Change detection in a hybrid application" width="600")

:marked
  What this means in practice is that we do not need to call `$apply()` in
  our code, regardless of whether it is in Angular 1 on Angular 2. The
  `UpgradeModule` does it for us. We *can* still call `$apply()` so there
  is no need to remove such calls from existing code. Those calls just don't
  have any effect in a hybrid application.


:marked
  When we downgrade an Angular 2 component and then use it from Angular 1,
  the component's inputs will be watched using Angular 1 change detection.
  When those inputs change, the corresponding properties in the component
  are set. We can also hook into the changes by implementing the
  [OnChanges](../api/core/index/OnChanges-class.html) interface in the component,
  just like we could if it hadn't been downgraded.

  Correspondingly, when we upgrade an Angular 1 component and use it from Angular 2,
  all the bindings defined for the component directive's `scope` (or `bindToController`)
  will be hooked into Angular 2 change detection. They will be treated
  as regular Angular 2 inputs and set onto the scope (or controller) when
  they change.

  ## Using UpgradeModule with Angular 2 _NgModules_

  Both Angular 1 and Angular 2 have their own concept of modules
  to help organize an application into cohesive blocks of funcionality.
  
  Their details are quite different in architecture and implementation.
  In Angular 1, you add Angular assets to the `angular.module` property.
  In Angular 2, you create one or more classes adorned with an `NgModule` decorator
  that describes Angular assets in metadata. The differences blossom from there.

  In a hybrid application we run both versions of Angular at the same time.
  That means that we need at least one module each from both Angular 1 and Angular 2.
  We will import `UpgradeModule` inside our Angular 2 module, and then use it for 
  bootstrapping our Angular 1 module. Let's see how.

.l-sub-section
  :marked
    Learn more about Angular 2 modules at the [NgModule guide](ngmodule.html).
  
:marked
  ## Bootstrapping Hybrid Angular 1+2 Applications

  The first step to upgrading an application using the `UpgradeModule` is
  always to bootstrap it as a hybrid that supports both Angular 1 and
  Angular 2.

  Pure Angular 1 applications can be bootstrapped in two ways: By using an `ng-app`
  directive somewhere on the HTML page, or by calling
  [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap)
  from JavaScript. In Angular 2, only the second method is possible - there is
  no `ng-app` in Angular 2. This is also the case for hybrid applications.
  Therefore, it is a good preliminary step to switch Angular 1 applications to use the
  JavaScript bootstrap method even before switching them to hybrid mode.

  Say we have an `ng-app` driven bootstrap such as this one:

+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-module/ts/app/1-bootstrap/app.module.ts', 'bootstrap')

:marked
  Now introduce Angular 2 to the project. Inspired by instructions in
  [the QuickStart](../quickstart.html), you can selectively copy in material from the
  <a href="https://github.com/angular/quickstart" target="_blank">QuickStart github repository</a>.

  Next, create an `app.module.ts` file and add the following `NgModule` class:

+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.

  It also imports `UpgradeModule` from `@angular/upgrade/static`, and adds an override to prevent
  Angular 2 from bootstrapping itself in the form of the `ngDoBootstrap` empty class method.

  Now we bootstrap `AppModule` using `platformBrowserDynamic`'s `bootstrapModule` method.
  Then we use dependency injection to get a hold of the `UpgradeModule` instance in `AppModule`,
  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-module/ts/app/1-2-hybrid-bootstrap/app.module.ts', 'bootstrap')

:marked
  Congratulations! You're running a hybrid Angular 1+2 application! The
  existing Angular 1 code works as before _and_ you're ready to run Angular 2 code.

:marked
  ## Using Angular 2 Components from Angular 1 Code
figure
  img(src="/resources/images/devguide/upgrade/a1-to-a2.png" alt="Using an Angular 2 component from Angular 1 code" align="left" style="width:250px; margin-left:-40px;margin-right:10px" )
:marked
  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 2 component
  in an Angular 1 context. This could be a completely new component or one that was
  previously Angular 1 but has been rewritten for Angular 2.

  Say we have a simple Angular 2 component that shows information about a hero:

+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-module/ts/app/downgrade-static/app.module.ts', 'downgradecomponent')

:marked
  Because `HeroDetailComponent` is an Angular 2 component, we must also add it to the 
  `declarations` in the `AppModule`.

  And because this component is being used from the Angular 1 module, and is an entry point into 
  our Angular 2 application, we also need to add it to the `entryComponents` for our 
  Angular 2 module.

+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.

:marked
  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-module/ts/index-downgrade-static.html', 'usecomponent')

.alert.is-helpful
  :marked
    Note that this Angular 1 is an element directive (`restrict: 'E'`) called `heroDetail`.
    An Angular 1 element directive is matched based on its _name_.
    *The `selector` metadata of the downgraded Angular 2 component is ignored.*
    

:marked
  Most components are not quite this simple, of course. Many of them
  have *inputs and outputs* that connect them to the outside world. An
  Angular 2 hero detail component with inputs and outputs might look
  like this:

+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-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
  attribute syntax to bind the inputs and outputs**. This is a requirement for downgraded
  components. The expressions themselves are still regular Angular 1 expressions.

.callout.is-important
  header Use kebab-case for downgraded component attributes
  :marked
    There's one notable exception to the rule of using Angular 2 attribute syntax
    for downgraded components. It has to do with input or output names that consist
    of multiple words. In Angular 2 we would bind these attributes using camelCase:
  code-example(format="").
    [myHero]="hero"
  :marked
    But when using them from Angular 1 templates, we need to use kebab-case:
  code-example(format="").
    [my-hero]="hero"

:marked
  The `$event` variable can be used in outputs to gain access to the
  object that was emitted. In this case it will be the `Hero` object, because
  that is what was passed to `this.deleted.emit()`.

  Since this is an Angular 1 template, we can still use other Angular 1
  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-module/ts/index-downgrade-io.html', 'userepeatedcomponent')

:marked
  ## Using Angular 1 Component Directives from Angular 2 Code
figure
  img(src="/resources/images/devguide/upgrade/a2-to-a1.png" alt="Using an Angular 1 component from Angular 2 code" align="left" style="width:250px; margin-left:-40px;margin-right:10px" )
:marked
  So, we can write an Angular 2 component and then use it from Angular 1
  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* Angular 1 component directives and then use them from
  Angular 2.

  Not all kinds of Angular 1 directives can be upgraded. The directive
  really has to be a *component directive*, with the characteristics
  [described in the preparation guide above](#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 Angular 1.5.

  A simple example of an upgradable component is one that just has a template
  and a controller:

+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 `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-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
    Upgraded componentes are Angular 2 **directives**, instead of **components**, because Angular 2
    is unaware that Angular 1 will create elements under it. As far as Angular 2 knows, the upgraded
    component is just a directive - a tag - and Angular 2 doesn't have to concern itself with
    it's children. 

:marked
  An upgraded component may also have inputs and outputs, as defined by
  the scope/controller bindings of the original Angular 1 component
  directive. When we use the component from an Angular 2 template,
  we provide the inputs and outputs using **Angular 2 template syntax**,
  with the following rules:

table
  tr
    th
    th Binding definition
    th Template syntax
  tr
    th Attribute binding
    td
      :marked
        `myAttribute: '@myAttribute'`
    td
      :marked
        `<my-component myAttribute="value">`
  tr
    th Expression binding
    td
      :marked
        `myOutput: '&myOutput'`
    td
      :marked
        `<my-component (myOutput)="action()">`
  tr
    th One-way binding
    td
      :marked
        `myValue: '<myValue'`
    td
      :marked
        `<my-component [myValue]="anExpression">`
  tr
    th Two-way binding
    td
      :marked
        `myValue: '=myValue'`
    td
      :marked
        As a two-way binding: `<my-component [(myValue)]="anExpression">`.
        Since most Angular 1 two-way bindings actually only need a one-way binding
        in practice, `<my-component [myValue]="anExpression">` is often enough.

:marked
  As an example, say we have a hero detail Angular 1 component directive
  with one input and one output:

+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-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
  ## Projecting Angular 1 Content into Angular 2 Components
figure
  img(src="/resources/images/devguide/upgrade/a1-to-a2-with-projection.png" alt="Projecting Angular 1 content into Angular 2" align="left" style="width:250px; margin-left:-40px;margin-right:10px" )
:marked
  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 `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-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-module/ts/index-1-to-2-projection.html', 'usecomponent')

.alert.is-helpful
  :marked
    When Angular 1 content gets projected inside an Angular 2 component, it still
    remains in "Angular 1 land" and is managed by the Angular 1 framework.

:marked
  ## Transcluding Angular 2 Content into Angular 1 Component Directives
figure
  img(src="/resources/images/devguide/upgrade/a2-to-a1-with-transclusion.png" alt="Projecting Angular 2 content into Angular 1" align="left" style="width:250px; margin-left:-40px;margin-right:10px" )
:marked
  Just like we can project Angular 1 content into Angular 2 components,
  we can *transclude* Angular 2 content into Angular 1 components, whenever
  we are using upgraded versions from them.

  When an Angular 1 component directive supports transclusion, it may use
  the `ng-transclude` directive in its template to mark the transclusion
  point:

+makeExample('upgrade-module/ts/app/2-to-1-transclusion/hero-detail.component.ts', null, 'hero-detail.component.ts')

.alert.is-helpful
  :marked
    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.

:marked
  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-module/ts/app/2-to-1-transclusion/container.component.ts', null, 'container.component.ts')

:marked
  ## Making Angular 1 Dependencies Injectable to Angular 2

  When running a hybrid app, we may bump into situations where we need to have
  some Angular 1 dependencies to be injected to Angular 2 code. This may be
  because we have some business logic still in Angular 1 services, or because
  we need some of Angular 1's built-in services like `$location` or `$timeout`.

  In these situations, it is possible to *upgrade* an Angular 1 provider to
  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-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-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-module/ts/app/1-to-2-providers/hero-detail.component.ts', null, 'hero-detail.component.ts')

.alert.is-helpful
  :marked
    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 Angular 1 service, factory, or
    provider can be upgraded.

:marked
  ## Making Angular 2 Dependencies Injectable to Angular 1

  In addition to upgrading Angular 1 dependencies, we can also *downgrade*
  Angular 2 dependencies, so that we can use them from Angular 1. This can be
  useful when we start migrating services to Angular 2 or creating new services
  in Angular 2 while we still have components written in Angular 1.

  For example, we might have an Angular 2 service called `Heroes`:

+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-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-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-module/ts/app/2-to-1-providers/hero-detail.component.ts', null, 'hero-detail.component.ts')





.l-main-section
:marked
  # 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 Angular 1 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 2.

  During the process we'll learn how to apply the steps outlined in the
  [preparation guide](#preparation) in practice: We'll align the application
  with Angular 2 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:

.filetree
  .file angular-phonecat
  .children
    .file bower.json
    .file karma.conf.js
    .file package.json
    .file app
    .children
      .file core
      .children
        .file checkmark
        .children
          .file checkmark.filter.js
          .file checkmark.filter.spec.js
        .file phone
        .children
          .file phone.module.js
          .file phone.service.js
          .file phone.service.spec.js
        .file core.module.js
      .file phone-detail
      .children
        .file phone-detail.component.js
        .file phone-detail.component.spec.js
        .file phone-detail.module.js
        .file phone-detail.template.html
      .file phone-list
      .children
        .file phone-list.component.js
        .file phone-list.component.spec.js
        .file phone-list.module.js
        .file phone-list.template.html
      .file img
      .children
        .file  ...
      .file phones
      .children
        .file  ...
      .file app.animations.js
      .file app.config.js
      .file app.css
      .file app.module.js
      .file index.html
    .file e2e-tests
    .children
      .file protractor-conf.js
      .file scenarios.js

:marked
  This is actually a pretty good starting point. The code uses the Angular 1.5
  component API and the organization follows the
  [Angular 1 Style Guide](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md),
  which is an important [preparation step](#following-the-angular-style-guide) 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).

:marked
  ## Switching to TypeScript

  Since we're going to be writing our Angular 2 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.

code-example(format="").
  npm i typescript --save-dev

:marked
  Let's also add run scripts for the `tsc` TypeScript compiler to `package.json`:

+makeJson('upgrade-phonecat-1-typescript/ts/package.json', {paths: 'scripts.tsc, scripts.tsc:w'}, 'package.json')


:marked
  We can now install type definitions for the existing libraries that
  we're using but that don't come with prepackaged types: Angular 1 and the 
  Jasmine unit test framework.

code-example(format="").
  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

:marked
  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 [Quickstart](../quickstart.html). It instructs the TypeScript compiler how
  to interpret our source files.

+makeJson('upgrade-phonecat-1-typescript/ts/tsconfig.ng1.json', null, 'tsconfig.json')

:marked
  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.

code-example(format="").
  npm run tsc:w

:marked
  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 Angular 1 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 Angular 1 typings we installed.
  TypeScript are checking that we are calling Angular 1 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.

+makeExample('upgrade-phonecat-1-typescript/ts/app/core/checkmark/checkmark.filter.ts', null, 'app/core/checkmark/checkmark.filter.ts')

:marked
  In the `Phone` service we can explicitly annotate the `$resource` service dependency
  as an `angular.resource.IResourceService` - a type defined by the Angular 1 typings.

+makeExample('upgrade-phonecat-1-typescript/ts/app/core/phone/phone.service.ts', null, 'app/core/phone/phone.service.ts')

:marked
  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.

+makeExample('upgrade-phonecat-1-typescript/ts/app/app.config.ts', null, 'app/app.config.ts')

.l-sub-section
  :marked
    The [Angular 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 Angular 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.

:marked
  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 2 component classes, which will make our life
  easier once we do the upgrade.

  Angular 1 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 Angular 1 will happily use it.

  Here's what our new class for the phone list component controller looks like:

+makeExample('upgrade-phonecat-1-typescript/ts/app/phone-list/phone-list.component.ts', null, 'app/phone-list/phone-list.component.ts')

:marked
  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:

+makeExample('upgrade-phonecat-1-typescript/ts/app/phone-detail/phone-detail.component.ts', null, 'app/phone-detail/phone-detail.component.ts')

:marked
  This makes our controller code look a lot more like Angular 2 already. We're
  all set to actually introduce Angular 2 into the project.

  If we had any Angular 1 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 2 service.

  ## Installing Angular 2

  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-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.

.alert.is-important 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.

:marked
  Let's install Angular 2 into the project, along with the SystemJS module loader. Take a look into the
  [Quickstart](../quickstart.html) guide and get the following configurations from there:

  * Add Angular 2 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:

code-example(format="").
  npm install

:marked
  We can soon load Angular 2 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`:

+makeJson('upgrade-phonecat-2-hybrid/ts/package.ng1.json', {paths: 'scripts.start'}, 'package.json (start script)')

:marked
  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 `<base>` tag to `index.html`, which will
  cause relative URLs to be resolved back to the `/app` directory:

+makeExample('upgrade-phonecat-2-hybrid/ts/index.html', 'base', 'index.html')

:marked
  Now we can load Angular 2 via SystemJS. We'll add the Angular 2 polyfills and the
  SystemJS config to the end of the `<head>` section, and then we'll use `System.import`
  to load the actual application:

+makeExample('upgrade-phonecat-2-hybrid/ts/index.html', 'ng2', 'index.html')

:marked
  In the `systemjs.config.js` file we got from the Quickstart we also need to make a couple
  of adjustments because of our project structure. We want to point the browser to the project
  root when loading things through SystemJS, instead of using the  `<base>` URL:

+makeExample('upgrade-phonecat-2-hybrid/ts/systemjs.config.1.js', 'paths', 'systemjs.config.js')

:marked
  ## Creating the _AppModule_

  Now create the root `NgModule` class called `AppModule`.
  There is already a file named `app.module.ts` that holds the Angular 1 module. 
  Rename it to `app.module.ng1.ts` and update the corresponding script name in the `index.html` as well.
  The file contents remain:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ng1.ts', null, 'app.module.ng1.ts')

:marked
  Now create a new `app.module.ts` with the minimum `NgModule` class:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ts', 'bare', 'app.module.ts')

:marked
  ## Bootstrapping a hybrid 1+2 PhoneCat

  What we'll do next is bootstrap the application as a *hybrid application*
  that supports both Angular 1 and Angular 2 components. Once we've done that
  we can start converting the individual pieces to Angular 2.

  To [bootstrap a hybrid application](#bootstrapping-hybrid-angular-1-2-applications),
  we first need to import `UpgradeModule` in our `AppModule`, and override it's bootstrap method:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ts', 'upgrademodule', 'app/app.module.ts')
  
:marked
  Our application is currently bootstrapped using the Angular 1 `ng-app` directive
  attached to the `<html>` element of the host page. This will no longer work with
  Angular 2. We should switch to a JavaScript-driven bootstrap instead. 
  
  So, remove the `ng-app` attribute from `index.html`, and instead boostrap via `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.

+makeExample('upgrade-phonecat-2-hybrid/ts/app/main.ts', 'bootstrap')

:marked
  The arguments used here are the root element of the application (which is
  the same element we had `ng-app` on earlier), and the Angular 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 Angular 1+2
  app.

  This means we are now running both Angular 1 and 2 at the same time. That's pretty
  exciting! We're not running any actual Angular 2 components yet though,
  so let's do that next.

.l-sub-section
  :marked
    ### Why declare _angular_ as _angular.IAngularStatic_?
    
    `@types/angular` is declared as a UMD module, and due to the way 
    <a href="https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript#support-for-umd-module-definitions" target="_blank">UMD typings</a>
    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.

    Angular 1 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 Angular 1 app to use ES6 modules in order to ensure Angular 1 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 our to Angular 2 already. 
    Instead we declare `angular` as `angular.IAngularStatic` to indicate it is a global variable
    and still have full typing support.

:marked
  ## Upgrading the Phone service

  The first piece we'll port over to Angular 2 is the `Phone` service, which
  resides in `app/core/phone/phone.service.ts` and makes it possible for components
  to load phone information from the server. Right now it's implemented with
  ngResource and we're using it for two things:

  * For loading the list of all phones into the phone list component
  * For loading the details of a single phone into the phone detail component.

  We can replace this implementation with an Angular 2 service class, while
  keeping our controllers in Angular 1 land. 
  
  In the new version, we import the Angular 2 HTTP module and call its `Http` service instead of `ngResource`.

  Re-open the `app.module.ts` file, import and add `HttpModule` to the `imports` array of the `AppModule`:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ts', 'httpmodule', 'app.module.ts')

:marked
  Now we're ready to upgrade the Phone service itself. We replace the ngResource-based
  service in `phone.service.ts` with a TypeScript class decorated as `@Injectable`:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/core/phone/phone.service.ts', 'classdef', 'app/core/phone/phone.service.ts (skeleton)')(format='.')

:marked
  The `@Injectable` decorator will attach some dependency injection metadata
  to the class, letting Angular 2 know about its dependencies. As described
  by our [Dependency Injection Guide](../guide/dependency-injection.html),
  this is a marker decorator we need to use for classes that have no other
  Angular 2 decorators but still need to have their dependencies injected.

  In its constructor the class expects to get the `Http` service. It will
  be injected to it and it is stored as a private field. The service is then
  used in the two instance methods, one of which loads the list of all phones,
  and the other the details of a particular phone:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/core/phone/phone.service.ts', 'fullclass')

:marked
  The methods now return Observables of type `PhoneData` and `PhoneData[]`. This is
  a type we don't have yet, so let's add a simple interface for it:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/core/phone/phone.service.ts', 'phonedata-interface', 'app/core/phone/phone.service.ts (interface)')(format='.')

:marked
  `@angular/upgrade/static` has a `downgradeInjectable` method for the purpose of making
  Angular 2 services available to Angular 1 code. Use it to plug in the `Phone` service:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/core/phone/phone.service.ts', 'downgrade-injectable', 'app/core/phone/phone.service.ts (downgrade)')(format='.')

:marked
  Here's the full, final code for the service:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/core/phone/phone.service.ts', null, 'app/core/phone/phone.service.ts')

:marked
  Notice that we're importing the `map` operator of the RxJS `Observable` separately.
  We need to do this for all RxJS operators that we want to use, since Angular 2
  does not load all of them by default.

  The new `Phone` service has the same features as the original, `ngResource`-based service. 
  Because it's an Angular 2 service, we register it with the `NgModule` providers:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ts', 'phone', 'app.module.ts')

:marked
  Now that we are loading `phone.service.ts` through an import that is resolved
  by SystemJS, we should **remove the &lt;script&gt; tag** for the service from `index.html`.
  This is something we'll do to all our components as we upgrade them. Simultaneously
  with the Angular 1 to 2 upgrade we're also migrating our code from scripts to modules.

  At this point we can switch our two components to use the new service
  instead of the old one. We `$inject` it as the downgraded `phone` factory,
  but it's really an instance of the `Phone` class and we can annotate its type
  accordingly:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.component.ng1.ts', null, 'app/phone-list/phone-list.component.ts')

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-detail/phone-detail.component.ng1.ts', null, 'app/phone-detail/phone-detail.component.ts')

:marked
  What we have here are two Angular 1 components using an Angular 2 service!
  The components don't need to be aware of this, though the fact that the
  service returns Observables and not Promises is a bit of a giveaway.
  In any case, what we've achieved is a migration of a service to Angular 2
  without having to yet migrate the components that use it.

.alert.is-helpful
  :marked
    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.

:marked
  ## Upgrading Components

  Next, let's upgrade our Angular 1 components to Angular 2 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 2 *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 2 component by just renaming the controller class and turning the
  Angular 1 component definition object into an Angular 2 `@Component` decorator.
  We can then also remove the static `$inject` property from the class:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.component.ts', 'initialclass', 'app/phone-list/phone-list.component.ts')

:marked
  The `selector` attribute is a CSS selector that defines where on the page the component
  should go. In Angular 1 we do matching based on component names, but in Angular 2 we
  have these explicit selectors. This one will match elements with the name `phone-list`,
  just like the Angular 1 version did.

  We now also need to convert the template of this component into Angular 2 syntax.
  The search controls replace the Angular 1 `$ctrl` expressions
  with Angular 2's two-way `[(ngModel)]` binding syntax:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.template.html', 'controls', 'app/phone-list/phone-list.template.html (search controls)')(format='.')

:marked
  Replace the list's `ng-repeat` with an `*ngFor` as 
  [described in the Template Syntax page](../guide/template-syntax.html#directives).
  Replace the image tag's `ng-src` with a binding to the native `src` property.

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.template.html', 'list', 'app/phone-list/phone-list.template.html (phones)')(format='.')

:marked
  ### No Angular 2 _filter_ or _orderBy_ filters
  The built-in Angular 1 `filter` and `orderBy` filters do not exist in Angular 2,
  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. 

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.component.ts', 'getphones', 'app/phone-list/phone-list.component.ts')

:marked
  Now we need to downgrade our Angular 2 component so we can use it in Angular 1. 
  Instead of registering a component, we register a `phoneList` *directive*, 
  a downgraded version of the Angular 2 component.

  The `as angular.IDirectiveFactory` cast tells the TypeScript compiler
  that the return value of the `downgradeComponent` method is a directive factory.

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.component.ts', 'downgrade-component', 'app/phone-list/phone-list.component.ts')

:marked
  The new `PhoneListComponent` uses the Angular 2 `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:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ts', 'phonelist', 'app.module.ts')

:marked
  Remove the &lt;script&gt; tag for the phone list component from `index.html`.

  Now set the remaining `phone-detail.component.ts` as follows:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-detail/phone-detail.component.ts', null, 'app/phone-detail/phone-detail.component.ts')

:marked
  This is similar to the phone list component. 
  The new wrinkle is the `@Inject` decorator that identifies the `$routeParams` dependency. 

  The Angular 1 injector has an Angular 1 router dependency called `$routeParams`.
  which was injected into `PhoneDetails` when it was still an Angular 1 controller.
  We intend to inject it into the new `PhoneDetailsComponent`.
  
  Unfortunately, Angular 1 dependencies are not automatically available to Angular 2 components.
  We must use a [Factory provider](#making-angular-1-dependencies-injectable-to-angular-2)
  to make `$routeParams` an Angular 2 provider.
  Do that in `app.module.ts`:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ts', 'routeparams', 'app/app.module.ts ($routeParms)')(format='.')

:marked
  Convert the phone detail component template into Angular 2 syntax as follows:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-detail/phone-detail.template.html', null, 'app/phone-detail/phone-detail.template.html')

:marked
  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 2
    does have [a very similar `ngClass`](../guide/template-syntax.html#directives)
    as Angular 1 does, its value is not magically evaluated as an expression.
    In Angular 2 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 Angular 1, Angular 2 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_:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ts', 'phonedetail', 'app.module.ts')

:marked
  We should now also remove the phone detail component &lt;script&gt; tag from `index.html`.

  ### Add the _CheckmarkPipe_

  The Angular 1 directive had a `checkmark` _filter_.
  Let's turn that into an Angular 2 **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 2 conventions:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/core/checkmark/checkmark.pipe.ts', null, 'app/core/checkmark/checkmark.pipe.ts')(format='.')

:marked
  Now import and declare the newly created pipe and
  remove the filter &lt;script&gt; tag from `index.html`:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/app.module.ts', 'checkmarkpipe', 'app.module.ts')

:marked
  ## Switching To The Angular 2 Router And Bootstrap

  At this point we've replaced all Angular 1 application components with
  their Angular 2 counterparts. 
  
  The application is still bootstrapped as a hybrid app.
  There's no need for that anymore.
  It's time to remove the last remnants of Angular 1 in two final steps:
  1. Switch to the Angular 2 router.
  1. Bootstrap as a pure Angular 2 app.

  ### Switch to the Angular 2 router
  Angular 2 has an [all-new router](router.html).

  Like all routers, it needs a place in the UI to display routed views.
  The Angular 2 that's the `<router-outlet>` 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 Angular 1 app.
  Create a new `app.component.ts` file with the following `AppComponent` class:

+makeExample('upgrade-phonecat-3-final/ts/app/app.component.ts', null, 'app/app.component.ts')(format='.')

:marked
  It has a simple template that only includes the `<router-outlet>`.
  This component just renders the contents of the active route and nothing else.
  
  The selector tells Angular 2 to plug this root component into the `<phonecat-app>` 
  element on the host web page when the application launches.

  Add this `<phonecat-app>` element to the `index.html`.
  It replaces the old Angular 1 `ng-view` directive:

+makeExample('upgrade-phonecat-3-final/ts/index.html', 'appcomponent', 'index.html (body)')(format='.')

:marked
  ### Create the _Routing Module_
  A router needs configuration whether it's the Angular 1 or Angular 2 or any other router.
  
  The details of Angular 2 router configuration are best left to the [Routing documentation](router.html) 
  which recommends that you create a `NgModule` dedicated to router configuration
  (called a _Routing Module_):

+makeExample('upgrade-phonecat-3-final/ts/app/app-routing.module.ts', null, 'app/app-routing.module.ts')

:marked
  This module defines a `routes` object with two routes to the two phone components
  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.

  Now update the `AppModule` to import this `AppRoutingModule` and also the
  declare the root `AppComponent`:

+makeExample('upgrade-phonecat-3-final/ts/app/app.module.ts', null, 'app/app.module.ts')

:marked
  The Angular 2 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:

+makeExample('upgrade-phonecat-3-final/ts/app/phone-detail/phone-detail.component.ts', null, 'app/phone-detail/phone-detail.component.ts')
:marked
  ### Generate links for each phone

  We no longer have to hardcode the links to phone details in the phone list. 
  We can generate them data binding each phone's `id` to the `routerLink` directive
  and let that directive construct the appropriate URL to the `PhoneDetailComponent`:

+makeExample('upgrade-phonecat-3-final/ts/app/phone-list/phone-list.template.html', 'list', 'app/phone-list/phone-list.template.html (list with links)')(format='.')
.l-sub-section
  :marked
    See the [Routing](router.html) page for details.

:marked
  ### Bootstrap as an Angular 2 app

  You may have noticed one extra `bootstrap` metadata property added to the `AppModule`
+makeExample('upgrade-phonecat-3-final/ts/app/app.module.ts', 'bootstrap', 'app/app.module.ts (bootstrap)')(format='.')
:marked
  That tells Angular 2 that it should bootstrap the app with the _root_ `AppComponent` and 
  insert it's view into the host web page.

  Now switch the bootstrap method of the application from the `UpgradeAdapter` 
  to the Angular 2 way. 

  Now we can drop `upgrade.bootstrap` from our application bootstrap, and remove the 
  `ngDoBootstrap()` override from `app.module.ts`

+makeExample('upgrade-phonecat-3-final/ts/app/main.ts', null, 'main.ts')
+makeExample('upgrade-phonecat-3-final/ts/app/app.module.ts', null, 'app.module.ts')

:marked
  You are now running a pure Angular 2 application!

  ## Say Goodbye to Angular 1

  It is time to take off the training wheels and let our application begin
  its new life as a pure, shiny Angular 2 app. The remaining tasks all have to
  do with removing code - which of course is every programmer's favorite task!

  If you haven't already, remove all references to the `UpgradeModule` from `app.module.ts`, 
  as well as any [Factory provider](#making-angular-1-dependencies-injectable-to-angular-2) for Angular 1 services.
  Also remove any `downgradeComponent()` you find, together with the associated Angular 1 
  directive declarations.

:marked
  You may also completely remove the following files. They are Angular 1
  module configuration files and not needed in Angular 2:

  * `app/app.module.ng1.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 Angular 1 may be uninstalled as well. The only ones
  we still need are for Jasmine and Angular 2 polyfills.

code-example(format="").
  npm uninstall @types/angular @types/angular-animate @types/angular-cookies @types/angular-mocks @types/angular-resource @types/angular-route @types/angular-sanitize --save-dev

:marked
  Finally, from `index.html`, remove all references to
  Angular 1 scripts, the Angular 2 upgrade module, and jQuery. When we're done,
  this is what it should look like:

+makeExample('upgrade-phonecat-3-final/ts/index.html', 'full', 'index.html')

:marked
  That is the last we'll see of Angular 1! It has served us well but now
  it's time to say goodbye.



.l-main-section
:marked
  # 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 an Hybrid app that we need to
  make some changes.

  The following change is needed in `protractor-conf.js` to sync with hybrid apps:
code-example(format="").
  ng12Hybrid: true
  
:marked
  The next set of changes is when we start to upgrade components and their template to Angular 2. 
  This is because the E2E tests have matchers that are specific to Angular 1. 
  For PhoneCat we need to make the following changes in order to make things work with Angular 2:

table
  tr
    th Previous code
    th New code
    th Notes
  tr
    td
      :marked
        `by.repeater('phone in $ctrl.phones').column('phone.name')`
    td
      :marked
        `by.css('.phones .name')`
    td
      :marked
        The repeater matcher relies on Angular 1 `ng-repeat`
  tr
    td
      :marked
        `by.repeater('phone in $ctrl.phones')`
    td
      :marked
        `by.css('.phones li')`
    td
      :marked
        The repeater matcher relies on Angular 1 `ng-repeat`
  tr
    td
      :marked
        `by.model('$ctrl.query')`
    td
      :marked
        `by.css('input')`
    td
      :marked
        The model matcher relies on Angular 1 `ng-model`
  tr
    td
      :marked
        `by.model('$ctrl.orderProp')`
    td
      :marked
        `by.css('select')`
    td
      :marked
        The model matcher relies on Angular 1 `ng-model`
  tr
    td
      :marked
        `by.binding('$ctrl.phone.name')`
    td
      :marked
        `by.css('h1')`
    td
      :marked
        The binding matcher relies on Angular 1 data binding


:marked
  When the bootstrap method is switched from that of `UpgradeModule` to
  pure Angular 2, Angular 1 ceases to exist on the page completely.
  At this point we need to tell Protractor that it should not be looking for
  an Angular 1 app anymore, but instead it should find *Angular 2 apps* from
  the page. 
  
  Replace the `ng12Hybrid` previously added with the following in `protractor-conf.js`:

code-example(format="").
  useAllAngular2AppRoots: true,

:marked
  Also, there are a couple of Protractor API calls in the PhoneCat test code that
  are using the Angular 1 `$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:

+makeExample('upgrade-phonecat-3-final/e2e-spec.ts', 'redirect', 'e2e-tests/scenarios.ts')

:marked
  And the second is the phone links spec:

+makeExample('upgrade-phonecat-3-final/e2e-spec.ts', 'links', 'e2e-tests/scenarios.ts')

:marked
  ## 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 Angular 1 services we're consuming:

+makeExample('upgrade-phonecat-1-typescript/ts/app/phone-detail/phone-detail.component.spec.ts', null, 'app/phone-detail/phone-detail.component.spec.ts')

:marked
  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 2 code,
  which can be done with the following kind of shim file:

+makeExample('upgrade-phonecat-2-hybrid/ts/karma-test-shim.1.js', null, 'karma-test-shim.js')

:marked
  The shim first loads the SystemJS configuration, then Angular 2'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`.

+makeExample('upgrade-phonecat-2-hybrid/ts/karma.conf.ng1.js', 'basepath', 'karma.conf.js')

:marked
  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.

+makeExample('upgrade-phonecat-2-hybrid/ts/karma.conf.ng1.js', 'files', 'karma.conf.js')

:marked
  Since the HTML templates of Angular 2 components will be loaded as well, we need to help
  Karma out a bit so that it can route them to the right paths:

+makeExample('upgrade-phonecat-2-hybrid/ts/karma.conf.ng1.js', 'html', 'karma.conf.js')

:marked
  The unit test files themselves also need to be switched to Angular 2 when their production
  counterparts are switched. The specs for the checkmark pipe are probably the most straightforward,
  as the pipe has no dependencies:

+makeExample('upgrade-phonecat-2-hybrid/ts/app/core/checkmark/checkmark.pipe.spec.ts', null, 'app/core/checkmark/checkmark.pipe.spec.ts')

:marked
  The unit test for the phone service is a bit more involved. We need to switch from the mocked-out
  Angular 1 `$httpBackend` to a mocked-out Angular 2 Http backend.

+makeExample('upgrade-phonecat-2-hybrid/ts/app/core/phone/phone.service.spec.ts', null, 'app/core/phone/phone.service.spec.ts')

:marked
  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.

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-detail/phone-detail.component.spec.ts', null, 'app/phone-detail/phone-detail.component.spec.ts')

+makeExample('upgrade-phonecat-2-hybrid/ts/app/phone-list/phone-list.component.spec.ts', null, 'app/phone-list/phone-list.component.spec.ts')


:marked
  Finally, we need to revisit both of the component tests when we switch to the Angular 2
  router. For the details component we need to provide a mock of Angular 2 `ActivatedRoute` object
  instead of using the Angular 1 `$routeParams`.

+makeExample('upgrade-phonecat-3-final/ts/app/phone-detail/phone-detail.component.spec.ts', 'activatedroute', 'app/phone-detail/phone-detail.component.spec.ts')

:marked
  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.

+makeExample('upgrade-phonecat-3-final/ts/app/phone-list/phone-list.component.spec.ts', 'routestuff', 'app/phone-list/phone-list.component.spec.ts')