step_07.html

<h1>Tutorial: 7 - Routing &amp; Multiple Views</h1>
<div class="tutorial-7-routing-multiple-views"><ul doc:tutorial-nav="7"></ul>

<p>In this step, you will learn how to create a layout template and how to build an app that has
multiple views by adding routing.</p><doc:tutorial-instructions step="7"></doc:tutorial-instructions><p>Note that you are redirected to <code>app/index.html#/phones</code> and the same phone list appears in the
browser. When you click on a phone link the stub of a phone detail page is displayed.</p>

<p>The most important changes are listed below. You can see the full diff on <a href="https://github.com/angular/angular-phonecat/compare/step-6...step-7">GitHub</a>:</p>

<h3>Multiple Views, Routing and Layout Template</h3>

<p>Our app is slowly growing and becoming more complex. Before step 7, the app provided our users with
a single view (the list of all phones), and all of the template code was located in the
<code>index.html</code> file. The next step in building the app is to add a view that will show detailed
information about each of the devices in our list.</p>

<p>To add the detailed view, we could expand the <code>index.html</code> file to contain template code for both
views, but that would get messy very quickly. Instead, we are going to turn the <code>index.html</code>
template into what we call a "layout template". This is a template that is common for all views in
our application. Other "partial templates" are then included into this layout template depending on
the current "route" — the view that is currently displayed to the user.</p>

<p>Application routes in angular are declared via the <a href="#!/api/angular.service.$route"><code>$route</code></a>
service. This service makes it easy to wire together controllers, view templates, and the current
URL location in the browser. Using this feature we can implement <a href="http://en.wikipedia.org/wiki/Deep_linking">deep linking</a>, which lets us utilize the browser's
history (back and forward navigation) and bookmarks.</p>

<h3>Controllers</h3>

<p><strong><code>app/js/controller.js</code>:</strong></p><div ng:non-bindable><pre class="brush: js;">
function PhoneCatCtrl($route) {
  var self = this;

  $route.when('/phones',
      {template: 'partials/phone-list.html',   controller: PhoneListCtrl});
  $route.when('/phones/:phoneId',
      {template: 'partials/phone-detail.html', controller: PhoneDetailCtrl});
  $route.otherwise({redirectTo: '/phones'});

  $route.onChange(function() {
    self.params = $route.current.params;
  });

  $route.parent(this);
}

//PhoneCatCtrl.$inject = ['$route'];
...
</pre></div><p>We created a new controller called <code>PhoneCatCtrl</code>. We declared its dependency on the <code>$route</code>
service and used this service to declare that our application consists of two different views:</p>

<ul>
<li><p>The phone list view will be shown when the URL hash fragment is <code>/phones</code>. To construct this
view, angular will use the <code>phone-list.html</code> template and the <code>PhoneListCtrl</code> controller.</p></li>
<li><p>The phone details view will be shown when the URL hash fragment matches '/phone/:phoneId', where
<code>:phoneId</code> is a variable part of the URL. To construct the phone details view, angular will use the
<code>phone-detail.html</code> template and the <code>PhoneDetailCtrl</code> controller.</p></li>
</ul>

<p>We reused the <code>PhoneListCtrl</code> controller that we constructed in previous steps and we added a new,
empty <code>PhoneDetailCtrl</code> controller to the <code>app/js/controllers.js</code> file for the phone details view.</p>

<p>The statement <code>$route.otherwise({redirectTo: '/phones'})</code> triggers a redirection to <code>/phones</code> when
the browser address doesn't match either of our routes.</p>

<p>Thanks to the <code>$route.parent(this);</code> statement and <code>ng:controller="PhoneCatCtrl"</code> declaration in
the <code>index.html</code> template, the <code>PhoneCatCtrl</code> controller has a special role in our app. It is the
"root" controller and the parent controller for the other two sub-controllers (<code>PhoneListCtrl</code> and
<code>PhoneDetailCtrl</code>). The sub-controllers inherit the model properties and behavior from the root
controller.</p>

<p>Note the use of the <code>:phoneId</code> parameter in the second route declaration. The <code>$route</code> service uses
the route declaration — <code>'/phones/:phoneId'</code> — as a template that is matched against the current
URL. All variables defined with the <code>:</code> notation are extracted into the <code>$route.current.params</code> map.</p>

<p>The <code>params</code> alias created in the <a href="#!/api/angular.service.$route"><code><code>$route.onChange</code></code></a> callback
allows us to use the <code>phoneId</code> property of this map in the <code>phone-details.html</code> template.</p>

<h3>Template</h3>

