angularjs
Improve this DocWhat does it do?
The $location
service parses the URL in the browser address bar (based on window.location
) and makes the URL available to your application. Changes to the URL in the address bar are reflected into the $location
service and changes to $location
are reflected into the browser address bar.
The $location service:
- Exposes the current URL in the browser address bar, so you can
- Watch and observe the URL.
- Change the URL.
- Maintains synchronization between itself and the browser's URL when the user
- Changes the address in the browser's address bar.
- Clicks the back or forward button in the browser (or clicks a History link).
- Clicks on a link in the page.
- Represents the URL object as a set of methods (protocol, host, port, path, search, hash).
Comparing $location to window.location
window.location | $location service | |
---|---|---|
purpose | allow read/write access to the current browser location | same |
API | exposes "raw" object with properties that can be directly modified | exposes jQuery-style getters and setters |
integration with angular application life-cycle | none | knows about all internal life-cycle phases, integrates with $watch, ... |
seamless integration with HTML5 API | no | yes (with a fallback for legacy browsers) |
aware of docroot/context from which the application is loaded | no - window.location.pathname returns "/docroot/actual/path" | yes - $location.path() returns "/actual/path" |
When should I use $location?
Any time your application needs to react to a change in the current URL or if you want to change the current URL in the browser.
What does it not do?
It does not cause a full page reload when the browser URL is changed. To reload the page after changing the URL, use the lower-level API, $window.location.href
.
General overview of the API
The $location
service can behave differently, depending on the configuration that was provided to it when it was instantiated. The default configuration is suitable for many applications, for others customizing the configuration can enable new features.
Once the $location
service is instantiated, you can interact with it via jQuery-style getter and setter methods that allow you to get or change the current URL in the browser.
$location service configuration
To configure the $location
service, retrieve the $locationProvider and set the parameters as follows:
-
html5Mode(mode): {boolean|Object}
true
orenabled:true
- see HTML5 mode
false
orenabled:false
- see Hashbang mode
requireBase:true
- see Relative links
default:enabled:false
-
hashPrefix(prefix): {string}
prefix used for Hashbang URLs (used in Hashbang mode or in legacy browser in Html5 mode)
default:""
Example configuration
$locationProvider.html5Mode(true).hashPrefix('!');
Getter and setter methods
$location
service provides getter methods for read-only parts of the URL (absUrl, protocol, host, port) and getter / setter methods for url, path, search, hash:
// get the current path $location.path(); // change the path $location.path('/newValue')
All of the setter methods return the same $location
object to allow chaining. For example, to change multiple segments in one go, chain setters like this:
$location.path('/newValue').search({key: value});
Replace method
There is a special replace
method which can be used to tell the $location service that the next time the $location service is synced with the browser, the last history record should be replaced instead of creating a new one. This is useful when you want to implement redirection, which would otherwise break the back button (navigating back would retrigger the redirection). To change the current URL without creating a new browser history record you can call:
$location.path('/someNewPath'); $location.replace(); // or you can chain these as: $location.path('/someNewPath').replace();
Note that the setters don't update window.location
immediately. Instead, the $location
service is aware of the scope life-cycle and coalesces multiple $location
mutations into one "commit" to the window.location
object during the scope $digest
phase. Since multiple changes to the $location's state will be pushed to the browser as a single change, it's enough to call the replace()
method just once to make the entire "commit" a replace operation rather than an addition to the browser history. Once the browser is updated, the $location service resets the flag set by replace()
method and future mutations will create new history records, unless replace()
is called again.
Setters and character encoding
You can pass special characters to $location
service and it will encode them according to rules specified in RFC 3986. When you access the methods:
- All values that are passed to
$location
setter methods,path()
,search()
,hash()
, are encoded. - Getters (calls to methods without parameters) return decoded values for the following methods
path()
,search()
,hash()
. - When you call the
absUrl()
method, the returned value is a full url with its segments encoded. - When you call the
url()
method, the returned value is path, search and hash, in the form/path?search=a&b=c#hash
. The segments are encoded as well.
Hashbang and HTML5 Modes
$location
service has two configuration modes which control the format of the URL in the browser address bar: Hashbang mode (the default) and the HTML5 mode which is based on using the HTML5 History API. Applications use the same API in both modes and the $location
service will work with appropriate URL segments and browser APIs to facilitate the browser URL change and history management.