{ "id": "api/upgrade/static/UpgradeModule", "title": "UpgradeModule", "contents": "\n\n
\n
\n
\n \n API > @angular/upgrade > @angular/upgrade/static\n
\n
\n mode_edit\n code\n
\n
\n \n
\n

UpgradeModulelink

\n \n \n \n \n \n
\n \n \n\n
\n \n
\n

An NgModule, which you import to provide AngularJS core services,\nand has an instance method used to bootstrap the hybrid upgrade application.

\n\n

See more...

\n
\n \n \n \n
\n\nclass UpgradeModule {\n $injector: any\n injector: Injector\n ngZone: NgZone\n bootstrap(element: Element, modules: string[] = [], config?: any)\n}\n\n\n \n \n\n
\n\n\n \n\n \n \n \n
\n

Descriptionlink

\n

Part of the upgrade/static\nlibrary for hybrid upgrade apps that support AOT compilation

\n

The upgrade/static package contains helpers that allow AngularJS and Angular components\nto be used together inside a hybrid upgrade application, which supports AOT compilation.

\n

Specifically, the classes and functions in the upgrade/static module allow the following:

\n
    \n
  1. Creation of an Angular directive that wraps and exposes an AngularJS component so\nthat it can be used in an Angular template. See UpgradeComponent.
    2. \n
  2. Creation of an AngularJS directive that wraps and exposes an Angular component so\nthat it can be used in an AngularJS template. See downgradeComponent.
    3. \n
  3. Creation of an Angular root injector provider that wraps and exposes an AngularJS\nservice so that it can be injected into an Angular context. See\nUpgrading an AngularJS service below.
    4. \n
  4. Creation of an AngularJS service that wraps and exposes an Angular injectable\nso that it can be injected into an AngularJS context. See downgradeInjectable.
    5. \n
  5. Bootstrapping of a hybrid Angular application which contains both of the frameworks\ncoexisting in a single application.
    6. \n
\n\n

Further information available in the Usage Notes...

\n
\n\n \n\n \n\n \n\n \n
\n

Propertieslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDescription
\n \n $injector: any\n \n \n

The AngularJS $injector for the upgrade application.

\n\n \n
\n \n injector: Injector\n \n \n

The Angular Injector *

\n\n \n
\n \n ngZone: NgZone\n \n \n

The bootstrap zone for the upgrade application

\n\n \n
\n
\n\n \n\n
\n

Methodslink

\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n bootstrap()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Bootstrap an AngularJS application from this NgModule

\n\n
\n
\n \n\n bootstrap(element: Element, modules: string[] = [], config?: any)\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n element\n Element\n

the element on which to bootstrap the AngularJS application

\n\n
\n \n modules\n string[]\n

the AngularJS modules to bootstrap for this application

\n

Optional. Default is [].

\n\n
\n \n config\n any\n

optional extra AngularJS bootstrap configuration

\n

Optional. Default is undefined.

\n\n
\n\n \n\n\n \n\n \n
\n
\n\n \n
\n\n\n \n \n
\n

Providerslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n
Provider
\n \n angular1Providers\n \n
\n
\n\n \n\n \n \n\n\n \n
\n

Usage noteslink

\n \nimport {UpgradeModule} from '@angular/upgrade/static';\n\n

See also the examples below.

\n

Mental Modellink

\n

When reasoning about how a hybrid application works it is useful to have a mental model which\ndescribes what is happening and explains what is happening at the lowest level.

\n
    \n
  1. There are two independent frameworks running in a single application, each framework treats\nthe other as a black box.
    2. \n
  2. Each DOM element on the page is owned exactly by one framework. Whichever framework\ninstantiated the element is the owner. Each framework only updates/interacts with its own\nDOM elements and ignores others.
    3. \n
  3. AngularJS directives always execute inside the AngularJS framework codebase regardless of\nwhere they are instantiated.
    4. \n
  4. Angular components always execute inside the Angular framework codebase regardless of\nwhere they are instantiated.
    5. \n
  5. An AngularJS component can be \"upgraded\"\" to an Angular component. This is achieved by\ndefining an Angular directive, which bootstraps the AngularJS component at its location\nin the DOM. See UpgradeComponent.
    6. \n
  6. An Angular component can be \"downgraded\" to an AngularJS component. This is achieved by\ndefining an AngularJS directive, which bootstraps the Angular component at its location\nin the DOM. See downgradeComponent.
    7. \n
  7. \n

    Whenever an \"upgraded\"/\"downgraded\" component is instantiated the host element is owned by\nthe framework doing the instantiation. The other framework then instantiates and owns the\nview for that component.

    \n
      \n
    1. This implies that the component bindings will always follow the semantics of the\ninstantiation framework.
      2. \n
    2. The DOM attributes are parsed by the framework that owns the current template. So\nattributes in AngularJS templates must use kebab-case, while AngularJS templates must use\ncamelCase.
      3. \n
    3. However the template binding syntax will always use the Angular style, e.g. square\nbrackets ([...]) for property binding.
      4. \n
    \n
    8. \n
  8. Angular is bootstrapped first; AngularJS is bootstrapped second. AngularJS always owns the\nroot component of the application.
    9. \n
  9. The new application is running in an Angular zone, and therefore it no longer needs calls to\n$apply().
    10. \n
\n

The UpgradeModule classlink

\n

This class is an NgModule, which you import to provide AngularJS core services,\nand has an instance method used to bootstrap the hybrid upgrade application.

\n
    \n
  • \n

    Core AngularJS services\nImporting this NgModule will add providers for the core\nAngularJS services to the root injector.

    \n
    • \n
  • \n

    Bootstrap\nThe runtime instance of this class contains a `bootstrap()`\nmethod, which you use to bootstrap the top level AngularJS module onto an element in the\nDOM for the hybrid upgrade app.

    \n

    It also contains properties to access the root injector, the\nbootstrap NgZone and the\nAngularJS $injector.

    \n
    • \n
\n

Exampleslink

\n

Import the UpgradeModule into your top level Angular `NgModule`.

\n\n// This NgModule represents the Angular pieces of the application\n@NgModule({\n declarations: [Ng2HeroesComponent, Ng1HeroComponentWrapper],\n providers: [\n HeroesService,\n // Register an Angular provider whose value is the \"upgraded\" AngularJS service\n {provide: TextFormatter, useFactory: (i: any) => i.get('textFormatter'), deps: ['$injector']}\n ],\n // All components that are to be \"downgraded\" must be declared as `entryComponents`\n entryComponents: [Ng2HeroesComponent],\n // We must import `UpgradeModule` to get access to the AngularJS core services\n imports: [BrowserModule, UpgradeModule]\n})\nexport class Ng2AppModule {\n}\n\n\n

Then inject UpgradeModule into your Angular NgModule and use it to bootstrap the top level\nAngularJS module in the\nngDoBootstrap() method.

\n\nexport class Ng2AppModule {\n constructor(private upgrade: UpgradeModule) {}\n\n ngDoBootstrap() {\n // We bootstrap the AngularJS app.\n this.upgrade.bootstrap(document.body, [ng1AppModule.name]);\n }\n}\n\n\n

Finally, kick off the whole process, by bootstraping your top level Angular NgModule.

\n\n// We bootstrap the Angular module as we would do in a normal Angular app.\n// (We are using the dynamic browser platform as this example has not been compiled AOT.)\nplatformBrowserDynamic().bootstrapModule(Ng2AppModule);\n\n\n\n

Upgrading an AngularJS servicelink

\n

There is no specific API for upgrading an AngularJS service. Instead you should just follow the\nfollowing recipe:

\n

Let's say you have an AngularJS service:

\n\nexport class TextFormatter {\n titleCase(value: string) {\n return value.replace(/((^|\\s)[a-z])/g, (_, c) => c.toUpperCase());\n }\n}\n\n// This AngularJS service will be \"upgraded\" to be used in Angular\nng1AppModule.service('textFormatter', [TextFormatter]);\n\n\n

Then you should define an Angular provider to be included in your NgModule providers\nproperty.

\n\n// Register an Angular provider whose value is the \"upgraded\" AngularJS service\n{provide: TextFormatter, useFactory: (i: any) => i.get('textFormatter'), deps: ['$injector']}\n\n\n

Then you can use the \"upgraded\" AngularJS service by injecting it into an Angular component\nor service.

\n\nconstructor(textFormatter: TextFormatter) {\n // Change all the hero names to title case, using the \"upgraded\" AngularJS service\n this.heroes.forEach((hero: Hero) => hero.name = textFormatter.titleCase(hero.name));\n}\n\n\n\n
\n\n\n\n
\n
\n\n\n" }