diff --git a/aio/content/guide/router.md b/aio/content/guide/router.md index 73902bd3f2..82a711e0a3 100644 --- a/aio/content/guide/router.md +++ b/aio/content/guide/router.md @@ -541,6 +541,15 @@ set the `href` value in `index.html` as shown here. ### HTML5 URLs and the `` +The guidelines that follow will refer to different parts of a URL. This diagram outlines what those parts refer to: + +``` +foo://example.com:8042/over/there?name=ferret#nose +\_/ \______________/\_________/ \_________/ \__/ + | | | | | +scheme authority path query fragment +``` + While the router uses the HTML5 pushState style by default, you must configure that strategy with a ``. The preferred way to configure the strategy is to add a <base href> element tag in the `` of the `index.html`. @@ -554,8 +563,16 @@ Some developers may not be able to add the `` element, perhaps because the Those developers may still use HTML5 URLs by taking the following two steps: -1. Provide the router with an appropriate [APP_BASE_HREF][] value. -1. Use root URLs for all web resources: CSS, images, scripts, and template HTML files. +1. Provide the router with an appropriate `APP_BASE_HREF` value. +1. Use root URLs (URLs with an `authority`) for all web resources: CSS, images, scripts, and template HTML files. + +* The `` `path` should end with a "/", as browsers ignore characters in the `path` that follow the right-most "/". +* If the `` includes a `query` part, the `query` is only used if the `path` of a link in the page is empty and has no `query`. +This means that a `query` in the `` is only included when using `HashLocationStrategy`. +* If a link in the page is a root URL (has an `authority`), the `` is not used. In this way, an `APP_BASE_HREF` with an authority will cause all links created by Angular to ignore the `` value. +* A fragment in the `` is _never_ persisted. + +For more complete information on how `` is used to construct target URIs, see the [RFC](https://tools.ietf.org/html/rfc3986#section-5.2.2) section on transforming references. {@a hashlocationstrategy} diff --git a/packages/common/src/location/location_strategy.ts b/packages/common/src/location/location_strategy.ts index c10880d45d..3d9bc0e05f 100644 --- a/packages/common/src/location/location_strategy.ts +++ b/packages/common/src/location/location_strategy.ts @@ -81,16 +81,20 @@ export const APP_BASE_HREF = new InjectionToken('appBaseHref'); * browser's URL. * * If you're using `PathLocationStrategy`, you must provide a {@link APP_BASE_HREF} - * or add a base element to the document. This URL prefix that will be preserved - * when generating and recognizing URLs. + * or add a `` element to the document. * - * For instance, if you provide an `APP_BASE_HREF` of `'/my/app'` and call + * For instance, if you provide an `APP_BASE_HREF` of `'/my/app/'` and call + * `location.go('/foo')`, the browser's URL will become + * `example.com/my/app/foo`. To ensure all relative URIs resolve correctly, + * the `` and/or `APP_BASE_HREF` should end with a `/`. + * + * Similarly, if you add `` to the document and call * `location.go('/foo')`, the browser's URL will become * `example.com/my/app/foo`. * - * Similarly, if you add `` to the document and call - * `location.go('/foo')`, the browser's URL will become - * `example.com/my/app/foo`. + * Note that when using `PathLocationStrategy`, neither the query nor + * the fragment in the `` will be preserved, as outlined + * by the [RFC](https://tools.ietf.org/html/rfc3986#section-5.2.2). * * @usageNotes *