UI-Router angular-hybrid

UI-Router support for Hybrid Angular/AngularJS apps

This module provides ngUpgrade integration with UI-Router. It enables UI-Router to route to both AngularJS components (and/or templates) and Angular components.

Your app will be hosted by AngularJS while you incrementally upgrade it to Angular. With @uirouter/angular-hybrid you can use either an Angular component or an AngularJS component/template as the view in a state definition.

1import { Ng2AboutComponentClass } from "./about.ng2.component";
2
3/// ...
4
5$stateProvider.state({
6  name: 'home',
7  url: '/home',
8  component: 'ng1HomeComponent' // AngularJS component or directive name
9})
10
11.state({
12  name: 'about',
13  url: '/about',
14  component: Ng2AboutComponentClass // Angular component class reference
15});
16
17.state({
18  name: 'other',
19  url: '/other',
20  template: '<h1>Other</h1>', // AngularJS template/controller
21  controller: function($scope) { /* do stuff */ }
22})

When routing to an Angular component, that component uses the standard Angular directives (ui-view and uiSref) from @uirouter/angular.

When routing to an AngularJS component or template, that component uses the standard AngularJS directives (ui-view and ui-sref) from @uirouter/angularjs.

See the hybrid sample app for a full example.

Getting started

Remove angular-ui-router (or @uirouter/angularjs) from your AngularJS app's package.json and replace it with @uirouter/angular-hybrid. Add the @angular/* dependencies.

dependencies: {
  ...
  "@angular/common": "^6.0.0",
  "@angular/compiler": "^6.0.0",
  "@angular/core": "^6.0.0",
  "@angular/platform-browser": "^6.0.0",
  "@angular/platform-browser-dynamic": "^6.0.0",
  "@angular/upgrade": "^6.0.0",
   ...
  "@uirouter/angular-hybrid": "^6.0.0",
  ...
}

Remove any ng-app attributes from your main HTML file. We need to use manual AngularJS bootstrapping mode.

Add AngularJS module ui.router.upgrade

• Add 'ui.router.upgrade' to your AngularJS app module's depedencies

1let ng1module = angular.module('myApp', ['ui.router', 'ui.router.upgrade']);

example

Create a root Angular NgModule

• Import the BrowserModule, UpgradeModule, and a UIRouterUpgradeModule.forRoot() module.
• Add providers entry for any AngularJS services you want to expose to Angular.
• The module should have a ngDoBootstrap method which calls the UpgradeModule's bootstrap method.

1export function getDialogService($injector) {
2  return $injector.get('DialogService');
3}
4
5@NgModule({
6  imports: [
7    BrowserModule,
8    // Provide angular upgrade capabilities
9    UpgradeModule,
10    // Provides the @uirouter/angular directives and registers
11    // the future state for the lazy loaded contacts module
12    UIRouterUpgradeModule.forRoot({ states: [contactsFutureState] }),
13  ],
14  providers: [
15    // Provide the SystemJsNgModuleLoader when using Angular lazy loading
16    { provide: NgModuleFactoryLoader, useClass: SystemJsNgModuleLoader },
17
18    // Register some AngularJS services as Angular providers
19    { provide: 'DialogService', deps: ['$injector'], useFactory: getDialogService },
20    { provide: 'Contacts', deps: ['$injector'], useFactory: getContactsService },
21  ]
22})
23export class SampleAppModuleAngular {
24  constructor(private upgrade: UpgradeModule) { }
25
26  ngDoBootstrap() {
27    this.upgrade.bootstrap(document.body, [sampleAppModuleAngularJS.name], { strictDi: true });
28  }
29}

example

Defer intercept

Tell UI-Router that it should wait until all bootstrapping is complete before doing the initial URL synchronization.

1ngmodule.config(['$urlServiceProvider', ($urlService: UrlService) => $urlService.deferIntercept()]);

example

Bootstrap the app

• Bootstrap Angular
• Angular runs ngDoBootstrap() which bootstraps AngularJS
• Chain off bootstrapModule() and tell UIRouter to synchronize the URL and listen for further URL changes
  • Do this in the Angular Zone to avoid "digest already in progress" errors.

1platformBrowserDynamic()
2  .bootstrapModule(SampleAppModuleAngular)
3  .then((platformRef) => {
4    // Intialize the Angular Module
5    // get() the UIRouter instance from DI to initialize the router
6    const urlService: UrlService = platformRef.injector.get(UIRouter).urlService;
7
8    // Instruct UIRouter to listen to URL changes
9    function startUIRouter() {
10      urlService.listen();
11      urlService.sync();
12    }
13
14    platformRef.injector.get < NgZone > NgZone.run(startUIRouter);
15  });

example

Route to AngularJS components/templates

Your existing AngularJS routes work the same as before.

