| + | 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.path returns "/docroot/actual/path" | +yes - $location.path() returns "/actual/path" | +
+angular.service('$config', function() {
+ return {
+ 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});
+
+All setter methods take an optional boolean flag parameter, which signifies whether current history
+record should be replaced or if a new record should be created (default). To change the current URL
+without creating a new browser history record you can call:
+$location.path('/newVal', true);
+
+Note that the setters don't update `window.location` immediately. Instead, `$location` service is
+aware of the {@link api/angular.scope scope} life-cycle and coalesces multiple `$location`
+mutations into one "commit" to the `window.location` object during the scope `$flush` phase. Since
+any of the setters can take the replace flag, it's enough for one setter to use this flag in order
+to make the entire "commit" a replace operation rather than addition to the browser history.
+
+### Setters and character encoding
+You can pass special characters to `$location` service and it will encode them according to rules
+specified in {@link http://www.ietf.org/rfc/rfc3986.txt 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 {@link http://www.w3.org/TR/html5/history.html 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.
+
+
+
+| + | Hashbang mode | +Html5 mode | +
| configuration | +the default | +{ html5Mode: true } | +
| URL format | +hashbang URLs in all browsers | +regular URLs in modern browser, hashbang URLs in old browser | +
| <a href=""> link rewriting | +no | +yes | +
| requires server-side configuration | +no | +yes | +
+angular.service('$config', function() {
+ return {
+ html5Mode: false,
+ hashPrefix: '!'
+ };
+});
+
+// open http://host.com/base/index.html#!/a
+$location.absUrl() == 'http://host.com/base/index.html#!/a'
+$location.path() == '/a'
+
+$location.path('/foo')
+$location.absUrl() == 'http://host.com/base/index.html#!/foo'
+
+$location.search() == {}
+$location.search({a: 'b', c: true});
+$location.absUrl() == 'http://host.com/base/index.html#!/foo?a=b&c'
+
+$location.path('/new').search('x=y');
+$location.absUrl() == 'http://host.com/base/index.html#!/new?x=y'
+
+
+### Crawling your app
+
+To allow indexing of your AJAX application, you have to add special meta tag in the head section of
+your document:
+
+
+This will cause crawler bot to request links with `_escaped_fragment_` param so that your server
+can recognize the crawler and serve a HTML snapshots. For more information about this technique,
+see {@link http://code.google.com/web/ajaxcrawling/docs/specification.html Making AJAX Applications
+Crawlable}.
+
+## HTML5 mode
+
+In HTML5 mode, the `$location` service getters and setters interact with the browser URL address
+through the HTML5 history API, which allows for use of regular URL path and search segments,
+instead of their hashbang equivalents. If the HTML5 History API is not supported by a browser, the
+`$location` service will fall back to using the hashbang URLs automatically. This frees you from
+having to worry about whether the browser displaying your app supports the history API or not; the
+`$location` service transparently uses the best available option.
+
+- Opening a regular URL in a legacy browser -> redirects to a hashbang URL
+- Opening hashbang URL in a modern browser -> rewrites to a regular URL
+
+### Example
+
+
+angular.service('$config', function() {
+ return {
+ html5Mode: true,
+ hashPrefix: '!'
+ };
+});
+
+// in browser with html5 history support:
+// open http://host.com/#!/a -> rewrite to http://host.com/a
+// (replacing the http://host.com/#!/a history record)
+$location.path() == '/a'
+
+$location.path('/foo');
+$location.absUrl() == 'http://host.com/foo'
+
+$location.search() == {}
+$location.search({a: 'b', c: true});
+$location.absUrl() == 'http://host.com/foo?a=b&c'
+
+$location.path('/new').search('x=y');
+$location.url() == 'new?x=y'
+$location.absUrl() == 'http://host.com/new?x=y'
+
+// in browser without html5 history support:
+// open http://host.com/new?x=y -> redirect to http://host.com/#!/new?x=y
+// (again replacing the http://host.com/new?x=y history item)
+$location.path() == '/new'
+$location.search() == {x: 'y'}
+
+$location.path('/foo/bar');
+$location.path() == '/foo/bar'
+$location.url() == '/foo/bar?x=y'
+$location.absUrl() == 'http://host.com/#!/foo/bar?x=y'
+
+
+### Fallback for legacy browsers
+
+For browsers that support the HTML5 history API, `$location` uses the HTML5 history API to write
+path and search. If the history API is not supported by a browser, `$location` supplies a Hasbang
+URL. This frees you from having to worry about whether the browser viewing your app supports the
+history API or not; the `$location` service makes this transparent to you.
+
+### Html link rewriting
+
+When you use the history API mode, you will need different links in different browser, but all you
+have to do is specify regular URL links, such as: `<a href="/some?foo=bar">link</a>`
+
+When a user clicks on this link,
+
+- In a legacy browser, the URL changes to `/index.html#!/some?foo=bar`
+- In a modern browser, the URL changes to `/some?foo=bar`
+
+
+In cases like the following, links are not rewritten; instead, the browser will perform a full page
+reload to the original link.
+
+- Links with an `ng:ext-link` directive
+angular.service('$serviceUnderTest', function($location) {
+ // whatever it does...
+};
+
+describe('$serviceUnderTest', function() {
+ var scope, $location, $sut;
+
+ beforeEach(function() {
+ scope = angular.scope();
+ $location = scope.$service('$location');
+ $sut = scope.$service('$serviceUnderTest');
+ });
+
+ it('should...', function() {
+ $location.path('/new/path');
+ scope.$apply();
+
+ // test whatever the service should do...
+
+ });
+});
+
+
+
+# Migrating from earlier AngularJS releases
+
+In earlier releases of Angular, `$location` used `hashPath` or `hashSearch` to process path and
+search methods. With this release, the `$location` service processes path and search methods and
+then uses the information it obtains to compose hashbang URLs (such as
+`http://server.com/#!/path?search=a`), when necessary.
+
+## Changes to your code
+
+| Navigation inside the app | +Change to | +
| $location.href = value $location.hash = value $location.update(value) $location.updateHash(value) |
+ $location.path(path).search(search) | +
| $location.hashPath = path | +$location.path(path) | +
| $location.hashSearch = search | +$location.search(search) | +
| Navigation outside the app | +Use lower level API | +
| $location.href = value $location.update(value) |
+ $window.location.href = value | +
| $location[protocol | host | port | path | search] | +$window.location[protocol | host | port | path | search] | +
| Read access | +Change to | +
| $location.hashPath | +$location.path() | +
| $location.hashSearch | +$location.search() | +
| $location.href $location.protocol $location.host $location.port $location.hash |
+ $location.absUrl() $location.protocol() $location.host() $location.port() $location.path() + $location.search() |
+
| $location.path $location.search |
+ $window.location.path $window.location.search |
+
+ + ++
+// js - controller
+this.$watch('locationPath', function(scope, path) {
+ $location.path(path);
+});
+
+this.$watch('$location.path()', function(scope, path) {
+ scope.locationPath = path;
+});
+
+
+
+# Related API
+
+* {@link api/angular.service.$location $location API}
+
+
+
--
cgit v1.2.3