jeena/Podcast
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Upgrade to angularjs 1.2.0 rc1

Browse source
This commit is contained in:
Colin Frei 2013-08-21 19:46:51 +02:00
parent d223dfd662
commit d6b021bfaf
674 changed files with 79667 additions and 62269 deletions
Download patch file Download diff file Expand all files Collapse all files

283
lib/angular/docs/partials/guide/dev_guide.services.$location.html Normal file → Executable file
View file

@ -1,27 +1,27 @@
<h1><code ng:non-bindable=""></code>
<span class="hint"></span>
<a href="http://github.com/angular/angular.js/edit/master/docs/content/guide/dev_guide.services.$location.ngdoc" class="improve-docs btn btn-primary"><i class="icon-edit"> </i> Improve this doc</a><h1><code ng:non-bindable=""></code>
<div><span class="hint"></span>
</div>
</h1>
<div><a href="http://github.com/angular/angular.js/edit/master/docs/content/guide/dev_guide.services.$location.ngdoc" class="improve-docs btn btn-primary">Improve this doc</a><h2>What does it do?</h2>
<div><div class="developer-guide-page developer-guide-angular-services-using-location-page"><h2>What does it do?</h1>
<p>The <code>$location</code> 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>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>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>
<h3>Comparing $location to window.location</h3>
<h3>Comparing $location to window.location</h2>
<table class="table">
<thead>
@ -42,7 +42,7 @@ changes to $location are reflected into the browser address bar.</p>
<tr>
<td class="head">API</td>
<td>exposes "raw" object with properties that can be directly modified</td>
<td>exposes &quot;raw&quot; object with properties that can be directly modified</td>
<td>exposes jQuery-style getters and setters</td>
</tr>
@ -60,55 +60,44 @@ changes to $location are reflected into the browser address bar.</p>
<tr>
<td class="head">aware of docroot/context from which the application is loaded</td>
<td>no - window.location.path returns "/docroot/actual/path"</td>
<td>yes - $location.path() returns "/actual/path"</td>
<td>no - window.location.path returns &quot;/docroot/actual/path&quot;</td>
<td>yes - $location.path() returns &quot;/actual/path&quot;</td>
</tr>
</tbody>
</table>
<h3>When should I use $location?</h3>
<h2>When should I use $location?</h2>
<p>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.</p>
<h3>What does it not do?</h3>
<h2>What does it not do?</h2>
<p>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, <code>$window.location.href</code>.</p>
<h2>General overview of the API</h2>
<h1>General overview of the API</h1>
<p>The <code>$location</code> 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.</p>
<p>Once the <code>$location</code> 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.</p>
<h3>$location service configuration</h3>
<h2>$location service configuration</h2>
<p>To configure the <code>$location</code> service, retrieve the
<a href="api/ng.$locationProvider"><code>$locationProvider</code></a> and set the parameters as follows:</p>
<ul>
<li><p><strong>html5Mode(mode)</strong>: {boolean}<br />
<code>true</code> - see HTML5 mode<br />
<code>false</code> - see Hashbang mode<br />
default: <code>false</code></p></li>
default: <code>false</code></p>
</li>
<li><p><strong>hashPrefix(prefix)</strong>: {string}<br />
prefix used for Hashbang URLs (used in Hashbang mode or in legacy browser in Html5 mode)<br />
default: <code>'!'</code></p></li>
default: <code>&quot;&quot;</code></p>
</li>
</ul>
<h4>Example configuration</h4>
<h4>Example configuration</h3>
<pre class="prettyprint linenums">
$locationProvider.html5Mode(true).hashPrefix('!');
</pre>
<h3>Getter and setter methods</h3>
<h2>Getter and setter methods</h2>
<p><code>$location</code> service provides getter methods for read-only parts of the URL (absUrl, protocol, host,
port) and getter / setter methods for url, path, search, hash:
<pre class="prettyprint linenums">
@ -118,11 +107,9 @@ $location.path();
// change the path
$location.path('/newValue')
</pre>
<p>All of the setter methods return the same <code>$location</code> object to allow chaining. For example, to
change multiple segments in one go, chain setters like this:
<pre class="prettyprint linenums">$location.path('/newValue').search({key: value});</pre>
<p>There is a special <code>replace</code> 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
@ -133,21 +120,17 @@ current URL without creating a new browser history record you can call:
$location.replace();
// or you can chain these as: $location.path('/someNewPath').replace();
</pre>
<p>Note that the setters don't update <code>window.location</code> immediately. Instead, the <code>$location</code> service is
<p>Note that the setters don&#39;t update <code>window.location</code> immediately. Instead, the <code>$location</code> service is
aware of the <a href="api/ng.$rootScope.Scope"><code>scope</code></a> life-cycle and coalesces multiple <code>$location</code>
mutations into one "commit" to the <code>window.location</code> object during the scope <code>$digest</code> 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 <code>replace()</code> method just once to make the entire "commit" a replace operation
mutations into one &quot;commit&quot; to the <code>window.location</code> object during the scope <code>$digest</code> phase. Since
multiple changes to the $location&#39;s state will be pushed to the browser as a single change, it&#39;s
enough to call the <code>replace()</code> method just once to make the entire &quot;commit&quot; a replace operation
rather than an addition to the browser history. Once the browser is updated, the $location service
resets the flag set by <code>replace()</code> method and future mutations will create new history records,
unless <code>replace()</code> is called again.</p>
<h4>Setters and character encoding</h4>
<h3>Setters and character encoding</h3>
<p>You can pass special characters to <code>$location</code> service and it will encode them according to rules
specified in <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>. When you access the methods:</p>
<ul>
<li>All values that are passed to <code>$location</code> setter methods, <code>path()</code>, <code>search()</code>, <code>hash()</code>, are
encoded.</li>
@ -157,17 +140,13 @@ encoded.</li>
<li>When you call the <code>url()</code> method, the returned value is path, search and hash, in the form
<code>/path?search=a&amp;b=c#hash</code>. The segments are encoded as well.</li>
</ul>
<h2>Hashbang and HTML5 Modes</h2>
<h1>Hashbang and HTML5 Modes</h1>
<p><code>$location</code> service has two configuration modes which control the format of the URL in the browser
address bar: <strong>Hashbang mode</strong> (the default) and the <strong>HTML5 mode</strong> which is based on using the
HTML5 <a href="http://www.w3.org/TR/html5/history.html">History API</a>. Applications use the same API in
both modes and the <code>$location</code> service will work with appropriate URL segments and browser APIs to
facilitate the browser URL change and history management.</p>
<p><img src="img/guide/hashbang_vs_regular_url.jpg"></p>
<table class="table">
<thead>
@ -193,7 +172,7 @@ facilitate the browser URL change and history management.</p>
</tr>
<tr>
<td class="head">&lt;a href=""&gt; link rewriting</td>
<td class="head">&lt;a href=&quot;&quot;&gt; link rewriting</td>
<td>no</td>
<td>yes</td>
</tr>
@ -206,17 +185,14 @@ facilitate the browser URL change and history management.</p>
</tbody>
</table>
<h3>Hashbang mode (default mode)</h3>
<h2>Hashbang mode (default mode)</h2>
<p>In this mode, <code>$location</code> uses Hashbang URLs in all browsers.</p>
<h4>Example</h4>
<h3>Example</h3>
<pre class="prettyprint linenums">
it('should show example', inject(
function($locationProvider) {
$locationProvider.html5Mode(false);
$locationProvider.hashPrefix = '!';
$locationProvider.hashPrefix('!');
},
function($location) {
// open http://host.com/base/index.html#!/a
@ -235,38 +211,30 @@ it('should show example', inject(
}
));
</pre>
<h4>Crawling your app</h4>
<h3>Crawling your app</h3>
<p>To allow indexing of your AJAX application, you have to add special meta tag in the head section of
your document:
<pre class="prettyprint linenums">&lt;meta name="fragment" content="!" /&gt;</pre>
<p>This will cause crawler bot to request links with <code>_escaped_fragment_</code> param so that your server
can recognize the crawler and serve a HTML snapshots. For more information about this technique,
see <a href="http://code.google.com/web/ajaxcrawling/docs/specification.html">Making AJAX Applications Crawlable</a>.</p>
<h3>HTML5 mode</h3>
<h2>HTML5 mode</h2>
<p>In HTML5 mode, the <code>$location</code> 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
<code>$location</code> 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
<code>$location</code> service transparently uses the best available option.</p>
<ul>
<li>Opening a regular URL in a legacy browser -> redirects to a hashbang URL</li>
<li>Opening hashbang URL in a modern browser -> rewrites to a regular URL</li>
<li>Opening a regular URL in a legacy browser -&gt; redirects to a hashbang URL</li>
<li>Opening hashbang URL in a modern browser -&gt; rewrites to a regular URL</li>
</ul>
<h4>Example</h4>
<h3>Example</h3>
<pre class="prettyprint linenums">
it('should show example', inject(
function($locationProvider) {
$locationProvider.html5Mode(true);
$locationProvider.hashPrefix = '!';
$locationProvider.hashPrefix('!');
},
function($location) {
// in browser with HTML5 history support:
@ -298,93 +266,70 @@ it('should show example', inject(
}
));
</pre>
<h4>Fallback for legacy browsers</h4>
<h3>Fallback for legacy browsers</h3>
<p>For browsers that support the HTML5 history API, <code>$location</code> uses the HTML5 history API to write
path and search. If the history API is not supported by a browser, <code>$location</code> 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 <code>$location</code> service makes this transparent to you.</p>
<h4>Html link rewriting</h4>
<h3>Html link rewriting</h3>
<p>When you use HTML5 history API mode, you will need different links in different browsers, but all you
have to do is specify regular URL links, such as: <code>&lt;a href="/some?foo=bar"&gt;link&lt;/a&gt;</code></p>
have to do is specify regular URL links, such as: <code>&lt;a href=&quot;/some?foo=bar&quot;&gt;link&lt;/a&gt;</code></p>
<p>When a user clicks on this link,</p>
<ul>
<li>In a legacy browser, the URL changes to <code>/index.html#!/some?foo=bar</code></li>
<li>In a modern browser, the URL changes to <code>/some?foo=bar</code></li>
</ul>
<p>In cases like the following, links are not rewritten; instead, the browser will perform a full page
reload to the original link.</p>
<ul>
<li>Links that contain <code>target</code> element<br>
Example: <code>&lt;a href="/ext/link?a=b" target="_self"&gt;link&lt;/a&gt;</code></li>
Example: <code>&lt;a href=&quot;/ext/link?a=b&quot; target=&quot;_self&quot;&gt;link&lt;/a&gt;</code></li>
<li>Absolute links that go to a different domain<br>
Example: <code>&lt;a href="http://angularjs.org/"&gt;link&lt;/a&gt;</code></li>
<li>Links starting with '/' that lead to a different base path when base is defined<br>
Example: <code>&lt;a href="/not-my-base/link"&gt;link&lt;/a&gt;</code></li>
Example: <code>&lt;a href=&quot;http://angularjs.org/&quot;&gt;link&lt;/a&gt;</code></li>
<li>Links starting with &#39;/&#39; that lead to a different base path when base is defined<br>
Example: <code>&lt;a href=&quot;/not-my-base/link&quot;&gt;link&lt;/a&gt;</code></li>
</ul>
<h4>Server side</h4>
<h3>Server side</h3>
<p>Using this mode requires URL rewriting on server side, basically you have to rewrite all your links
to entry point of your application (e.g. index.html)</p>
<h4>Crawling your app</h4>
<h3>Crawling your app</h3>
<p>If you want your AJAX application to be indexed by web crawlers, you will need to add the following
meta tag to the HEAD section of your document:
<pre class="prettyprint linenums">&lt;meta name="fragment" content="!" /&gt;</pre>
<p>This statement causes a crawler to request links with an empty <code>_escaped_fragment_</code> parameter so that
your server can recognize the crawler and serve it HTML snapshots. For more information about this
technique, see <a href="http://code.google.com/web/ajaxcrawling/docs/specification.html">Making AJAX Applications Crawlable</a>.</p>
<h4>Relative links</h4>
<h3>Relative links</h3>
<p>Be sure to check all relative links, images, scripts etc. You must either specify the url base in
the head of your main html file (<code>&lt;base href="/my-base"&gt;</code>) or you must use absolute urls
the head of your main html file (<code>&lt;base href=&quot;/my-base&quot;&gt;</code>) or you must use absolute urls
(starting with <code>/</code>) everywhere because relative urls will be resolved to absolute urls using the
initial absolute url of the document, which is often different from the root of the application.</p>
<p>Running Angular apps with the History API enabled from document root is strongly encouraged as it
takes care of all relative link issues.</p>
<h4>Sending links among different browsers</h4>
<h3>Sending links among different browsers</h3>
<p>Because of rewriting capability in HTML5 mode, your users will be able to open regular url links in
legacy browsers and hashbang links in modern browser:</p>
<ul>
<li>Modern browser will rewrite hashbang URLs to regular URLs.</li>
<li>Older browsers will redirect regular URLs to hashbang URLs.</li>
</ul>
<h4>Example</h4>
<h3>Example</h3>
<p>Here you can see two <code>$location</code> instances, both in <strong>Html5 mode</strong>, but on different browsers, so
that you can see the differences. These <code>$location</code> services are connected to a fake browsers. Each
input represents address bar of the browser.</p>
<p>Note that when you type hashbang url into first browser (or vice versa) it doesn't rewrite /
<p>Note that when you type hashbang url into first browser (or vice versa) it doesn&#39;t rewrite /
redirect to regular / hashbang url, as this conversion happens only during parsing the initial URL
= on page reload.</p>
<p>In this examples we use <code>&lt;base href="/base/index.html" /&gt;</code>
<h3>Source</h3>
<div source-edit="" source-edit-deps="angular.js script.js" source-edit-html="index.html-37" source-edit-css="" source-edit-js="script.js-36" source-edit-unit="" source-edit-scenario=""></div>
<p>In this examples we use <code>&lt;base href=&quot;/base/index.html&quot; /&gt;</code>
<h2>Source</h2>
<div source-edit="" source-edit-deps="angular.js script.js" source-edit-html="index.html-200" source-edit-css="" source-edit-js="script.js-199" source-edit-json="" source-edit-unit="" source-edit-scenario=""></div>
<div class="tabbable"><div class="tab-pane" title="index.html">
<pre class="prettyprint linenums" ng-set-text="index.html-37" ng-html-wrap=" angular.js script.js"></pre>
<script type="text/ng-template" id="index.html-37">
<pre class="prettyprint linenums" ng-set-text="index.html-200" ng-html-wrap=" angular.js script.js"></pre>
<script type="text/ng-template" id="index.html-200">
<div ng-non-bindable class="html5-hashbang-example">
<div id="html5-mode" ng-controller="Html5Cntl">
<h4>Browser with History API</h4>
<h3>Browser with History API</h3>
<div ng-address-bar browser="html5"></div><br><br>
$location.protocol() = {{$location.protocol()}}<br>
$location.host() = {{$location.host()}}<br>
@ -398,7 +343,7 @@ redirect to regular / hashbang url, as this conversion happens only during parsi
</div>
<div id="hashbang-mode" ng-controller="HashbangCntl">
<h4>Browser without History API</h4>
<h3>Browser without History API</h4>
<div ng-address-bar browser="hashbang"></div><br><br>
$location.protocol() = {{$location.protocol()}}<br>
$location.host() = {{$location.host()}}<br>
@ -417,8 +362,8 @@ redirect to regular / hashbang url, as this conversion happens only during parsi
</script>
</div>
<div class="tab-pane" title="script.js">
<pre class="prettyprint linenums" ng-set-text="script.js-36"></pre>
<script type="text/ng-template" id="script.js-36">
<pre class="prettyprint linenums" ng-set-text="script.js-199"></pre>
<script type="text/ng-template" id="script.js-199">
function FakeBrowser(initUrl, baseHref) {
this.onUrlChange = function(fn) {
this.urlChange = fn;
@ -467,7 +412,7 @@ redirect to regular / hashbang url, as this conversion happens only during parsi
input = angular.element('<input type="text">').val(browser.url()),
delay;
input.bind('keypress keyup keydown', function() {
input.on('keypress keyup keydown', function() {
if (!delay) {
delay = setTimeout(fireUrlChange, 250);
}
@ -486,7 +431,7 @@ redirect to regular / hashbang url, as this conversion happens only during parsi
};
});
}]);
root.bind('click', function(e) {
root.on('click', function(e) {
e.stopPropagation();
});
}
@ -495,39 +440,28 @@ redirect to regular / hashbang url, as this conversion happens only during parsi
initEnv('hashbang');
</script>
</div>
</div><h3>Demo</h3>
<div class="well doc-example-live animator-container" ng-embed-app="" ng-set-html="index.html-37" ng-eval-javascript="script.js-36"></div>
<h2>Caveats</h2>
<h3>Page reload navigation</h3>
</div><h2>Demo</h2>
<div class="well doc-example-live animate-container" ng-embed-app="" ng-set-html="index.html-200" ng-eval-javascript="script.js-199"></div>
<h1>Caveats</h1>
<h2>Page reload navigation</h2>
<p>The <code>$location</code> service allows you to change only the URL; it does not allow you to reload the
page. When you need to change the URL and reload the page or navigate to a different page, please
use a lower level API, <a href="api/ng.$window"><code>$window.location.href</code></a>.</p>
<h3>Using $location outside of the scope life-cycle</h3>
<p><code>$location</code> knows about Angular's <a href="api/ng.$rootScope.Scope"><code>scope</code></a> life-cycle. When a URL changes in
<h2>Using $location outside of the scope life-cycle</h2>
<p><code>$location</code> knows about Angular&#39;s <a href="api/ng.$rootScope.Scope"><code>scope</code></a> life-cycle. When a URL changes in
the browser it updates the <code>$location</code> and calls <code>$apply</code> so that all $watchers / $observers are
notified.
When you change the <code>$location</code> inside the <code>$digest</code> phase everything is ok; <code>$location</code> will
propagate this change into browser and will notify all the $watchers / $observers.
When you want to change the <code>$location</code> from outside Angular (for example, through a DOM Event or
during testing) - you must call <code>$apply</code> to propagate the changes.</p>
<h3>$location.path() and ! or / prefixes</h3>
<h2>$location.path() and ! or / prefixes</h2>
<p>A path should always begin with forward slash (<code>/</code>); the <code>$location.path()</code> setter will add the
forward slash if it is missing.</p>
<p>Note that the <code>!</code> prefix in the hashbang mode is not part of <code>$location.path()</code>; it is actually
hashPrefix.</p>
<h2>Testing with the $location service</h2>
<p>When using <code>$location</code> service during testing, you are outside of the angular's <a href="api/ng.$rootScope.Scope"><code>scope</code></a> life-cycle. This means it's your responsibility to call <code>scope.$apply()</code>.</p>
<h1>Testing with the $location service</h1>
<p>When using <code>$location</code> service during testing, you are outside of the angular&#39;s <a href="api/ng.$rootScope.Scope"><code>scope</code></a> life-cycle. This means it&#39;s your responsibility to call <code>scope.$apply()</code>.</p>
<pre class="prettyprint linenums">
describe('serviceUnderTest', function() {
beforeEach(module(function($provide) {
@ -545,16 +479,12 @@ describe('serviceUnderTest', function() {
}));
});
</pre>
<h2>Migrating from earlier AngularJS releases</h2>
<h1>Migrating from earlier AngularJS releases</h1>
<p>In earlier releases of Angular, <code>$location</code> used <code>hashPath</code> or <code>hashSearch</code> to process path and
search methods. With this release, the <code>$location</code> service processes path and search methods and
then uses the information it obtains to compose hashbang URLs (such as
<code>http://server.com/#!/path?search=a</code>), when necessary.</p>
<h3>Changes to your code</h3>
<h2>Changes to your code</h2>
<table class="table">
<thead>
<tr class="head">
@ -624,29 +554,40 @@ then uses the information it obtains to compose hashbang URLs (such as
</tbody>
</table>
<h3>Two-way binding to $location</h3>
<p>The Angular's compiler currently does not support two-way binding for methods (see <a href="https://github.com/angular/angular.js/issues/404">issue</a>). If you should require two-way binding
<h2>Two-way binding to $location</h2>
<p>The Angular&#39;s compiler currently does not support two-way binding for methods (see <a href="https://github.com/angular/angular.js/issues/404">issue</a>). If you should require two-way binding
to the $location object (using <a href="api/ng.directive:input.text"><code>ngModel</code></a> directive on an input field), you will need to specify an extra model property
(e.g. <code>locationPath</code>) with two watchers which push $location updates in both directions. For
example:
<pre class="prettyprint linenums">
&lt;!-- html --&gt;
&lt;input type="text" ng-model="locationPath" /&gt;
</pre>
<pre class="prettyprint linenums">
// js - controller
$scope.$watch('locationPath', function(path) {
$location.path(path);
});
$scope.$watch('$location.path()', function(path) {
scope.locationPath = path;
});
</pre>
<h2>Related API</h2>
<h2>Source</h2>
<div source-edit="" source-edit-deps="angular.js script.js" source-edit-html="index.html-201" source-edit-css="" source-edit-js="script.js-202" source-edit-json="" source-edit-unit="" source-edit-scenario=""></div>
<div class="tabbable"><div class="tab-pane" title="index.html">
<pre class="prettyprint linenums" ng-set-text="index.html-201" ng-html-wrap=" angular.js script.js"></pre>
<script type="text/ng-template" id="index.html-201">
<div ng-controller="LocationController">
<input type="text" ng-model="locationPath" />
</div>
</script>
</div>
<div class="tab-pane" title="script.js">
<pre class="prettyprint linenums" ng-set-text="script.js-202"></pre>
<script type="text/ng-template" id="script.js-202">
function LocationController($scope, $location) {
$scope.$watch('locationPath', function(path) {
$location.path(path);
});
$scope.$watch(function() {
return $location.path();
}, function(path) {
$scope.locationPath = path;
});
}
</script>
</div>
</div><h2>Demo</h3>
<div class="well doc-example-live animate-container" ng-embed-app="" ng-set-html="index.html-201" ng-eval-javascript="script.js-202"></div>
<h1>Related API</h2>
<ul>
<li><a href="api/ng.$location"><code>$location API</code></a></li>
</ul></div>
</ul>
</div></div>