forked from angular/code.angularjs.org
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathng.$location.html
141 lines (141 loc) · 11.8 KB
/
ng.$location.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
<a href="http://github.com/angular/angular.js/tree/v1.2.3/src/ng/location.js#L497" class="view-source btn btn-action"><i class="icon-zoom-in"> </i> View source</a><a href="http://github.com/angular/angular.js/edit/master/src/ng/location.js" class="improve-docs btn btn-primary"><i class="icon-edit"> </i> Improve this doc</a><h1><code ng:non-bindable="">$location</code>
<div><span class="hint">service in module <code ng:non-bindable="">ng</code>
</span>
</div>
</h1>
<div><h2 id="description">Description</h2>
<div class="description"><div class="ng-location-page"><p>The $location service parses the URL in the browser address bar (based on the
<a href="https://developer.mozilla.org/en/window.location">window.location</a>) and makes the URL
available to your application. Changes to the URL in the address bar are reflected into
$location service and changes to $location are reflected into the browser address bar.</p>
<p><strong>The $location service:</strong></p>
<ul>
<li>Exposes the current URL in the browser address bar, so you can<ul>
<li>Watch and observe the URL.</li>
<li>Change the URL.</li>
</ul>
</li>
<li>Synchronizes the URL with the browser when the user<ul>
<li>Changes the address bar.</li>
<li>Clicks the back or forward button (or clicks a History link).</li>
<li>Clicks on a link.</li>
</ul>
</li>
<li>Represents the URL object as a set of methods (protocol, host, port, path, search, hash).</li>
</ul>
<p>For more information see <a href="guide/dev_guide.services.$location">Developer Guide: Angular Services: Using $location</a></p>
</div></div>
<h2 id="dependencies">Dependencies</h2>
<ul class="dependencies"><li><code ng:non-bindable=""><a href="api/ng.$browser">$browser</a></code>
</li>
<li><code ng:non-bindable=""><a href="api/ng.$sniffer">$sniffer</a></code>
</li>
<li><code ng:non-bindable=""><a href="api/ng.$rootElement">$rootElement</a></code>
</li>
</ul>
<div class="member method"><h2 id="methods">Methods</h2>
<ul class="methods"><li><h3 id="methods_absurl">absUrl()</h3>
<div class="absurl"><div class="ng-location-absurl-page"><p>This method is getter only.</p>
<p>Return full url representation with all segments encoded according to rules specified in
<a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.</p>
</div><h5 id="methods_absurl_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-absurl-page"><p>full url</p>
</div></td></tr></table></div>
</li>
<li><h3 id="methods_hash">hash(hash)</h3>
<div class="hash"><div class="ng-location-hash-page"><p>This method is getter / setter.</p>
<p>Return hash fragment when called without any parameter.</p>
<p>Change hash fragment when called with parameter and return <code>$location</code>.</p>
</div><h5 id="methods_hash_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>hash <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-hash-page"><p>New hash fragment</p>
</div></td></tr></tbody></table><h5 id="methods_hash_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-hash-page"><p>hash</p>
</div></td></tr></table></div>
</li>
<li><h3 id="methods_host">host()</h3>
<div class="host"><div class="ng-location-host-page"><p>This method is getter only.</p>
<p>Return host of current url.</p>
</div><h5 id="methods_host_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-host-page"><p>host of current url.</p>
</div></td></tr></table></div>
</li>
<li><h3 id="methods_path">path(path)</h3>
<div class="path"><div class="ng-location-path-page"><p>This method is getter / setter.</p>
<p>Return path of current url when called without any parameter.</p>
<p>Change path when called with parameter and return <code>$location</code>.</p>
<p>Note: Path should always begin with forward slash (/), this method will add the forward slash
if it is missing.</p>
</div><h5 id="methods_path_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>path <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-path-page"><p>New path</p>
</div></td></tr></tbody></table><h5 id="methods_path_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-path-page"><p>path</p>
</div></td></tr></table></div>
</li>
<li><h3 id="methods_port">port()</h3>
<div class="port"><div class="ng-location-port-page"><p>This method is getter only.</p>
<p>Return port of current url.</p>
</div><h5 id="methods_port_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-number">Number</a></td><td><div class="ng-location-port-page"><p>port</p>
</div></td></tr></table></div>
</li>
<li><h3 id="methods_protocol">protocol()</h3>
<div class="protocol"><div class="ng-location-protocol-page"><p>This method is getter only.</p>
<p>Return protocol of current url.</p>
</div><h5 id="methods_protocol_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-protocol-page"><p>protocol of current url</p>
</div></td></tr></table></div>
</li>
<li><h3 id="methods_replace">replace()</h3>
<div class="replace"><div class="ng-location-replace-page"><p>If called, all changes to $location during current <code>$digest</code> will be replacing current history
record, instead of adding new one.</p>
</div></div>
</li>
<li><h3 id="methods_search">search(search, paramValue)</h3>
<div class="search"><div class="ng-location-search-page"><p>This method is getter / setter.</p>
<p>Return search part (as object) of current url when called without any parameter.</p>
<p>Change search part when called with parameter and return <code>$location</code>.</p>
</div><h5 id="methods_search_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>search</td><td><a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-object">Object.<string></a><a href="" class="label type-hint type-hint-object">Object.<Array.<string>></a></td><td><div class="ng-location-search-page"><p>New search params - string or
hash object. Hash object may contain an array of values, which will be decoded as duplicates in
the url.</p>
</div></td></tr><tr><td>paramValue <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a><a href="" class="label type-hint type-hint-array">Array<string></a></td><td><div class="ng-location-search-page"><p>If <code>search</code> is a string, then <code>paramValue</code> will override only a
single search parameter. If <code>paramValue</code> is an array, it will set the parameter as a
comma-separated value. If <code>paramValue</code> is <code>null</code>, the parameter will be deleted.</p>
</div></td></tr></tbody></table><h5 id="methods_search_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-search-page"><p>search</p>
</div></td></tr></table></div>
</li>
<li><h3 id="methods_url">url(url, replace)</h3>
<div class="url"><div class="ng-location-url-page"><p>This method is getter / setter.</p>
<p>Return url (e.g. <code>/path?a=b#hash</code>) when called without any parameter.</p>
<p>Change path, search and hash, when called with parameter and return <code>$location</code>.</p>
</div><h5 id="methods_url_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>url <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-url-page"><p>New url without base prefix (e.g. <code>/path?a=b#hash</code>)</p>
</div></td></tr><tr><td>replace <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-url-page"><p>The path that will be changed</p>
</div></td></tr></tbody></table><h5 id="methods_url_returns">Returns</h5><table class="variables-matrix"><tr><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-url-page"><p>url</p>
</div></td></tr></table></div>
</li>
</ul>
</div>
<div class="member event"><h2 id="events">Events</h2>
<ul class="events"><li><h3 id="events_$locationchangestart">$locationChangeStart</h3>
<div class="$locationchangestart"><div class="ng-location-locationchangestart-page"><p>Broadcasted before a URL will change. This change can be prevented by calling
<code>preventDefault</code> method of the event. See <a href="api/ng.$rootScope.Scope#$on"><code>ng.$rootScope.Scope#$on</code></a> for more
details about event object. Upon successful change
<a href="api/ng.$location#$locationchangesuccess"><code>$locationChangeSuccess</code></a> is fired.</p>
</div><div class="inline"><h4 id="events_$locationchangestart_type">Type:</h4>
<div class="type">broadcast</div>
</div>
<div class="inline"><h4 id="events_$locationchangestart_target">Target:</h4>
<div class="target">root scope</div>
</div>
<h5 id="events_$locationchangestart_target_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>angularEvent</td><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="ng-location-locationchangestart-page"><p>Synthetic event object.</p>
</div></td></tr><tr><td>newUrl</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-locationchangestart-page"><p>New URL</p>
</div></td></tr><tr><td>oldUrl <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-locationchangestart-page"><p>URL that was before it was changed.</p>
</div></td></tr></tbody></table></div>
</li>
<li><h3 id="events_$locationchangesuccess">$locationChangeSuccess</h3>
<div class="$locationchangesuccess"><div class="ng-location-locationchangesuccess-page"><p>Broadcasted after a URL was changed.</p>
</div><div class="inline"><h4 id="events_$locationchangesuccess_type">Type:</h4>
<div class="type">broadcast</div>
</div>
<div class="inline"><h4 id="events_$locationchangesuccess_target">Target:</h4>
<div class="target">root scope</div>
</div>
<h5 id="events_$locationchangesuccess_target_parameters">Parameters</h5><table class="variables-matrix table table-bordered table-striped"><thead><tr><th>Param</th><th>Type</th><th>Details</th></tr></thead><tbody><tr><td>angularEvent</td><td><a href="" class="label type-hint type-hint-object">Object</a></td><td><div class="ng-location-locationchangesuccess-page"><p>Synthetic event object.</p>
</div></td></tr><tr><td>newUrl</td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-locationchangesuccess-page"><p>New URL</p>
</div></td></tr><tr><td>oldUrl <div><em>(optional)</em></div></td><td><a href="" class="label type-hint type-hint-string">string</a></td><td><div class="ng-location-locationchangesuccess-page"><p>URL that was before it was changed.</p>
</div></td></tr></tbody></table></div>
</li>
</ul>
</div>
</div>