angular-cn/public/docs/ts/latest/guide/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.

  已经有了一个Angular 1的程序并不表示我们就不能喜欢Angular 2提供的一切。
  这是因为Angular 2带来了一些内建工具帮助我们把Angular 1的项目迁移到Angular 2平台。

  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.

  有些应用可能比其它的升级起来简单，还有一些方法能让我们自己把这项工作变得更简单。
  即使在正式开始升级过程之前，让Angular 1的程序提前做些准备，并向Angular 2看齐也是有可能的。
  这些准备步骤几乎都是关于如何让代码更加松耦合、更有可维护性，以及用现代开发工具提高速度的。
  这意味着，这种准备工作不仅能让最终的升级变得更简单，而且还能提升Angular 1程序的质量。

  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.

  成功升级的关键之一是增量式的实现它，通过在同一个应用中一起运行这两个框架，并且逐个把Angular 1的组件迁移到Angular 2中。
  这意味着可以在不必打断其他业务的前提下，升级更大、更复杂的应用程序，因为这项工作可以多人协作完成，并能在一段时间内逐渐铺开。
  Angular 2 `upgrade`模块的设计目标就是让你渐进、无缝的完成升级。

  1. [Preparation](#preparation)
  1. [准备工作](#preparation)
      1. [Following The Angular Style Guide](#following-the-angular-style-guide)
      1. [遵循Angular风格指南](#following-the-angular-style-guide)
      2. [Using a Module Loader](#using-a-module-loader)
      2. [使用模块加载器](#using-a-module-loader)
      3. [Migrating to TypeScript](#migrating-to-typescript)
      3. [迁移到TypeScript](#migrating-to-typescript)
      4. [Using Component Directives](#using-component-directives)
      4. [使用组件型指令](#using-component-directives)
  2. [Upgrading with The Upgrade Adapter](#upgrading-with-the-upgrade-adapter)
  2. [通过升级适配器进行升级](#upgrading-with-the-upgrade-adapter)
      1. [How The Upgrade Adapter Works](#how-the-upgrade-adapter-works)
      1. [升级适配器如何工作](#how-the-upgrade-adapter-works)
      2. [Bootstrapping Hybrid Angular 1+2 Applications](#bootstrapping-hybrid-angular-1-2-applications)
      2. [引导Angular 1和2的混合(hybrid)应用](#bootstrapping-hybrid-angular-1-2-applications)
      3. [Using Angular 2 Components from Angular 1 Code](#using-angular-2-components-from-angular-1-code)
      3. [从Angular 1的代码中使用Angular 2的组件](#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)
      4. [从Angular 2的代码中使用Angular 1的组件](#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)
      5. [把Angular 1的内容投影(project)进Angular 2组件中](#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)
      6. [把Angular 2的内容透传(transclude)到Angular 1的组件型指令中](#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)
      7. [让Angular 1提供的依赖可以被注入到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)
      8. [让Angular 2提供的依赖可以被注入到Angular 1](#making-angular-2-dependencies-injectable-to-angular-1)
  3. [PhoneCat Preparation Tutorial](#phonecat-preparation-tutorial)
  3. [PhoneCat准备工作教程](#phonecat-preparation-tutorial)
      1. [Switching to TypeScript And Module Loading](#switching-to-typescript-and-module-loading)
      1. [切换到TypeScript和模块加载器](#switching-to-typescript-and-module-loading)
      2. [Preparing Unit and E2E Tests](#preparing-unit-and-e2e-tests)
      2. [准备单元测试和E2E测试](#preparing-unit-and-e2e-tests)
      3. [Enjoying The Benefits of TypeScript](#enjoying-the-benefits-of-typescript)
      3. [享受TypeScript带来的好处](#enjoying-the-benefits-of-typescript)

  4. [PhoneCat Upgrade Tutorial](#phonecat-upgrade-tutorial)
  4. [PhoneCat升级教程](#phonecat-upgrade-tutorial)
      1. [Bootstrapping A Hybrid 1+2 PhoneCat](#bootstrapping-a-hybrid-1-2-phonecat)
      1. [引导Angular 1+2的混合版PhoneCat](#bootstrapping-a-hybrid-1-2-phonecat)
      2. [Upgrading the Phone factory](#upgrading-the-phone-factory)
      2. [升级Phone工厂](#upgrading-the-phone-factory)
      3. [Upgrading Controllers to Components](#upgrading-controllers-to-components)
      3. [把控制器升级为组件](#upgrading-controllers-to-components)
      4. [Switching To The Angular 2 Router And Bootstrap](#switching-to-the-angular-2-router-and-bootstrap)
      4. [切换到Angular 2的路由器并引导](#switching-to-the-angular-2-router-and-bootstrap)
      5. [Saying Goodbye to Angular 1](#saying-goodbye-to-angular-1)
      5. [再见，Angular 1！](#saying-goodbye-to-angular-1)

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

  Angular 1应用程序的组织方式有很多种。当我们想把它们升级到Angular 2的时候，
  有些做起来会比其它的更容易些。即使在我们开始升级之前，也有一些关键的技术和模式可以让我们将来升级时更轻松。

  ## Following The Angular Style Guide
  ## 遵循Angular风格指南

  The [Angular Style Guide](https://github.com/johnpapa/angular-styleguide)
  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风格指南](https://github.com/johnpapa/angular-styleguide)收集了一些
  已证明能写出干净且可维护的Angular 1程序的模式与实践。
  它包含了很多关于如何书写和组织Angular代码的有价值信息，同样重要的是，**不应该**如何书写和组织Angular代码。

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

  Angular 2是一个基于Angular 1中最好的部分构思出来的版本。在这种意义上，它的目标和Angular风格指南是一样的：
  保留Angular 1中好的部分，去掉坏的部分。当然，Angular 2还做了更多。
  说这些的意思是：*遵循这个风格指南可以让你写出的Angular 1程序更接近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:

  特别是某些规则会让使用Angular 2的`upgrade`模块进行*增量升级*变得更简单：

  * 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, factory, and filter is in its own source file.

  * [规则1](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#single-responsibility)
    规定应该每个文件中放一个组件。这不仅让组件更容易浏览和查找，而且还将允许我们逐个迁移它们的语言和框架。
    在这个范例程序中，每个控制器、工厂和过滤器都在它自己的源文件中。

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

  * [按特性分目录的结构](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#folders-by-feature-structure)
    和[模块化](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#modularity)
    规则在较高的抽象层定义了一些相似的原则：应用程序中的不同部分应该被分到不同的目录和Angular模块中。

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

  当我们把应用代码分解成每个文件中放一个组件之后，我们通常会得到一个由大量相对较小的文件组成的项目结构。
  这比组织成少量大文件要整洁得多，但如果你不得不通过`<script>`标签在HTML页面中加载所有这些文件，那就不好玩儿了。
  尤其是当你不得不按正确的顺序维护这些标签时更是如此。
  这就是为什么开始使用*模块加载器*是一个好主意了。

  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.

  使用模块加载器，比如[SystemJS](https://github.com/systemjs/systemjs)、
  [Webpack](http://webpack.github.io/)或[Browserify](http://browserify.org/)，
  可以让我们在程序中使用TypeScript或ES2015语言内置的模块系统。
  我们可以使用`import`和`export`特性来明确指定哪些代码应该以及将会被在程序的不同部分之间共享。
  对于ES5程序来说，我们可以改用CommonJS风格的`require`和`module.exports`特性代替。
  无是论哪种情况，模块加载器都会按正确的顺序加载程序中用到的所有代码。

  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
  ## 迁移到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.

  Angular 2升级计划的一部分是引入TypeScript，即使在开始升级之前，引入TypeScript编译器也是有意义的。
  这意味着等真正升级的时候需要学习和思考的东西更少。
  它还意味着我们可以在Angular 1代码中开始使用TypeScript的特性。

  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:

  因为TypeScript是ECMAScript 2015的一个超集，而ES2015又是ECMAScript 5的一个超集。
  这意味着除了安装一个TypeScript编译器，并把文件名都从`*.js`改成`*.ts`之外，其实什么都不用做。
  当然，如果仅仅这样做也没什么大用，也没什么令人兴奋之处。
  下面这些额外步骤可以让我们抖擞起精神来：

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

  * 对那些使用了模块加载器的程序，TypeScript的导入和导出(这实际上是ECMAScript 2015导入和导出)可以把代码组织到模块中。

  * 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 `let`s and `const`s, default function
    parameters, and destructuring assignments can also be gradually added to make
    the code more expressive.

  * 那些ES2015中新增的特性，比如`let`、`const`、默认函数参数、解构赋值等也能逐渐添加进来，让代码更有表现力。

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

  * 服务和控制器可以转成*类*。这样我们就能一步步接近Angular 2的服务和组件类了，这样等到我们开始升级时，也会更简单。

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

  在Angular 2中，组件是用来构建用户界面的主要元素。我们把UI中的不同部分定义成组件，然后通过在模板中使用这些组件最终合成为UI。

  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.

  我们在Angular 1中也能这么做。那就是一种定义了自己的模板、控制器和输入/输出绑定的指令 —— 跟Angular 2中对组件的定义是一样的。
  要迁移到Angular 2，通过组件型指令构建的应用程序会比直接用`ng-controller`、`ng-include`和作用域继承等底层特性构建的要容易得多。

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

  要做成与Angular 2兼容的，Angular 1的组件型指令应该配置下列属性：

  * `restrict: 'E'`. Components are usually used as elements.

  * `restrict: 'E'`。组件通常会以元素的方式使用。

  * `scope: {}` - an isolate scope. In Angular 2, components are always isolated
    from their surroundings, and we should do this in Angular 1 too.

  * `scope: {}` - 一个独立作用域。在Angular 2中，组件永远是从它们的环境中被隔离出来的，在Angular 1中，我们也应该这么做。

  * `bindToController: {}`. Component inputs and outputs should be bound
    to the controller instead of using the `$scope`.

  * `bindToController: {}`。组件的输入和输出应该绑定到控制器，而不是`$scope`。

  * `controller` and `controllerAs`. Components have their own controllers.

  * `controller`和`controllerAs`。组件有它们自己的控制器。

  * `template` or `templateUrl`. Components have their own templates.

  * `template`或`templateUrl`。组件有它们自己的模板。

  Component directives may also use the following attributes:

  组件型指令还可能使用下列属性：

  * `transclude: true`, if the component needs to transclude content from elsewhere.

  * `transclude: true`：如果组件需要从其它地方透传内容，就设置它。

  * `require`, if the component needs to communicate with some parent component's
    controller.

  * `require`：如果组件需要和父组件的控制器通讯，就设置它。

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

  组件型指令**不能**使用下列属性：

  * `compile`. This will not be supported in Angular 2.

  * `compile`。它在Angular 2中将不再被支持。

  * `replace: true`. Angular 2 never replaces a component element with the
    component template. This attribute is also deprecated in Angular 1.

  * `replace: true`。Angular永远不会用组件模板替换一个组件元素。这个特性在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.

  * `priority`和`terminal`。虽然Angular 1的组件可能使用这些，但它们在Angular 2中已经没用了，并且最好不要再写依赖它们的代码。

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

  Angular 1中一个完全向Angular 2架构看齐过的组件型指令看起来有点像这样：

+makeExample('upgrade-adapter/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:

  Angular 1.5引入了[组件API](https://docs.angularjs.org/api/ng/type/angular.Module)，它让像这样定义指令变得更简单了。
  为组件型指令使用这个API是一个好主意，因为：

  * It requires less boilerplate code.

  * 它需要更少的样板代码。

  * It enforces the use of component best practices like `controllerAs`.

  * 它强制使用组件的最佳实践，比如`controllerAs`。

  * It has good default values for directive attributes like `scope`,
    `restrict`, and `transclude`.

  * 对于指令中像`scope`、`restrict`和`transclude`这样的属性，它有良好的默认值。

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

  如果使用这个组件API进行快捷定义，那么上面看到的组件型指令就变成了这样：

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



.l-main-section
:marked
  # Upgrading with The Upgrade Adapter
  # 使用升级适配器进行升级

  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.

  不管要升级什么，Angular 2中的`upgrade`模块都会是一个非常有用的工具 —— 除非是小到没功能的应用。
  借助它，我们可以在同一个应用程序中混用并匹配Angular 1和2的组件，并让它们实现无缝的互操作。
  这意味着我们不用必须一次性做完所有升级工作，因为在整个演进过程中，这两个框架可以很自然的和睦相处。

  ## How The Upgrade Adapter Works
  ## 升级适配器如何工作

  The primary tool provided by the upgrade module is called the `UpgradeAdapter`.
  This is a service that can bootstrap and manage hybrid applications that support
  both Angular 2 and Angular 1 code.

  `upgrade`模块提供的主要工具叫做`UpgradeAdapter`。这是一个服务，它可以引导并管理同时支持Angular 2和Angular 1的混合应用程序。

  When we use `UpgradeAdapter`, 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.

  当使用`UpgradeAdapter`时，我们实际做的是*同时运行两个版本的Angular*。所有Angular 2的代码运行在Angular 2框架中，
  而Angular 1的代码运行在Angular 1框架中。所有这些都是真实的、全功能的框架版本。
  没有进行任何仿真，所以我们可以期待同时存在这两个框架的所有特性和天生的行为。

  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.

  所有这些事情的背后，本质上是一个框架中管理的组件和服务能和来自另一个中的进行互操作。
  这发生在三个主要的领域：依赖注入、DOM和变更检测。

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

  无论是在Angular 1中还是在Angular 2中，依赖注入都处于前沿和中心的位置，但在两个框架的工作原理上，却存在着一些关键的不同之处。

table
  tr
    th Angular 1
    th Angular 2
  tr
    td
      :marked
        Dependency injection tokens are always strings

        依赖注入的令牌(Token)永远是字符串(译注：指服务名称)。
    td
      :marked
        Tokens [can have different types](../guide/dependency-injection.html).
        They are often classes. They may also be strings.

        令牌[可能有不同的类型](../guide/dependency-injection.html)。
        通常是类，也可能是字符串。
  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.

        有一组[树状多层注入器](../guide/hierarchical-dependency-injection.html)，有一个根注入器，每个组件也有一个额外的注入器。

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

  就算有这么多不同点，也并不妨碍我们在依赖注入时进行互操作。`UpgradeAdapter`解决了这些差异，并让它们无缝的对接：

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

  * 通过升级它们，我们就能让那些在Angular 1中能被注入的服务在Angular 2的代码中可用。
    在框架之间共享的是服务的同一个单例对象。在Angular 2中，这些外来服务总是被放在*根注入器*中，并可用于所有组件。
    它们总是具有*字符串令牌* —— 跟它们在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.

  * 通过降级它们，我们也能让那些在Angular 2中能被注入的服务在Angular 1的代码中可用。
    只有那些来自Angular 2根注入器的服务才能被降级。同样的，在框架之间共享的是同一个单例对象。
    当我们注册一个要降级的服务时，要明确指定一个打算在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
  ### 组件与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 `UpgradeAdapter` bridges
  together. They may also communicate through shared injected dependencies,
  as described above.

  在混合应用中，我们能同时发现那些来自Angular 1和Angular 2中组件和指令的DOM。
  这些组件通过它们各自框架中的输入和输出绑定来互相通讯，它们由`UpgradeAdapter`桥接在一起。
  它们也能通过共享被注入的依赖彼此通讯，就像前面所说的那样。

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

  要弄明白在一个混合应用的DOM中发生了什么，有两点很关键：

  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.

  1. DOM中的每个元素都只能被两个框架之一拥有。另一个框架会忽略它。
     如果一个元素被Angular 1拥有，Angular 2就会当它不存在。反之亦然。

  2. The root of the application *is always an Angular 1 template*.

  2. 应用的根节点*总是来自Angular 1中的模板*。

  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.

  所以，混合应用总是像Angular 1程序那样启动，处理根模板的也是Angular 1.
  然后，当这个应用的模板中使用到了Angular 2的组件时，Angular 2才开始参与。
  这个组件的视图由Angular 2进行管理，而且它还可以使用一系列的Angular 2组件和指令。

  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.

  1. 通过使用来自另一个框架的组件：Angular 1的模板中用到了Angular 2的组件，或者Angular 2的模板中使用了Angular 1的组件。

  2. By transcluding or projecting content from the other framework. The
    `UpgradeAdapter` bridges the related concepts of  Angular 1 transclusion
     and Angular 2 content projection together.

  2. 通过透传(transclude)或投影(project)来自另一个框架的内容。`UpgradeAdapter`牵线搭桥，把Angular 1的透传概念和Angular 2的内容投影概念关联起来。

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:

  无论什么时候，只要我们用到了来自另一个框架的组件，就会发生框架边界的切换。然而，这种切换只会发生在组件元素的*子节点*上。
  考虑一个场景，我们从Angular 1中像这样使用Angular 2的组件：

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

  此时，`<ng2-component>`这个DOM元素仍然由Angular 1管理，因为它是在Angular 1的模板中定义的。
  这也意味着你可以往它上面添加额外的Angular 1指令，却*不能*添加Angular 2的指令。
  只有在`Ng2Component`组件的模板中才是Angular 2的天下。同样的规则也适用于在Angular 2中使用Angular 1组件型指令的情况。

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

  Angular 1中的变更检测全是关于`scope.$apply()`的。在每个事件发生之后，`scope.$apply()`就会被调用。
  这或者由框架自动调用，或者在某些情况下由我们自己的代码手动调用。它是发生变更检测以及更新数据绑定的时间点。

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

  在Angular 2中，事情有点不一样。虽然变更检测仍然会在每一个事件之后发生，却不再需要每次调用`scope.$apply()`了。
  这是因为所有Angular 2代码都运行在一个叫做[Angular zone](../api/core/NgZone-class.html)的地方。
  Angular总是知道什么时候代码执行完了，也就知道了它什么时候应该触发变更检测。代码本身并不需要调用`scope.$apply()`或其它类似的东西。

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

  在这种混合应用的案例中，`UpgradeAdapter`在Angular 1的方法和Angular 2的方法之间建立了桥梁。发生了什么呢？

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

  * 应用中发生的每件事都运行在Angular 2的zone里。
    无论事件发生在Angular 1还是Angular 2的代码中，都是如此。

  * The `UpgradeAdapter` will invoke the Angular 1 `$rootScope.$apply()` after
    every turn of the Angular zone. This also triggers Angular 1 change
    detection after every event.

  * `UpgradeAdapter`将在每一次离开Angular zone时调用Angular 1的`$rootScope.$apply()`。这样也就同样会在每个事件之后触发Angular 1的变更检测。

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

  在实践中，这意味着我们不用在自己的代码中调用`$apply()`，而不用管这段代码是在Angular 1还是Angular 2中。
  `UpgradeAdapter`都替我们做了。我们仍然*可以*调用`$apply()`，以便可以不必从现有代码中移除此调用。
  在混合应用中，那些调用只是没有任何效果而已。

: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/OnChanges-interface.html) interface in the component,
  just like we could if it hadn't been downgraded.

  当我们降级一个Angular 2组件，然后把它用于Angular 1中时，组件的输入属性就会被Angular 1的变更检测体系监视起来。
  当那些输入属性发生变化时，组件中相应的属性就会被设置。我们也能通过实现[OnChanges](../api/core/OnChanges-interface.html)
  接口来挂钩到这些更改，就像它未被降级时一样。

  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.

  相应的，当我们把Angular 1的组件升级给Angular 2使用时，在这个组件型指令的`scope`(或`bindToController`)中定义的所有绑定
  都将被挂钩到Angular 2的变更检测体系中。它们将和标准的Angular 2输入属性被同等对待，并当它们发生变化时设置回scope(或控制器)上。

  ## Bootstrapping Hybrid Angular 1+2 Applications
  ## 引导Angular 1+2的混合应用程序

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

  使用`UpgradeAdapter`升级应用的第一步总是把它引导成一个同时支持Angular 1和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.

  纯粹的Angular 1应用可以用两种方式引导：在HTML页面中的某处使用`ng-app`指令，或者从JavaScript中调用
  [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap)。
  在Angular 2中，只有第二种方法是可行的，因为它没有`ng-app`指令。在混合应用中也同样只能用第二种方法。
  所以，即使在把Angular 1应用切换到混合模式之前，把它改为用JavaScript引导的方式也是一个不错的起点。

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

  比如说我们有个由`ng-app`驱动的引导过程，就像这个：

+makeExample('upgrade-adapter/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:

  我们可以从HTML中移除`ng-app`和`ng-strict-di`指令，改为从JavaScript中调用`angular.bootstrap`，它能达到同样效果：

+makeExample('upgrade-adapter/ts/app/1-bootstrap/app.module.ts', 'bootstrap')

:marked
  To then switch the application into hybrid mode, we must first
  install Angular 2 to the project. Follow the instructions in
  [the QuickStart](../quickstart.html) for some pointers on this.
  When we have Angular 2 installed, we can import and instantiate
  the `UpgradeAdapter`, and then call its `bootstrap` method. It
  is designed to take the exact same arguments as
  [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap)
  so that it is easy to make the switch:

  要把这个应用切换到混合模式，我们得先把Angular 2安装到项目中。遵循[“快速起步”](../quickstart.html)中给出的步骤完成它。
  安装完Angular 2之后，我们可以导入和实例化`UpgradeAdapter`类，然后调用它的`bootstrap`方法。
  它被设计成接受与[angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap)完全相同的参数。
  所以，做这种切换很简单：

+makeExample('upgrade-adapter/ts/app/1-2-hybrid-bootstrap/app.module.ts', 'bootstrap')

:marked
  At this point we'll be running a hybrid Angular 1+2 application! All the
  existing Angular 1 code will work as it always did, but we are now ready
  to run Angular 2 code as well.

  这时，我们就要开始运行Angular 1+2的混合应用程序了！所有现存的Angular 1代码会像以前一样正常工作，但是我们现在也同样可以运行Angular 2代码了。

.alert.is-helpful
  :marked
    One notable difference between `angular.bootstrap` and
    `upgradeAdapter.bootstrap` is that the latter works *asynchronously*.
    This means that we cannot assume that the application has been instantiated
    immediately after the bootstrap call returns.

    在`angular.bootstrap`和`upgradeAdapter.bootstrap`之间一个显著的不同点是：后者是*异步*工作的。
    这意味着当这次`bootstrap`调用刚刚返回时，我们不能假设应用程序已经被初始化过了。

:marked
  As we begin to migrate components to Angular 2, we'll be using the
  `UpgradeAdapter` for more than just bootstrapping. It'll be important
  to use the **same** instance of the adapter across the whole application,
  because it stores internal information about what's going on in the application.
  It'll be useful to have a module for a shared `UpgradeAdapter` instance in
  the project:

  当我们开始把组件移植到Angular 2时，我们还将使用`UpgradeAdapter` —— 不止是进行引导。
  在整个应用程序中使用此适配器的**同一个**实例是非常重要的，因为它保存了关于该应用程序当前状态的内部信息：

+makeExample('upgrade-adapter/ts/app/1-2-hybrid-shared-adapter-bootstrap/upgrade_adapter.ts', null, 'upgrade_adapter.ts')

:marked
  This shared instance can then be pulled in to all the modules that need it:

  然后这个共享的实例就能被所有需要它的模块获取到：

+makeExample('upgrade-adapter/ts/app/1-2-hybrid-shared-adapter-bootstrap/app.module.ts', 'bootstrap')

:marked
  ## Using Angular 2 Components from Angular 1 Code
  ## 在Angular 1的代码中使用Angular 2的组件
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.

  一旦我们开始运行混合应用，我们就可以开始逐渐升级代码了。做这件事的一种更常见的模式就是在Angular 1的上下文中使用Angular 2的组件。
  该组件可能是全新的，也可能是把原本Angular 1的组件用Angular 2重写而成的。

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

  假设我们有一个简单的用来显示英雄信息的Angular 2组件：

+makeExample('upgrade-adapter/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 upgrade adapter. 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')

:marked
  What we have here is an Angular 1 directive called `heroDetail`, which we can
  use like any other directive in our Angular 1 templates.

+makeExample('upgrade-adapter/ts/index-downgrade-static.html', 'usecomponent')

.alert.is-helpful
  :marked
    Note that since Angular 1 directives are matched based on their name,
    *the selector metadata of the Angular 2 component is not used in Angular 1*.
    It is matched as an element directive (`restrict: 'E'`) called `heroDetail`.

: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-adapter/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
  `UpgradeAdapter` takes care of bridging them over:

+makeExample('upgrade-adapter/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.

  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-adapter/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 `UpgradeAdapter`.
  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-adapter/ts/app/upgrade-static/hero-detail.component.ts', null, '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**. When we then
  want to use it from an Angular 2 component, we list it the in the `directives`
  metadata of the component and then just use it in the Angular 2 template:

+makeExample('upgrade-adapter/ts/app/upgrade-static/container.component.ts', null, 'container.component.ts')

.alert.is-helpful
  :marked
    Upgraded components always have an element selector, which is based
    on the original name of the original Angular 1 component directive.


: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 Two-way binding
    td
      :marked
        `myValue: '=myValue'`
    td
      :marked
        As input: `<my-component [myValue]="anExpression">` or
        as two-way binding: `<my-component [(myValue)]="anExpression"`

:marked
  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', null, 'hero-detail.component.ts')

:marked
  We can upgrade this component to Angular 2, and then provide the input
  and output using Angular 2 template syntax:

+makeExample('upgrade-adapter/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 `UpgradeAdapter`
  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')

: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')

.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-adapter/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-adapter/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-adapter/ts/app/1-to-2-providers/heroes.service.ts', null, 'heroes.service.ts')

:marked
  We can upgrade the service using the `UpgradeAdapter`'s `upgradeNg1Provider` method
  by giving it the name of the service. This adds the service into Angular 2's root injector.

+makeExample('upgrade-adapter/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 that matches
  its original name in Angular 1:

+makeExample('upgrade-adapter/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-adapter/ts/app/2-to-1-providers/heroes.ts', null, 'heroes.ts')

:marked
  We can again use the `UpgradeAdapter` for this, but first we need to register `Heroes`
  to the Angular 2 injector itself. In a pure Angular 2 application we would do this
  when we bootstrap the app, as described in the [dependency injection guide](dependency-injection.html#!#providers).
  But since hybrid applications are bootstrapped using the `UpgradeAdapter`, we also
  need to register our Angular 2 providers using `UpgradeAdapter`. It has a method
  called `addProvider` for this purpose.

  Once we've registered the Angular 2 provider, we can turn `Heroes` into an *Angular 1
  factory function* using `upgradeAdapter.downgradeNg2Provider()`. We can
  then plug the factory into an Angular 1 module, at which point we also choose what the
  name of the dependency will be in Angular 1:

+makeExample('upgrade-adapter/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')

.l-main-section
:marked
  # PhoneCat Preparation Tutorial

  In this section and the one following it 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 both the SystemJS module loader and 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

.alert.is-important
  :marked
    If you do clone this repository, note that it doesn't look like this guide
    assumes yet. There's [a pull request](https://github.com/angular/angular-phonecat/pull/289)
    that will change this. Meanwhile, you'll find a good starting point from
    [this commit](https://github.com/teropa/angular-phonecat/commit/d6fb83e1c2db9d1812c7c478fdb8d92301ef0061).

:marked
  In terms of project structure, this is where our work begins

.filetree
  .file angular-phonecat
  .children
    .file bower.json
    .file package.json
    .file app
    .children
      .file js
      .children
        .file core
        .children
          .file checkmark.filter.js
          .file core.module.js
          .file phone.factory.js
        .file phone_detail
        .children
          .file phone_detail.html
          .file phone_detail.module.js
          .file phone_detail.controller.js
        .file phone_list
        .children
          .file phone_list.html
          .file phone_list.module.js
          .file phone_list.controller.js
        .file app.module.js
      .file css
      .children
        .file animations.css
        .file app.css
      .file img
      .children
        .file  ...
      .file phones
      .children
        .file  ...
      .file index.html
    .file test
    .children
      .file e2e
      .children
        .file scenarios.js
      .file unit
      .children
        .file checkmark.filter.spec.js
        .file phone_detail.controller.spec.js
        .file phone.factory.spec.js
        .file phone_list.controller.spec.js
      .file karma.conf.js
      .file protractor-conf.js

:marked
  This is actually a pretty good starting point. In particular, this organization
  follows the [Angular Style Guide](https://github.com/johnpapa/angular-styleguide),
  which is an important [preparation step](#following-the-angular-style-guide) before
  a successful upgrade.

  * Each controller, factory, and filter is in its own source file, as per the
    [Rule of 1](https://github.com/johnpapa/angular-styleguide#single-responsibility).
  * The `core`, `phoneDetail`, and `phoneList` 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#style-y152)
    and [Modularity](https://github.com/johnpapa/angular-styleguide#modularity)
    rules.

:marked
  ## Switching to TypeScript And Module Loading

  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.

  In order to use TypeScript's ES2015 module system to `import` and `export` code, we're
  going to need a JavaScript module loader. Our application doesn't currently
  use one, and is just using plain old `<script>` tags and the global `window` scope
  instead. We'll replace this approach with the
  [SystemJS loader](https://github.com/systemjs/systemjs).

.alert.is-helpful
  :marked
    Angular 2 itself doesn't require either TypeScript or SystemJS.
    There will soon be other editions of this guide that show how to
    do the upgrade using ES5.

:marked
  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 the SystemJS and TypeScript packages to the project.
  While we're at it, let's also install the
  [Typings type definition manager](https://github.com/typings/typings).
  It will allow us to install type definitions for libraries that don't come with
  prepackaged types.

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

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

+makeJson('upgrade-phonecat/ts/typescript-conversion/package.1.json', {paths: 'scripts'}, 'package.json', {otl: /(\"tsc.*|\"typings.*)/g})


:marked
  We can now use Typings to install the type definitions for Angular 1 and the Jasmine
  unit test framework. This will add a `typings` directory to the project and install
  a number of `.d.ts` files under it. It will also create a `typings.json` file to the
  project, which contains metadata about the type definitions we've installed:

code-example(format="").
  npm run typings install jquery -- --save --global
  npm run typings install angular -- --save --global
  npm run typings install angular-route -- --save --global
  npm run typings install angular-resource -- --save --global
  npm run typings install angular-mocks -- --save --global
  npm run typings install jasmine -- --save --global

:marked
  In `index.html`, let's now enable SystemJS. Add a couple of `<script>` tags that
  load the SystemJS library and then one that loads a configuration file for
  it. Then add one more `<script>` tag that uses SystemJS to load our application.
  These will *replace* the various `<script>` tags we had earlier for loading the
  application components:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/index.html', 'scripts', 'app/index.html')

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/systemjs.config.js', ull, 'app/systemjs.config.js')

:marked
  This tells SystemJS that we have a module called `app.module` that
  resides in the `js` subdirectory (relative to the `index.html` page). We then load that
  module using `System.import`. This will load and execute the `app/app.module.js` file.

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

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

:marked
  We are telling the TypeScript compiler to turn our TypeScript files to ES5 code
  bundled into SystemJS modules. In other words, our compiler target is something
  SystemJS can load and all major browsers are able to run.

  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

:marked
  The next thing we'll do is convert our JavaScript files to TypeScript and define
  their imports and exports. Each file should now explicitly export the things
  it wants to expose, and import the things it needs from other files. This is a
  departure from the previous approach which just relied on things being available
  on the global `window` scope.

  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 define the imports and exports. We don't need to make other changes to
  our existing code. Instead we'll introduce type annotations and other new
  features gradually over time.

  Let's begin by renaming `app.module.js` to `app.module.ts`. The TypeScript
  compiler should be able to compile it successfully right away. This means we can
  move right along and go through the rest of our source files and convert them.
  We'll rename each one to a `.ts` file, and add the imports and exports it needs.

  Beginning from the checkmark filter, here are the converted contents:

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

:marked
  This file now has the filter factory function as the default export. Apart from
  the export, there's one other major change we've applied to the file, which
  is that it does *not* contain the registration of the filter into an Angular
  module. We will do that later in the `core` module's main file.

  Moving to the `Phone` factory file, it now has the factory function as the default
  export:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/core/phone.factory.ts', null, 'app/js/core/phone.factory.ts')

:marked
  The `core` module's main module file will now import both the checkmark filter
  and the Phone factory. This is where we actually register them into the Angular module.
  We then export the module itself as this file's default export:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/core/core.module.ts', null, 'app/js/core/core.module.ts')

:marked
  Notice that with this organization pattern, the files that hold the application
  components themselves - filters and factories - aren't concerned with the makeup
  of Angular modules. That's just something we previously *had* to do because there
  were no other good solutions. Now we use a separate file just for the purpose
  of forming the Angular module.

  Now switching to the phone detail module, we'll make similar changes here. In the
  controller file we export the controller function as the default export:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/phone_detail/phone_detail.controller.ts', null, 'app/js/phone_detail/phone_detail.controller.ts')

:marked
  In the main module file we import the controller and register it into the Angular
  module, which itself is then exported:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/phone_detail/phone_detail.module.ts', null, 'app/js/phone_detail/phone_detail.module.ts')

:marked
  Then we'll repeat the same steps once more for the phone list module.
  The controller file exports the controller function:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/phone_list/phone_list.controller.ts', null, 'app/js/phone_list/phone_list.controller.ts')

:marked
  And the main module file imports the controller and registers it:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/phone_list/phone_list.module.ts', null, 'app/js/phone_list/phone_list.module.ts')

:marked
  Finally, we can now pull everything together in `app.module.ts`. We'll
  import each of the three submodule files and register them as dependencies
  of the main application module:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/app.module.ts', 'pre-bootstrap', 'app/js/app.module.ts')

:marked
  Note that we don't have to repeat the submodule name strings here. Since the
  modules export themselves, we can just refer to the `name` attribute of each
  of them.

  Before this converted version of the application will run, we need to change the
  way we're bootstrapping it. It is currently bootstrapped using the `ng-app` directive
  attached to the `<html>` element of the host page. This will no longer work because
  `ng-app` is processed when the page loads, and our application code will not
  be available at that point yet. It is loaded asynchronously by SystemJS instead.

  We should switch to a JavaScript-driven bootstrap instead. As it happens, this is
  also how Angular 2 apps are bootstrapped, so the switch brings us one step closer
  to Angular as well. So, remove the `ng-app` attribute from `index.html`, and add
  this at the end of `app.module.ts`:

+makeExample('upgrade-phonecat/ts/typescript-conversion/app/js/app.module.ts', 'bootstrap', 'app/js/app.module.ts')

:marked
  We now have a fully functional version of the application, all converted
  into TypeScript code and a modern module system! If you start the project HTTP
  server with `npm start`, you should see the fully functional application in
  your browser. On the other hand, if you were to try running the *test suite*,
  things wouldn't look quite that good yet. We also have to make our tests
  support our new module organization.

:marked
  ## Preparing Tests

  Our project has both E2E Protractor tests and some Karma unit tests in it.
  Of these two, E2E tests can be dealt with much quicker: 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've modified our project quite a bit, the E2E
  test suite should keep passing just as it was before. We haven't changed
  how the app behaves from the user's point of view.

  For unit tests, on the other hand, we'll do a bit of conversion work.
  What we'll do is convert our existing unit tests to TypeScript and have them
  use `import`s to load in the code they need.

  We'll also need to tweak our Karma configuration so that it'll let SystemJS load
  the application files. For this we'll use a shim file that will tweak the way
  files get loaded:

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/karma_test_shim.js', null, 'test/karma_test_shim.js')

.alert.is-important The shim is likely to be replaced by improved tooling, but is currently needed.

:marked
  We'll then update the Karma configuration file, so that it loads SystemJS and the
  shim file. We'll also change how the app and unit tests files themselves are loaded.
  We will *watch* them so that the test suite is triggered when changes occur, but we
  won't have Karma *include* them because that is now done by SystemJS and the shim.

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/karma.conf.1.js', 'files', 'test/karma.conf.js')

:marked
  Now we have the infrastructure in place and can convert the test files themselves.
  This mainly just consists for changing the file extensions of those files, and adding
  the necessary imports to them.

  In the checkmark filter spec, we'll import the core module file, so that it is
  available when we load the corresponding Angular module:

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/unit/checkmark.filter.spec.ts', 'top', 'test/unit/checkmark.filter.spec.ts')

:marked
  We'll do the exact same thing for the phone factory spec:

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/unit/phone.factory.spec.ts', 'top', 'test/unit/phone.factory.spec.ts')

:marked
  In the phone detail controller spec, on the other hand, we should import
  the phone detail module:

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/unit/phone_detail.controller.spec.ts', 'top', 'test/unit/phone_detail.controller.spec.ts')

:marked
  Finally, the phone list controller spec should import the phone list
  module:

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/unit/phone_list.controller.spec.ts', 'top', 'test/unit/phone_list.controller.spec.ts')

:marked
  There's one more issue we have in our controller tests, which is that TypeScript
  isn't happy about compiling them at the moment. This is because we're using
  the custom Jasmine matcher `toEqualData` in both of them. Because this is something
  we define ourselves, it isn't included in the Jasmine type definitions that we
  installed using Typings.

  We can add our own little type definition file for that extension, which extends
  the `jasmine.Matchers` interface and adds our custom matcher to it. This will
  satisfy the compiler and let us use our custom matcher while retaining the nice
  type safety features of TypeScript:

+makeExample('upgrade-phonecat/ts/typescript-conversion/test/jasmine_matchers.d.ts', null, 'test/jasmine_matchers.d.ts')

:marked
  And now we have a fully functional test suite for our TypeScript-enabled
  application as well.

:marked
  ## Enjoying The Benefits of TypeScript

  Now that we have TypeScript, we can start benefiting from some of its
  other features in addition to the imports and exports that we're already using.
  There's a lot of value the language can provide in 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, default function parameters,
  and destructuring assignments.

  Another thing we can do is start adding *type safety* to our code, by
  adding type annotations. For instance, we can annotate the checkmark
  filter so that it expects booleans as arguments and returns strings.
  This makes it clearer what the filter is supposed to do, and makes it
  possible for the TypeScript compiler to notify us when we're trying to
  use it with incompatible types.

+makeExample('upgrade-phonecat/ts/classes/app/js/core/checkmark.filter.ts', null, 'app/js/core/checkmark.filter.ts', {otl: /(:\w+)/g})

.l-sub-section
  :marked
    The [Angular 1.x type definitions](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/angularjs)
    we installed with Typings are not officially maintained by the Angular team,
    but are quite comprehensive. Though we're not going to do it in this
    tutorial, 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 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 what
  ES2015/TypeScript classes really are, so that means we can just register a
  class as a controller and Angular 1 will happily use it. We also won't
  need to make any changes to our test suite as the external behavior of the
  controllers will not change.

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

+makeExample('upgrade-phonecat/ts/classes/app/js/phone_list/phone_list.controller.ts', null, 'app/js/phone_list/phone_list.controller.ts')

:marked
  What was previously done in the controller function is now done in the class
  constructor function. 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.
  We can additionally introduce a TypeScript interface that explicitly defines
  what we expect the `$routeParams` object to contain when it is
  passed to the controller. This interface is not exported and is just used internally
  inside this module:

+makeExample('upgrade-phonecat/ts/classes/app/js/phone_detail/phone_detail.controller.ts', null, 'app/js/phone_detail/phone_detail.controller.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 in the
  next section.







.l-main-section
:marked
  # PhoneCat Upgrade Tutorial

  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.
  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. Add the Angular 2 dependencies
  to `package.json` and `typings.json` as described in the [Quickstart](../quickstart.html).
  Then run:

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

:marked
  We should then load some Angular 2 dependencies into the application by adding
  some `<script>` tags to `index.html`. They should go before the `<script>` tag
  that loads `systemjs.config.js`:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/index.html', 'ng2')

:marked
  We can then load Angular 2 itself by adding its packages into the `systemjs.config.js`
  file:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/systemjs.config.js', null, 'app/systemjs.config.js')

:marked
  While we're at it, let's also make these files available to unit tests by
  updating the Karma config:

+makeExample('upgrade-phonecat/ts/ng2_initial/test/karma.conf.1.js', 'ng2', 'test/karma.conf.js')

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

  At this point we need to do add the Angular 2 type definitions
  into `app.ts`, so that the TypeScript compiler knows what we're talking about
  when we use Angular 2 APIs. Unlike with Angular 1, we don't need to install
  these type definitions with Typings because Angular 2 comes with them included.
  What we do need to do is set the TypeScript compiler's `moduleResolution` option
  to `node`, so that it knows to look for these definitions from the `angular2` NPM
  package.

+makeJson('upgrade-phonecat/ts/ng2_initial/tsconfig.1.json', null, 'tsconfig.json', {otl: /(\"moduleResolution.*)/})

:marked
  To boostrap a hybrid application, we first need to initialize an `UpgradeAdapter`,
  which [provides the glue](#upgrading-with-the-upgrade-adapter) that joins the two
  versions of the framework together. Let's import the `UpgradeAdapter` class into
  `app.module.ts`:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'adapter-import', 'app/js/app.module.ts')

:marked
  We can then make an adapter by instantiating the class:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/upgrade_adapter.ts', 'adapter-init')

:marked
  Now we can use that adapter to bootstrap our application as a hybrid.
  Instead of calling `angular.bootstrap`, we must call
  `upgradeAdapter.bootstrap`, but the function arguments remain the same:
  They are still the element that will become the root of the application,
  and the names of the root Angular 1.x modules that we want to include:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'bootstrap')

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


:marked
  ## Upgrading the Phone factory

  The first piece we'll port over to Angular 2 is the `Phone` factory, which
  resides in `app/js/core/phones.factory.ts` and makes it possible for controllers
  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 controller
  * For loading the details of a single phone into the phone detail controller.

  We can replace this implementation with an Angular 2 service class, while
  keeping our controllers in Angular 1 land. In the new version we'll just use
  the `Http` service from Angular 2 instead of ngResource.

  Before the `Http` service is available for injection, we need to register
  it into our application's dependency injector. We should import the `HTTP_PROVIDERS`
  constant in `app.module.ts`:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'http-import')

:marked
  In a regular Angular 2 application we would now pass `HTTP_PROVIDERS` into
  the application bootstrap function. But we can't do that in a hybrid
  application such as the one we're working on. That's because the `bootstrap`
  method of  `UpgradeAdapter` expects Angular 1 modules as dependencies,
  not Angular 2 providers.

  What we must do instead is register `HTTP_PROVIDERS` into the `UpgradeAdapter`
  separately. It has a method called `addProvider` for that purpose:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'add-http-providers')

:marked
  Now we're ready to upgrade the Phones factory itself. We'll put the Angular 2
  implementation in a new file called `phones.service.ts` in the core module. It will be a TypeScript
  class decorated as `@Injectable`:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/phones.service.ts', 'class', 'app/js/core/phones.service.ts')

: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/ts/ng2_initial/app/js/core/phones.service.ts', 'fullclass')

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

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/phones.service.ts', 'phone-interface', 'app/js/core/phones.service.ts')

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

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/phones.service.ts', 'full', 'app/js/core/phones.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 `Phones` service now has the same features that the original, ngResource based
  service did. You can remove the old `phones.factory.ts` file. Now we just
  need to register the new service into the application, so that our Angular 1
  controllers will be able to use it.

  `UpgradeAdapter` has a `downgradeNg2Provider` method for the purpose of making
  Angular 2 services available to Angular 1 code. The problem is that we don't have
  our `UpgradeAdapter` available in `core.module.ts` where the `Phones` service should
  be registered. We only have it in `app.module.ts`. There should only be one
  `UpgradeAdapter` in an application, so we need to find a way to share our
  instance between the two code modules.

  What we'll do is create a new module that instantiates `UpgradeAdapter`
  and exports the instance. We can then just pull it in wherever we need it,
  so that we're using the same object everywhere. Let's put this new file
  under `core`:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/upgrade_adapter.ts', 'full', 'app/js/core/upgrade_adapter.ts')

:marked
  In `app.module.ts` we should now just import this adapter instead of making a separate one:

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/app.module.ts', 'adapter-state-import')

:marked
  Also remove the line from `app.module.ts` that is instantiating `UpgradeAdapter`. It's no
  longer needed since we import the instance from elsewhere.

  We'll then do the same in `core.module.ts` as well. Then we can register the `Phones` service into it.
  While doing that, we can remove the module's dependency to `ngResource`, which
  we're no longer using.

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/core/core.module.ts', null, 'app/js/core/core.module.ts')

:marked
  Note that we actually needed to do two registrations here:

  1. Register `Phones` as an **Angular 2 provider** with the `addProvider`
     method. That's the same method that we used earlier for `HTTP_PROVIDERS`.
  2. Register an **Angular 1 factory** called `phones`, which will be a *downgraded*
     version of the `Phones` service.

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

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/phone_detail/phone_detail.controller.ts', null, 'app/js/phone_detail/phone_detail.controller.ts')

+makeExample('upgrade-phonecat/ts/ng2_initial/app/js/phone_list/phone_list.controller.ts', null, 'app/js/phone_list/phone_list.controller.ts')

:marked
  What we have here are two Angular 1 controllers using an Angular 2 service!
  The controllers 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 controllers that use it.

.alert.is-helpful
  :marked
    You could use the `toPromise` method of `Observable` to turn those Observables
    into Promises in the service to further reduce the amount of changes
    needed in controller code.

:marked
  To bring our test suite up to speed with the changes, we should update the Karma
  test shim. It'll make some of Angular 2 providers available before starting
  to load any of the spec files:

+makeExample('upgrade-phonecat/ts/ng2_initial/test/karma_test_shim.js', null, 'test/karma_test_shim.js')

.alert.is-important The shim is likely to be replaced by improved tooling, but is needed right now.

:marked
  Now, let's look at the tests for the service itself. What we used to have in
  `phones_factory_spec.js` was a fairly simple test that simply checks if
  the factory exists and is available for injection. We can now do that same
  test in Angular 2. Rename `phones.factory.spec.ts` to `phones.service.spec.ts` and
  set the contents as follows:

+makeExample('upgrade-phonecat/ts/ng2_initial/test/unit/phones.service.spec.ts', null, 'test/unit/phones.service.spec.ts')

:marked
  Here we first load the `Phones` provider and then test that an instance of
  `Phones` can in fact be injected. We also need to load `HTTP_PROVIDERS` since
  it is a dependency of `Phones`.

  For the controller tests, we can first of all at this point get rid of the
  custom `toEqualData` custom matcher. It was added because `ngResource` attaches
  attributes to the data that we don't want to compare in tests. We're no longer
  using `ngResource`, so we can simply use the built-in `toEqual` for comparisons.
  This means we can remove the `test/jasmine_matchers.d.ts` file at this point.

  Now, in the phone detail controller we have been testing that the phone details
  with the id given in the route params are fetched over HTTP and put on the
  scope. We can continue doing that, but we'll need to change the structure of the
  test a bit. Instead of using the Angular 1 mock HTTP backend, we'll just mock out
  the `get` method of the `Phones` service, which is what the controller is now
  using to load what it needs. As the mocked value, we're returning an Observable
  that will emit a single value - the mock phone data:

+makeExample('upgrade-phonecat/ts/ng2_initial/test/unit/phone_detail.controller.spec.ts', null, 'test/unit/phone_detail.controller.spec.ts')

.alert.is-important
  :marked
    We're doing a manual `Phones` instantiation because hybrid apps can't be
    bootstrapped for unit tests at the moment, which means that Angular 2
    dependencies can't be made available. This is likely to change.

:marked
  In the phone list controller we'll do something very similar: We mock out the `query`
  method of the `Phones` service, and check that the controller makes the resulting
  value available:

+makeExample('upgrade-phonecat/ts/ng2_initial/test/unit/phone_list.controller.spec.ts', null, 'test/unit/phone_list.controller.spec.ts')

:marked
  ## Upgrading Controllers to Components

  Next, let's upgrade our Angular 1 controllers 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 controller first. Right now it is a TypeScript class,
  which is paired with an HTML template by the route configuration in `app.ts`.
  We'll be turning it into an Angular 2 component.

  Rename `phone_list.controller.ts` to `phone_list.component.ts`. Then rename the controller class
  inside to just `PhoneList` and decorate it as a `@Component`:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list_without_pipes.component.ts', 'top', 'app/js/phone_list/phone_list.component.ts')

:marked
  The `selector` attribute is a CSS selector that defines where on the page the component
  should go. It will match elements by the name of `pc-phone-list`. It is a good idea
  to always use application-specific prefixes in selectors so that they never clash with
  built-in ones, and here we're using `pc-`, which is short for "PhoneCat".

  The `templateUrl` defines the location of the component template. It points to our existing
  template file

  Both of these attributes are things that were defined *externally* for the controller,
  but for the component are things that it defines *itself*. This will affect how we use
  the component in the router.

:marked
  We now also need to convert the template of this component into Angular 2 syntax.
  In the search controls we need to use Angular 2 syntax for the two `ngModel`s

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list_without_pipes.html', 'controls', 'app/js/phone_list/phone_list.html')

:marked
  In the list we need to replace the `ng-repeat` with an `*ngFor` and its
  `#var of iterable` syntax, which is [described in our
  Template Syntax guide](../guide/template-syntax.html#directives).

  For the images, we can replace `ng-src` with the standard `src`, but will use a
  property binding. Note that we're also adding a `name` CSS class for the phone name.
  This is something we'll need for our Protractor tests:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list_without_pipes.html', 'list', 'app/js/phone_list/phone_list.html')

:marked
  In the module file we're going to plug this component into our application. Instead
  of registering a controller, we register a `pcPhoneList` directive.
  The directive is a downgraded version of our component, and the `UpgradeAdapter`
  handles the bridging between the two:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list.module.ts', null, 'app/js/phone_list/phone_list.module.ts')

:marked
  The `<angular.IDirectiveFactory>` type annotation here is to let the TypeScript compiler
  know that the return value of the downgrade method call will be something that can be
  used as a directive factory.

  To complete the switch, we should change our route configuration in `app.module.ts`.
  Instead of using the controller and template, it can just instantiate our component.
  We can do that by using a simple template that uses the directive
  we just registered:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/app.module.ts', 'list-route')

:marked
  When the application runs, the Angular 1.x directive compiler will match
  the element in the template to the `pcPhoneList` directive, which is actually
  an Angular 2 component!

  The remaining issue with the phone list is the use of filters in its
  template: It is referring to the `filter` filter and the `orderBy` filter,
  and relying on them to filter and sort the phone list, respectively.
  These pipes do not exist in Angular 2, so we're going to need to do
  the filtering and sorting ourselves. Let's define a couple of pipes that
  get the job done.

.alert.is-helpful
  :marked
    If you want to learn more about how pipes in Angular 2
    work, we have [a whole guide on the subject](../guide/pipes.html)
    available!

:marked
  For filtering, we'll have a pipe called `PhoneFilterPipe`. It works like
  the `filter` filter in Angular 1 in that it filters a collection of objects,
  matching properties within the objects. But, as opposed to `filter`,
  this pipe is specialized to filter `Phone` objects and we can use
  type annotations to make this explicit:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_filter.pipe.ts', null, 'app/js/phone_list/phone_filter.pipe.ts')

:marked
  Since we're adding new code, it's a good idea to add some unit tests for
  it too. Here are a few tests for `PhoneFilterPipe`:

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/phone_filter.pipe.spec.ts', null, 'test/unit/phone_filter.pipe.spec.ts')

:marked
  For sorting, we'll use a more generic pipe, just called `OrderBy`. It
  takes an array of objects, and a property to order the array by. It returns
  an array of the same type of thing it was given. In the implementation we
  copy the input array, sort the copy, and return it.

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/order_by.pipe.ts', null, 'app/js/phone_list/order_by.pipe.ts')

:marked
  Here's a unit test for `OrderByPipe` as well:

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/order_by.pipe.spec.ts', null, 'test/unit/order_by.pipe.spec.ts')

:marked
  We can now integrate these new pipes with our component. Before the pipes
  are available there, we need to declare them in the `@Component` decorator.

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list.component.ts', 'top', 'app/js/phone_list/phone_list.component.ts')

:marked
  In the template we need to use the `phoneFilter` pipe instead of `filter`.
  No changes are needed for the `orderBy`

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list_without_async.html', 'list', 'app/js/phone_list/phone_list.html')

:marked
  Now that the phone list is an Angular 2 component, there's one more neat trick
  we can apply to make its code a little bit simpler. Earlier, as we upgraded
  the `Phones` service, we needed to add a `subscribe` callback to the list
  response, which populated the `phones` array on the component.
  With Angular 2, we can instead just put the Observable itself on the
  component, and can skip the subscription callback:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list.component.ts', 'full', 'app/js/phone_list/phone_list.component.ts')

:marked
  This is made possible by the `async` pipe, which we can apply in the template.
  It knows how to turn an Observable to the (latest) value it has emitted:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_list/phone_list.html', 'list', 'app/js/phone_list/phone_list.html')

:marked
  That takes care of the phone list. Here's the updated unit test file for
  that component to complete the migration:

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/phone_list.component.spec.ts', null, 'test/unit/phone_list.component.spec.ts')

:marked
  Before this test will run, we'll need to augment our Karma configuration
  so that component HTML templates are loaded properly. We didn't need them
  before when we were testing the controller in isolation, but our new test
  exercises the component as a whole, which includes the template.

+makeExample('upgrade-phonecat/ts/ng2_components/test/karma.conf.1.js', 'html', 'test/karma.conf.js')

:marked
  Now we can start looking at our other controller, which is the one for
  the phone details. Rename `phone_detail.controller.ts` to `phone_detail.component.ts`,
  and set the contents as follows:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_detail/phone_detail_without_pipes.component.ts', null, 'app/js/phone_detail/phone_detail.component.ts')

:marked
  This is pretty similar to what we did with the phone list. The one new change
  here is the use of `@Inject` for the `$routeParams` dependency. It tells the
  Angular 2 injector what this dependency should map to. We have a dependency called
  `$routeParams` in the Angular 1 injector, where it is provided by the Angular 1 router.
  That is what we were already using when `PhoneDetails` was still an Angular 1 controller.
  The things is though, Angular 1 dependencies are not made automatically available to
  Angular 2 components, so if we were to run this now, it would not work.

  We explicitly need to tell the `UpgradeAdapter` to upgrade `$routeParams` so that
  it is available for injection in Angular 2. We can do it in `app.module.ts`:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/app.module.ts', 'upgrade-route-params', 'app/js/app.module.ts')



:marked
  We now also need to convert the template of this component into Angular 2 syntax.
  Here is the new template in its entirety:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_detail/phone_detail.html', null, 'app/js/phone_detail/phone_detail.html')

:marked
  There are several notable changes here:

  * We've removed the `vm.` prefix from all expressions.
  * Just like we did in the phone list, we've replaced `ng-src` with property
    bindings for the standard `src`.
  * 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`.
  * In all references to `phone`, we're using the safe navigation operator `?.` for
    safe property navigation. We need it 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.

:marked
  In the module file we'll now register a `pcPhoneDetail` directive instead of a
  controller. The directive is a downgraded version of the `PhoneDetail` component.

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_detail/phone_detail.module.ts', null, 'app/js/phone_detail/phone_detail.module.ts')

:marked
  In the router configuration in `app.module.ts`, we'll switch the details route to
  instantiate a component as well:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/app.module.ts', 'detail-route')

:marked
  There's one additional step we need to take, which is to upgrade the
  `checkmark` filter that the template is using. We need an Angular 2
  pipe instead of an Angular 1 filter.

  While there is no upgrade method in the upgrade adapter for filters, we
  can just turn the filter function into a class that fulfills
  the contract for Angular 2 Pipes. The implementation is the same as before.
  It just comes in a different kind of package. While changing it, also
  rename the file to `checkmark.pipe.ts`:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/core/checkmark.pipe.ts', null, 'app/js/core/checkmark.pipe.ts')

:marked
  As we apply this change, we should also remove the registration of the filter
  from the core module file. The module's content becomes:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/core/core.module.ts', null, 'app/js/core/core.module.ts')

:marked
  The unit test file for the filter also now becomes the unit test filter
  for the pipe. While we're still testing the same thing, we need to change
  how we set things up:

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/checkmark.pipe.spec.ts', null, 'test/unit/checkmark.pipe.spec.ts')

:marked
  In the component we should now import and declare our newly created pipe:

+makeExample('upgrade-phonecat/ts/ng2_components/app/js/phone_detail/phone_detail.component.ts', 'top', 'app/js/phone_detail/phone_detail.component.ts')

:marked
  With the phone detail component now migrated as well, we can go and migrate
  its unit tests too.

+makeExample('upgrade-phonecat/ts/ng2_components/test/unit/phone_detail.component.spec.ts', null, 'test/unit/phone_detail.component.spec.ts')

:marked
  As we discussed earlier, Protractor tests should largely remain functional
  as we are making changes, since we're not really changing the user-visible
  behavior of the application. Now that we've migrated some components and
  their templates, however, there are a few changes we need to make. Apply
  the following replacements to `scenarios.js`:

table
  tr
    th Previous code
    th New code
    th Notes
  tr
    td
      :marked
        `by.repeater('phone in vm.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 vm.phones')`
    td
      :marked
        `by.css('.phones li')`
    td
      :marked
        The repeater matcher relies on Angular 1 `ng-repeat`
  tr
    td
      :marked
        `by.model('vm.query')`
    td
      :marked
        `by.css('input')`
    td
      :marked
        The model matcher relies on Angular 1 `ng-model`
  tr
    td
      :marked
        `by.model('vm.orderProp')`
    td
      :marked
        `by.css('select')`
    td
      :marked
        The model matcher relies on Angular 1 `ng-model`
  tr
    td
      :marked
        `by.binding('vm.phone.name')`
    td
      :marked
        `by.css('h1')`
    td
      :marked
        The binding matcher relies on Angular 1 data binding
  tr
    td
      :marked
        `li:nth-child(1)` and `li:nth-child(3)`
    td
      :marked
        `li:nth-of-type(1)` and `li:nth-of-type(3)`
    td
      :marked
        Angular 2 may inject empty `<script>` tags to the page for its internal purposes so we should not rely on the number of siblings being predictable.

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

  At this point we've replaced all our Angular 1 application components with
  their Angular 2 counterparts. The application is still bootstrapped as a hybrid,
  but there isn't really any need for that anymore, and we can begin to
  pull out the last remnants of Angular 1.

  There are just two more things to do: We need to switch the router to
  the Angular 2 one, and then bootstrap the app as a pure Angular 2 app.

  Let's do the routing part first. Angular 2 comes with a [shiny new router](router.html)
  that we can use for this.

  Angular 2 applications all have a *root component*, which, among other
  things, is where we should plug in the router. We don't yet have such a root
  component, because our app is still managed as an Angular 1 app.
  Let's change this now and add an `AppComponent` class into a new file
  `app.component.ts`:

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/app.component.ts', null, 'app/js/app.component.ts')

:marked
  This is a component that plugs in to an `<pc-app>` element on the page,
  and has a simple template that only includes the router outlet component
  of the Angular router. This means that the component just renders the contents
  of the current route and nothing else. The `@RouteConfig` decorator defines
  the Angular 2 counterparts of our two routes. They refer directly to the
  two components.

  We should put this `<pc-app>` element in the HTML so that the root component
  has something to attach to. It replaces the old Angular 1 `ng-view` directive:

+makeExample('upgrade-phonecat/ts/ng2_final/app/index.html', 'body', 'app/index.html')

:marked
  In the `PhoneDetail` component we now need to change how the phone id parameter
  is received. There will be no more `$routeParams` injection available, because
  that comes from the Angular 1 router. Instead, what we have is a `RouteParams`
  object provided by the Angular 2 router. We use it to obtain the `phoneId` from
  the params:

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/phone_detail/phone_detail.component.ts', null, 'app/js/phone_detail/phone_detail.component.ts')

:marked
  We should also make the corresponding change in the unit test. We provide
  an instance of the `RouteParams` class instead of the `$routeParams` object:

+makeExample('upgrade-phonecat/ts/ng2_final/test/unit/phone_detail.component.spec.ts', 'routeparams', 'test/unit/phone_detail.component.spec.ts')

:marked
  With that, we're ready to switch the bootstrap method of the application from that
  of the `UpgradeAdapter` to the main Angular 2 `bootstrap`. Let's import it together
  with the router and the new app component in `app.module.ts`

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/main.ts', 'importbootstrap')

:marked
  We'll now use the regular Angular 2 `bootstrap` function to bootstrap the app
  instead of using `UpgradeAdapter`. The first argument to `bootstrap` is the
  application's root component `AppComponent`, and the second
  is an array of the Angular 2 providers that we want to make available for
  injection. In that array we include all the things we have been registering
  with  `upgradeAdapter.addProvider` until now, as well as the providers and
  directives of the router:

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/main.ts', 'bootstrap')

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

  But there's actually one more cool thing we can do with the new router.
  We no longer have to hardcode the links to phone details from the phone
  list, because the Angular 2 router is able to generate them for us with
  its `routerLink` directive. We just need to refer to the route names we
  used in the `@RouteConfig`:

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/phone_list/phone_list.html', 'list', 'app/js/phone_list/phone_list.html')

:marked
  For this to work the directive just needs to be declared in the component:

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/phone_list/phone_list.component.ts', 'top')

:marked
  Also, the unit tests for `PhoneList` now need to set up some router providers
  so that the `RouterLink` directive can be injected in the tests:

+makeExample('upgrade-phonecat/ts/ng2_final/test/unit/phone_list.component.spec.ts', null)

:marked
  To bring our Protractor test suite up to speed with the latest changes,
  there are a few remaining things we need to do. Firstly, now that we're
  no longer running Angular 1 at all, we should let Protractor know it
  should not be looking for one but instead find *Angular 2 apps* from
  the page. Add the following configuration option to `protractor-conf.js`:

+makeExample('upgrade-phonecat/ts/ng2_final/test/protractor-conf.js', 'ng2')

:marked
  Also, there are a couple of Protractor API calls in our test code that
  are using the Angular 1 `$location` service under the hood. As that
  service is no longer there, 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/ts/ng2_final/test/e2e/scenarios.js', 'redirect')

:marked
  And the second is the phone links spec:

+makeExample('upgrade-phonecat/ts/ng2_final/test/e2e/scenarios.js', 'links')

:marked
  Now our E2E test suite is passing too, and we're ready to remove
  Angular 1 from the project!

:marked
  ## Saying 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!

  First, rename `app.module.ts` to `main.ts`. It will no longer be setting up
  an Angular 1 module, so it doesn't really make sense to call it a module.
  Then remove all references to the `UpgradeAdapter` from `main.ts`. Also remove
  the Angular 1 bootstrap code and the imports of the `core`, `phoneList`, and
  `phoneDetail` modules. Instead import the `PhoneList` and `PhoneDetail`
  components directly - they are needed in the route configuration.

  When you're done, this is what `main.ts` should look like:

+makeExample('upgrade-phonecat/ts/ng2_final/app/js/main.ts', null, 'app/js/main.ts')

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

  * `app/js/core/core.module.ts`
  * `app/js/core/upgrade_adapter.ts`
  * `app/js/phone_detail/phone_detail.module.ts`
  * `app/js/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.

code-example(format="").
  npm run typings uninstall jquery -- --save --global
  npm run typings uninstall angular -- --save --global
  npm run typings uninstall angular-route -- --save --global
  npm run typings uninstall angular-resource -- --save --global
  npm run typings uninstall angular-mocks -- --save --global

:marked
  Finally, from `index.html` and `karma.conf.js`, remove all references to
  Angular 1 scripts as well as jQuery. Instead of importing `js/app.module`
  with SystemJS, import `js/main`. When you're done, this is what `index.html`
  should look like:

+makeExample('upgrade-phonecat/ts/ng2_final/app/index.html', null, 'app/index.html')

:marked
  And this is what `karma.conf.js` should look like:

+makeExample('upgrade-phonecat/ts/ng2_final/test/karma.conf.1.js', null, 'test/karma.conf.js')

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