var foo = {
  name: 'foo',
  url: '/foo',
  component: 'fooComponent'
};
$stateProvider.state(foo);

var bar = {
  name: 'foo.bar',
  url: '/bar',
  templateUrl: '/bar.html',
  controller: 'BarController'
};
$stateProvider.state(bar);

Route to Angular components

Register states using either Angular or AngularJS code. Use component: in your state declaration.

var leaf = {
  name: 'foo.bar.leaf',
  url: '/leaf',
  component: MyNg2CommponentClass
};
$stateProvider.state(leaf);

Create Angular Feature Modules (optional)

1@NgModule({
2  imports: [
3    UIRouterUpgradeModule.forChild({
4      states: [featureState1, featureState2],
5    }),
6  ],
7  declarations: [FeatureComponent1, FeatureComponent2],
8})
9export class MyFeatureModule {}

example

Add the feature module to the root NgModule imports

1@NgModule({
2  imports: [BrowserModule, UIRouterUpgradeModule.forChild({ states }), MyFeatureModule],
3})
4class SampleAppModule {}

example

Limitations:

Nested Routing

We currently support routing either Angular (2+) or AngularJS (1.x) components into an AngularJS (1.x) ui-view. However, we do not support routing AngularJS (1.x) components into an Angular (2+) ui-view.

If you create an Angular (2+) ui-view, then any nested ui-view must also be Angular (2+).

Because of this, apps should be migrated starting from leaf states/views and work up towards the root state/view.

Resolve

Resolve blocks on state definitions are always injected using AngularJS style string injection tokens.

• UI-Router for AngularJS injects objects using string tokens, such as '$transition$', '$state', or 'currentUser'.

1resolve: {
2  roles: ($authService, currentUser) => $authService.fetchRoles(currentUser);
3}

• UI-Router for Angular uses the Transition.injector() API. The resolve function receives the Transition object as the first argument.

1  // In Angular, the first argument to a resolve is always the Transition object
2  // The resolver (usually) must be exported
3  export const rolesResolver = (transition) => {
4    const authService = transition.injector().get(AuthService);
5    const currentUser = transition.injector().get('currentUser');
6    return authService.fetchRoles(currentUser);
7  }
8
9  ...
10
11  resolve: {
12    roles: rolesResolver
13  }

In UI-Router for Angular/AngularJS hybrid mode, all resolves are injected using AngularJS style. If you need to inject Angular services by class, or need to use some other token-based injection such as an InjectionToken, access them by injecting the $transition$ object using string-based injection. Then, use the Transition.injector() API to access your services and values.

1import { AuthService, UserToken } from './auth.service';
2
3// Notice that the `Transition` object is first injected
4// into the resolver using the '$transition$' string token
5export const rolesResolver = function ($transition$) {
6  // Get the AuthService using a class token
7  const authService: AuthService = transition.injector().get(AuthService);
8
9  // Get the user object using an InjectionToken
10  const user = transition.injector().get(UserToken);
11
12  return authService.fetchRoles(user).then((resp) => resp.roles);
13};
14
15export const NG2_STATE = {
16  name: 'ng2state',
17  url: '/ng2state',
18  component: Ng2Component,
19  resolve: {
20    roles: rolesResolver,
21  },
22};

onEnter/Exit/Retain

When a state has an onEnter, onExit, or onRetain, they are always injected (AngularJS style), even if the state uses Angular 2+ components or is added to an UIRouterUpgradeModule NgModule.

1export function ng2StateOnEnter(transition: Transition, svc: MyService) {
2  console.log(transition.to().name + svc.getThing());
3}
4ng2StateOnEnter.$inject = [Transition, 'MyService'];
5export const NG2_STATE = {
6  name: 'ng2state',
7  url: '/ng2state',
8  onEnter: ng2StateOnEnter,
9};

Examples

The minimal example of @uirouter/angular-hybrid can be found here: https://github.com/ui-router/angular-hybrid/tree/master/example

A minimal example can also be found on stackblitz: https://stackblitz.com/edit/ui-router-angular-hybrid

A large sample application example with lazy loaded modules can be found here: https://github.com/ui-router/sample-app-angular-hybrid

The same sample application can be live-edited using Angular CLI and StackBlitz here: https://stackblitz.com/github/ui-router/sample-app-angular-hybrid/tree/angular-cli

UpgradeAdapter vs UpgradeModule

Version 2.0.0 of @uirouter/angular-hybrid only supports UpgradeAdapter, which works fine but is no longer in development. Version 3.0.0+ of @uirouter/angular-hybrid only supports UpgradeModule from @angular/upgrade/static, which is what the Angular team actively supports for hybrid mode. Because we dropped support for UpgradeAdapter, current users of @uirouter/angular-hybrid 2.x will have to switch to UpgradeModule when upgrading to 3.x.