<p>The <code>$route</code> service is usually used in conjunction with the <a href="#!/api/angular.widget.ng:view"><code>ng:view</code></a> widget. The role of the <code>ng:view</code> widget is to include the view template for the current
route into the layout template, which makes it a perfect fit for our <code>index.html</code> template.</p>

<p><strong><code>app/index.html</code>:</strong></p><div ng:non-bindable><pre class="brush: js; html-script: true;">
...
&lt;body ng:controller="PhoneCatCtrl"&gt;

  &lt;ng:view&gt;&lt;/ng:view&gt;

  &lt;script src="lib/angular/angular.js" ng:autobind&gt;&lt;/script&gt;
  &lt;script src="js/controllers.js"&gt;&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre></div><p>Note that we removed most of the code in the <code>index.html</code> template and replaced it with a single
line containing the <code>ng:view</code> tag. The code that we removed was placed into the <code>phone-list.html</code>
template:</p>

<p><strong><code>app/partials/phone-list.html</code>:</strong></p><div ng:non-bindable><pre class="brush: js; html-script: true;">
&lt;ul class="predicates"&gt;
  &lt;li&gt;
    Search: &lt;input type="text" name="query"/&gt;
  &lt;/li&gt;
  &lt;li&gt;
    Sort by:
    &lt;select name="orderProp"&gt;
      &lt;option value="name"&gt;Alphabetical&lt;/option&gt;
      &lt;option value="age"&gt;Newest&lt;/option&gt;
    &lt;/select&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;ul class="phones"&gt;
  &lt;li ng:repeat="phone in phones.$filter(query).$orderBy(orderProp)"&gt;
    &lt;a href="#/phones/{{phone.id}}"&gt;{{phone.name}}&lt;/a&gt;
    &lt;a href="#/phones/{{phone.id}}" class="thumb"&gt;&lt;img ng:src="{{phone.imageUrl}}"&gt;&lt;/a&gt;
    &lt;p&gt;{{phone.snippet}}&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;
</pre></div><p><img src="img/tutorial/tutorial_07_final.png"></p>

<p>We also added a placeholder template for the phone details view:</p>

<p><strong><code>app/partials/phone-detail.html</code>:</strong></p><div ng:non-bindable><pre class="brush: js;">
TBD: detail view for {{params.phoneId}}
</pre></div><p>Note how we are using <code>params</code> model defined in the <code>PhoneCatCtrl</code> controller.</p>

<h3>Test</h3>

<p>To automatically verify that everything is wired properly, we wrote end-to-end tests that navigate
to various URLs and verify that the correct view was rendered.</p><div ng:non-bindable><pre class="brush: js;">
...
  it('should redirect index.html to index.html#/phones', function() {
   browser().navigateTo('../../app/index.html');
   expect(browser().location().hash()).toBe('/phones');
  });
...

 describe('Phone detail view', function() {

   beforeEach(function() {
      browser().navigateTo('../../app/index.html#/phones/nexus-s');
   });


   it('should display placeholder page with phoneId', function() {
      expect(binding('params.phoneId')).toBe('nexus-s');
   });
 });
</pre></div><p>You can now refresh the browser tab with the end-to-end test runner to see the tests run, or you
can see them running on <a href="http://angular.github.com/angular-phonecat/step-7/test/e2e/runner.html">angular's server</a>.</p>

<h2>Experiments</h2>

<ul>
<li><p>Try to add an <code>{{orderProp}}</code> binding to <code>index.html</code>, and you'll see that nothing happens even
when you are in the phone list view. This is because the <code>orderProp</code> model is visible only in the
scope managed by <code>PhoneListCtrl</code>, which is associated with the <code>&lt;ng:view&gt;</code> element. If you add the
same binding into the <code>phone-list.html</code> template, the binding will work as expected.</p></li>
<li><p>In <code>PhoneCatCtrl</code>, create a new model called "<code>hero</code>" with <code>this.hero = 'Zoro'</code>. In
<code>PhoneListCtrl</code> let's shadow it with <code>this.hero = 'Batman'</code>, and in <code>PhoneDetailCtrl</code> we'll use
<code>this.hero = "Captain Proton"</code>. Then add the <code>&lt;p&gt;hero = {{hero}}&lt;/p&gt;</code> to all three of our templates
(<code>index.html</code>, <code>phone-list.html</code>, and <code>phone-detail.html</code>). Open the app and you'll see scope
inheritance and model property shadowing do some wonders.</p></li>
</ul>

<h2>Summary</h2>

<p>With the routing set up and the phone list view implemented, we're ready to go to <a href="#!/tutorial/step_08">step 8</a> to implement the phone details view.</p>

<ul doc:tutorial-nav="7"></ul></div>