From 0d52a27f41d8ea86f2b42e4d1f33eec3fce7ffe0 Mon Sep 17 00:00:00 2001 From: Brandon Date: Mon, 20 May 2019 12:54:26 -0500 Subject: [PATCH] docs(common): update API docs for unified location service for upgrading (#30567) PR Close #30567 --- packages/common/upgrade/src/location_shim.ts | 102 +++++++++--------- .../upgrade/src/location_upgrade_module.ts | 22 +++- packages/common/upgrade/src/params.ts | 63 ++++++++++- 3 files changed, 130 insertions(+), 57 deletions(-) diff --git a/packages/common/upgrade/src/location_shim.ts b/packages/common/upgrade/src/location_shim.ts index 6a81891e94..b9e7cda766 100644 --- a/packages/common/upgrade/src/location_shim.ts +++ b/packages/common/upgrade/src/location_shim.ts @@ -22,7 +22,10 @@ const DEFAULT_PORTS: {[key: string]: number} = { }; /** - * Docs TBD. + * Location service that provides a drop-in replacement for the $location service + * provided in AngularJS. + * + * @see [Using the Angular Unified Location Service](guide/upgrade#using-the-unified-angular-location-service) * * @publicApi */ @@ -321,12 +324,17 @@ export class $locationShim { } /** - * Register URL change listeners. This API can be used to catch updates performed by the - * AngularJS framework. These changes are a subset of the `$locationChangeStart/Success` events - * as those events fire when AngularJS updates it's internally referenced version of the browser - * URL. It's possible for `$locationChange` events to happen, but for the browser URL + * Registers listeners for URL changes. This API is used to catch updates performed by the + * AngularJS framework. These changes are a subset of the `$locationChangeStart` and + * `$locationChangeSuccess` events which fire when AngularJS updates its internally-referenced + * version of the browser URL. + * + * It's possible for `$locationChange` events to happen, but for the browser URL * (window.location) to remain unchanged. This `onChange` callback will fire only when AngularJS * actually updates the browser URL (window.location). + * + * @param fn The callback function that is triggered for the listener when the URL changes. + * @param err The callback function that is triggered when an error occurs. */ onChange( fn: (url: string, state: unknown, oldUrl: string, oldState: unknown) => void, @@ -346,6 +354,11 @@ export class $locationShim { }); } + /** + * Parses the provided URL, and sets the current URL to the parsed result. + * + * @param url The URL string. + */ $$parse(url: string) { let pathUrl: string|undefined; if (url.startsWith('/')) { @@ -366,6 +379,12 @@ export class $locationShim { this.composeUrls(); } + /** + * Parses the provided URL and its relative URL. + * + * @param url The full URL string. + * @param relHref A URL string relative to the full URL string. + */ $$parseLinkUrl(url: string, relHref?: string|null): boolean { // When relHref is passed, it should be a hash and is handled separately if (relHref && relHref[0] === '#') { @@ -413,9 +432,8 @@ export class $locationShim { } /** - * This method is getter only. - * - * Return full URL representation with all segments encoded according to rules specified in + * Retrieves the full URL representation with all segments encoded according to + * rules specified in * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt). * * @@ -428,12 +446,8 @@ export class $locationShim { absUrl(): string { return this.$$absUrl; } /** - * This method is getter / setter. - * - * Return URL (e.g. `/path?a=b#hash`) when called without any parameter. - * - * Change path, search and hash, when called with parameter and return `$location`. - * + * Retrieves the current URL, or sets a new URL. When setting a URL, + * changes the path, search, and hash, and returns a reference to its own instance. * * ```js * // given URL http://example.com/#/some/path?foo=bar&baz=xoxo @@ -463,10 +477,7 @@ export class $locationShim { } /** - * This method is getter only. - * - * Return protocol of current URL. - * + * Retrieves the protocol of the current URL. * * ```js * // given URL http://example.com/#/some/path?foo=bar&baz=xoxo @@ -477,11 +488,9 @@ export class $locationShim { protocol(): string { return this.$$protocol; } /** - * This method is getter only. + * Retrieves the protocol of the current URL. * - * Return host of current URL. - * - * Note: compared to the non-AngularJS version `location.host` which returns `hostname:port`, this + * In contrast to the non-AngularJS version `location.host` which returns `hostname:port`, this * returns the `hostname` portion only. * * @@ -500,10 +509,7 @@ export class $locationShim { host(): string { return this.$$host; } /** - * This method is getter only. - * - * Return port of current URL. - * + * Retrieves the port of the current URL. * * ```js * // given URL http://example.com/#/some/path?foo=bar&baz=xoxo @@ -514,16 +520,12 @@ export class $locationShim { port(): number|null { return this.$$port; } /** - * This method is getter / setter. + * Retrieves the path of the current URL, or changes the path and returns a reference to its own + * instance. * - * Return path of current URL when called without any parameter. - * - * Change path when called with parameter and return `$location`. - * - * Note: Path should always begin with forward slash (/), this method will add the forward slash + * Paths should always begin with forward slash (/). This method adds the forward slash * if it is missing. * - * * ```js * // given URL http://example.com/#/some/path?foo=bar&baz=xoxo * let path = $location.path(); @@ -548,11 +550,8 @@ export class $locationShim { } /** - * This method is getter / setter. - * - * Return search part (as object) of current URL when called without any parameter. - * - * Change search part when called with parameter and return `$location`. + * Retrieves a map of the search parameters of the current URL, or changes a search + * part and returns a reference to its own instance. * * * ```js @@ -585,8 +584,7 @@ export class $locationShim { * If `paramValue` is `true`, the property specified via the first argument will be added with no * value nor trailing equal sign. * - * @return {Object} If called with no arguments returns the parsed `search` object. If called with - * one or more arguments returns `$location` object itself. + * @return {Object} The parsed `search` object of the current URL, or the changed `search` object. */ search(): {[key: string]: unknown}; search(search: string|number|{[key: string]: unknown}): this; @@ -633,12 +631,8 @@ export class $locationShim { } /** - * This method is getter / setter. - * - * Returns the hash fragment when called without any parameters. - * - * Changes the hash fragment when called with a parameter and returns `$location`. - * + * Retrieves the current hash fragment, or changes the hash fragment and returns a reference to + * its own instance. * * ```js * // given URL http://example.com/#/some/path?foo=bar&baz=xoxo#hashValue @@ -660,7 +654,7 @@ export class $locationShim { } /** - * If called, all changes to $location during the current `$digest` will replace the current + * Changes to `$location` during the current `$digest` will replace the current * history record, instead of adding a new one. */ replace(): this { @@ -669,15 +663,13 @@ export class $locationShim { } /** - * This method is getter / setter. - * - * Return the history state object when called without any parameter. + * Retrieves the history state object when called without any parameter. * * Change the history state object when called with one parameter and return `$location`. * The state object is later passed to `pushState` or `replaceState`. * - * NOTE: This method is supported only in HTML5 mode and only in browsers supporting - * the HTML5 History API (i.e. methods `pushState` and `replaceState`). If you need to support + * This method is supported only in HTML5 mode and only in browsers supporting + * the HTML5 History API methods such as `pushState` and `replaceState`. If you need to support * older browsers (like IE9 or Android < 4.0), don't use this method. * */ @@ -694,7 +686,8 @@ export class $locationShim { } /** - * Docs TBD. + * The factory function used to create an instance of the `$locationShim` in Angular, + * and provides an API-compatiable `$locationProvider` for AngularJS. * * @publicApi */ @@ -704,6 +697,9 @@ export class $locationShimProvider { private platformLocation: PlatformLocation, private urlCodec: UrlCodec, private locationStrategy: LocationStrategy) {} + /** + * Factory method that returns an instance of the $locationShim + */ $get() { return new $locationShim( this.ngUpgrade.$injector, this.location, this.platformLocation, this.urlCodec, diff --git a/packages/common/upgrade/src/location_upgrade_module.ts b/packages/common/upgrade/src/location_upgrade_module.ts index 4cd9ee35b4..720dd986a0 100644 --- a/packages/common/upgrade/src/location_upgrade_module.ts +++ b/packages/common/upgrade/src/location_upgrade_module.ts @@ -20,15 +20,31 @@ import {AngularJSUrlCodec, UrlCodec} from './params'; * @publicApi */ export interface LocationUpgradeConfig { + /** + * Configures whether the location upgrade module should use the `HashLocationStrategy` + * or the `PathLocationStrategy` + */ useHash?: boolean; + /** + * Configures the hash prefix used in the URL when using the `HashLocationStrategy` + */ hashPrefix?: string; + /** + * Configures the URL codec for encoding and decoding URLs. Default is the `AngularJSCodec` + */ urlCodec?: typeof UrlCodec; + /** + * Configures the base href when used in server-side rendered applications + */ serverBaseHref?: string; + /** + * Configures the base href when used in client-side rendered applications + */ appBaseHref?: string; } /** - * Is used in DI to configure the location upgrade package. + * A provider token used to configure the location upgrade module. * * @publicApi */ @@ -38,7 +54,9 @@ export const LOCATION_UPGRADE_CONFIGURATION = const APP_BASE_HREF_RESOLVED = new InjectionToken('APP_BASE_HREF_RESOLVED'); /** - * Module used for configuring Angular's LocationUpgradeService. + * `NgModule` used for providing and configuring Angular's Unified Location Service for upgrading. + * + * @see [Using the Unified Angular Location Service](guide/upgrade#using-the-unified-angular-location-service) * * @publicApi */ diff --git a/packages/common/upgrade/src/params.ts b/packages/common/upgrade/src/params.ts index 612e15310a..025c2edcaa 100644 --- a/packages/common/upgrade/src/params.ts +++ b/packages/common/upgrade/src/params.ts @@ -12,21 +12,80 @@ * @publicApi **/ export abstract class UrlCodec { + /** + * Encodes the path from the provided string + * + * @param path The path string + */ abstract encodePath(path: string): string; + + /** + * Decodes the path from the provided string + * + * @param path The path string + */ abstract decodePath(path: string): string; + /** + * Encodes the search string from the provided string or object + * + * @param path The path string or object + */ abstract encodeSearch(search: string|{[k: string]: unknown}): string; + + /** + * Decodes the search objects from the provided string + * + * @param path The path string + */ abstract decodeSearch(search: string): {[k: string]: unknown}; + /** + * Encodes the hash from the provided string + * + * @param path The hash string + */ abstract encodeHash(hash: string): string; + + /** + * Decodes the hash from the provided string + * + * @param path The hash string + */ abstract decodeHash(hash: string): string; + /** + * Normalizes the URL from the provided string + * + * @param path The URL string + */ abstract normalize(href: string): string; + + + /** + * Normalizes the URL from the provided string, search, hash, and base URL parameters + * + * @param path The URL path + * @param search The search object + * @param hash The has string + * @param baseUrl The base URL for the URL + */ abstract normalize(path: string, search: {[k: string]: unknown}, hash: string, baseUrl?: string): string; + /** + * Checks whether the two strings are equal + * @param valA First string for comparison + * @param valB Second string for comparison + */ abstract areEqual(valA: string, valB: string): boolean; + /** + * Parses the URL string based on the base URL + * + * @param url The full URL string + * @param base The base for the URL + */ abstract parse(url: string, base?: string): { href: string, protocol: string, @@ -40,8 +99,8 @@ export abstract class UrlCodec { } /** - * A `AngularJSUrlCodec` that uses logic from AngularJS to serialize and parse URLs - * and URL parameters + * A `UrlCodec` that uses logic from AngularJS to serialize and parse URLs + * and URL parameters. * * @publicApi */