From f5127f601da52d71481b37534080c21ef50075dd Mon Sep 17 00:00:00 2001 From: Brandon Roberts Date: Tue, 7 May 2019 15:31:20 -0500 Subject: [PATCH] docs: add section to upgrade guide on using the unified location service (#30331) The LocationUpgradeModule provides a unified way of handling URL updates across AngularJS and Angular. PR Close #30331 --- aio/content/guide/upgrade.md | 47 ++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/aio/content/guide/upgrade.md b/aio/content/guide/upgrade.md index e3493a3fe2..1de9a0d605 100644 --- a/aio/content/guide/upgrade.md +++ b/aio/content/guide/upgrade.md @@ -838,6 +838,53 @@ After this, the service is injectable anywhere in AngularJS code: +## Using the Unified Angular Location Service + +AngularJS and Angular both have separate routers for configuration, handling navigation, encoding and decoding URLs, redirects, and interacting with browser APIs. When migrating from AngularJS to Angular, you have the option of running both routers to handle navigating in different parts of your application. As your migrating from AngularJS, you want to take advantage of new APIs, and move as much of this functionality to Angular. + +To aid in your migration from AngularJS to Angular, a unified location service is provided to shift the routing responsibility previously handled by the `$location` provider in AngularJS to Angular. + +To use the `LocationUpgradeModule`, import the symbol from `@angular/common/upgrade` and add it to your `AppModule` imports using the static `LocationUpgradeModule.config()` method. + +```ts +// Other imports ... +import { LocationUpgradeModule } from '@angular/common/upgrade'; + +@NgModule({ + imports: [ + // Other NgModule imports... + LocationUpgradeModule.config() + ] +}) +export class AppModule {} +``` + +The `LocationUpgradeModule.config()` method accepts a configuration object that allows you configure the `LocationStrategy` with the `useHash` property, and the URL prefix with `hashPrefix` property. + +The `useHash` property defaults to `false`, and the `hashPrefix` defaults to an empty `string`. Pass the configuration object to override the defaults. + +```ts +LocationUpgradeModule.config({ + useHash: true + hashPrefix: '!' +}) +``` + +This registers the drop-in replacement for the `$location` provider in AngularJS. Once registered, all navigation, routing broadcast messages, and any necessary digest cycles in AngularJS triggered during navigation are handled by Angular. This gives you a single way to navigate within both sides of your hybrid application consistently. + +For usage of the `$location` service as a provider in AngularJS, you need to downgrade the `$locationShim` using a factory provider. + +```ts +// Other imports ... +import { $locationShim } from '@angular/common/upgrade'; +import { downgradeInjectable } from '@angular/upgrade/static'; + +angular.module('myHybridApp', [...]) + .factory('$location', downgradeInjectable($locationShim)); +``` + +Once you introduce the Angular Router, using the Angular Router triggers navigations through the unified location service, still providing a single source for navigating with AngularJS and Angular. + ## Using Ahead-of-time compilation with hybrid apps You can take advantage of Ahead-of-time (AOT) compilation on hybrid apps just like on any other