Angular

What it does

Part of the upgrade/static library for hybrid upgrade apps that support AoT compilation

Allows an Angular 1 component to be used from Angular 2+.

How to use

Let's assume that you have an Angular 1 component called ng1Hero that needs to be made available in Angular 2+ templates.

// This Angular 1 component will be "upgraded" to be used in Angular 2+
ng1AppModule.component('ng1Hero', {
  bindings: {hero: '<', onRemove: '&'},
  transclude: true,
  template: `<div class="title" ng-transclude></div>
             <h2>{{ $ctrl.hero.name }}</h2>
             <p>{{ $ctrl.hero.description }}</p>
             <button ng-click="$ctrl.onRemove()">Remove</button>`
});

We must create a Directive that will make this Angular 1 component available inside Angular 2+ templates.

// This Angular 2 directive will act as an interface to the "upgraded" Angular 1 component
@Directive({selector: 'ng1-hero'})
class Ng1HeroComponentWrapper extends UpgradeComponent implements OnInit, OnChanges, DoCheck,
    OnDestroy {
  // The names of the input and output properties here must match the names of the
  // `<` and `&` bindings in the Angular 1 component that is being wrapped
  @Input() hero: Hero;
  @Output() onRemove: EventEmitter<void>;
  constructor(@Inject(ElementRef) elementRef: ElementRef, @Inject(Injector) injector: Injector) {
    // We must pass the name of the directive as used by Angular 1 to the super
    super('ng1Hero', elementRef, injector);
  }

  // For this class to work when compiled with AoT, we must implement these lifecycle hooks
  // because the AoT compiler will not realise that the super class implements them
  ngOnInit() { super.ngOnInit(); }

  ngOnChanges(changes: SimpleChanges) { super.ngOnChanges(changes); }

  ngDoCheck() { super.ngDoCheck(); }

  ngOnDestroy() { super.ngOnDestroy(); }
}

In this example you can see that we must derive from the UpgradeComponent base class but also provide an @Directive decorator. This is because the AoT compiler requires that this information is statically available at compile time.

Note that we must do the following:

specify the directive's selector (ng1-hero)
specify all inputs and outputs that the Angular 1 component expects
derive from UpgradeComponent
call the base class from the constructor, passing
- the Angular 1 name of the component (ng1Hero)
- the ElementRef and Injector for the component wrapper

Class Overview

class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy {

constructor(name: string, elementRef: ElementRef, injector: Injector)

ngOnInit()

ngOnChanges(changes: SimpleChanges)

ngDoCheck()

ngOnDestroy()

}

Class Description

A helper class that should be used as a base class for creating Angular directives that wrap Angular 1 components that need to be "upgraded".

Constructor

constructor(name: string, elementRef: ElementRef, injector: Injector)

Create a new UpgradeComponent instance. You should not normally need to do this. Instead you should derive a new class from this one and call the super constructor from the base class.

// This Angular 2 directive will act as an interface to the "upgraded" Angular 1 component
@Directive({selector: 'ng1-hero'})
class Ng1HeroComponentWrapper extends UpgradeComponent implements OnInit, OnChanges, DoCheck,
    OnDestroy {
  // The names of the input and output properties here must match the names of the
  // `<` and `&` bindings in the Angular 1 component that is being wrapped
  @Input() hero: Hero;
  @Output() onRemove: EventEmitter<void>;
  constructor(@Inject(ElementRef) elementRef: ElementRef, @Inject(Injector) injector: Injector) {
    // We must pass the name of the directive as used by Angular 1 to the super
    super('ng1Hero', elementRef, injector);
  }

  // For this class to work when compiled with AoT, we must implement these lifecycle hooks
  // because the AoT compiler will not realise that the super class implements them
  ngOnInit() { super.ngOnInit(); }

  ngOnChanges(changes: SimpleChanges) { super.ngOnChanges(changes); }

  ngDoCheck() { super.ngDoCheck(); }

  ngOnDestroy() { super.ngOnDestroy(); }
}

The name parameter should be the name of the Angular 1 directive.
The elementRef and injector parameters should be acquired from Angular by dependency injection into the base class constructor.

Note that we must manually implement lifecycle hooks that call through to the super class. This is because, at the moment, the AoT compiler is not able to tell that the UpgradeComponent already implements them and so does not wire up calls to them at runtime.

Class Details

ngOnInit()

ngOnChanges(changes: SimpleChanges)

ngDoCheck()

ngOnDestroy()

exported from @angular/upgrade/static, defined in @angular/upgrade/src/aot/upgrade_component.ts