angular.service.$route.html

<h1>angular.service.$route</h1>
<div class="angular-service-route"><fieldset class="workInProgress"><legend>Work in Progress</legend>
This page is currently being revised. It might be incomplete or contain inaccuracies.</fieldset>
<h2>Description</h2>
<div class="description"><p>Watches <code>$location.hashPath</code> and tries to map the hash to an existing route
definition. It is used for deep-linking URLs to controllers and views (HTML partials).</p>

<p>The <code>$route</code> service is typically used in conjunction with <a href="#!angular.widget.ng:view"><code>ng:view</code></a>
widget.</p></div>
<h2>Dependencies</h2>
<ul class="dependencies"><li><code ng:non-bindable=""><a href="#!angular.service.$location">$location</a>
</code>
</li>
</ul>
<h2>Methods</h2>
<ul class="methods"><li><h3>onChange(fn)</h3>
<div class="onchange-fn-"><p>Register a handler function that will be called when route changes</p><h4>Parameters</h4>
<ul class="parameters"><li><code ng:non-bindable="">fn – {function()} – </code>
<p>Function that will be called when <code>$route.current</code> changes.</p></li>
</ul>
</div>
</li>
<li><h3>otherwise(params)</h3>
<div class="otherwise-params-"><p>Sets route definition that will be used on route change when no other route definition
is matched.</p><h4>Parameters</h4>
<ul class="parameters"><li><code ng:non-bindable="">params – {Object} – </code>
<p>Mapping information to be assigned to <code>$route.current</code>.</p></li>
</ul>
</div>
</li>
<li><h3>parent(scope)</h3>
<div class="parent-scope-"><p>Sets a scope to be used as the parent scope for scopes created on route change. If not
set, defaults to the root scope.</p><h4>Parameters</h4>
<ul class="parameters"><li><code ng:non-bindable="">scope – {Scope} – </code>
<p>Scope to be used as parent for newly created
<code>$route.current.scope</code> scopes.</p></li>
</ul>
</div>
</li>
<li><h3>reload()</h3>
<div class="reload-"><p>Causes <code>$route</code> service to reload (and recreate the <code>$route.current</code> scope) upon the next
eval even if <a href="#!angular.service.$location"><code>$location</code></a> hasn't changed.</p></div>
</li>
<li><h3>when(path, params)</h3>
<div class="when-path-params-"><p>Adds a new route definition to the <code>$route</code> service.</p><h4>Parameters</h4>
<ul class="parameters"><li><code ng:non-bindable="">path – {string} – </code>
<p>Route path (matched against <code>$location.hash</code>)</p></li>
<li><code ng:non-bindable="">params – {Object} – </code>
<p>Mapping information to be assigned to <code>$route.current</code> on route
match.</p>

<p>Object properties:</p>

<ul>
<li><code>controller</code> – <code>{function()=}</code> – Controller fn that should be associated with newly
created scope.</li>
<li><code>template</code> – <code>{string=}</code> – path to an html template that should be used by
<a href="#!angular.widget.ng:view"><code>ng:view</code></a> or
<a href="#!angular.widget.ng:include"><code>ng:include</code></a> widgets.</li>
<li><p><code>redirectTo</code> – {(string|function())=} – value to update
<a href="#!angular.service.$location"><code>$location</code></a> hash with and trigger route redirection.</p>

<p>If <code>redirectTo</code> is a function, it will be called with the following parameters:</p>

<ul><li><code>{Object.&lt;string&gt;}</code> - route parameters extracted from the current
<code>$location.hashPath</code> by applying the current route template.</li>
<li><code>{string}</code> - current <code>$location.hash</code></li>
<li><code>{string}</code> - current <code>$location.hashPath</code></li>
<li><code>{string}</code> - current <code>$location.hashSearch</code></li></ul>

<p>The custom <code>redirectTo</code> function is expected to return a string which will be used
to update <code>$location.hash</code>.</p></li>
</ul></li>
</ul>
</div>
</li>
</ul>
<h2>Properties</h2>
<ul class="properties"><li><h3>current</h3>
<div class="current"><p>Reference to the current route definition.</p></div>
</li>
<li><h3>routes</h3>
<div class="routes"><p>Array of all configured routes.</p></div>
</li>
</ul>
<h2>Example</h2>
<div class="example"><p>This example shows how changing the URL hash causes the <tt>$route</tt>
to match a route against the URL, and the <tt>[[ng:include]]</tt> pulls in the partial.
Try changing the URL in the input box to see changes.</p><doc:example>
   <pre class="doc-source">
     &lt;script&gt;
       angular.service('myApp', function($route) {
         $route.when('/Book/:bookId', {template:'rsrc/book.html', controller:BookCntl});
         $route.when('/Book/:bookId/ch/:chapterId', {template:'rsrc/chapter.html', controller:ChapterCntl});
         $route.onChange(function() {
           $route.current.scope.params = $route.current.params;
         });
       }, {$inject: ['$route']});

       function BookCntl() {
         this.name = "BookCntl";
       }

       function ChapterCntl() {
         this.name = "ChapterCntl";
       }
     &lt;/script&gt;

     Chose:
     &lt;a href="#/Book/Moby"&gt;Moby&lt;/a&gt; |
     &lt;a href="#/Book/Moby/ch/1"&gt;Moby: Ch1&lt;/a&gt; |
     &lt;a href="#/Book/Gatsby"&gt;Gatsby&lt;/a&gt; |
     &lt;a href="#/Book/Gatsby/ch/4?key=value"&gt;Gatsby: Ch4&lt;/a&gt;&lt;br/&gt;
     &lt;input type="text" name="$location.hashPath" size="80" /&gt;
     &lt;pre&gt;$location={{$location}}&lt;/pre&gt;
     &lt;pre&gt;$route.current.template={{$route.current.template}}&lt;/pre&gt;
     &lt;pre&gt;$route.current.params={{$route.current.params}}&lt;/pre&gt;
     &lt;pre&gt;$route.current.scope.name={{$route.current.scope.name}}&lt;/pre&gt;
     &lt;hr/&gt;
     &lt;ng:include src="$route.current.template" scope="$route.current.scope"/&gt;
   </pre>
   <pre class="doc-scenario">
   </pre>
 </doc:example></div>
</div>