EVOLUTION-MANAGER
Edit File: step_07.html
<a href='https://github.com/angular/angular.js/edit/v1.3.x/docs/content/tutorial/step_07.ngdoc?message=docs(tutorial%2F7 - Routing & Multiple Views)%3A%20describe%20your%20change...' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit"> </i>Improve this Doc</a> <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, using an Angular module called 'ngRoute'.</p> <ul> <li>When you now navigate to <code>app/index.html</code>, you are redirected to <code>app/index.html/#/phones</code> and the phone list appears in the browser.</li> <li>When you click on a phone link the url changes to one specific to that phone and the stub of a phone detail page is displayed.</li> </ul> <div doc-tutorial-reset="7"></div> <h2 id="dependencies">Dependencies</h2> <p>The routing functionality added by this step is provided by angular in the <code>ngRoute</code> module, which is distributed separately from the core Angular framework.</p> <p>We are using <a href="http://bower.io">Bower</a> to install client side dependencies. This step updates the <code>bower.json</code> configuration file to include the new dependency:</p> <pre><code class="lang-json">{ "name": "angular-phonecat", "description": "A starter project for AngularJS", "version": "0.0.0", "homepage": "https://github.com/angular/angular-phonecat", "license": "MIT", "private": true, "dependencies": { "angular": "~1.3.0", "angular-mocks": "~1.3.0", "jquery": "2.1.1", "bootstrap": "~3.1.1", "angular-route": "~1.3.0" } } </code></pre> <p>The new dependency <code>"angular-route": "~1.3.0"</code> tells bower to install a version of the angular-route component that is compatible with version 1.3.x. We must tell bower to download and install this dependency.</p> <p>If you have bower installed globally then you can run <code>bower install</code> but for this project we have preconfigured npm to run bower install for us:</p> <pre><code>npm install </code></pre> <h2 id="multiple-views-routing-and-layout-template">Multiple Views, Routing and Layout Template</h2> <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/ngRoute/provider/$routeProvider">$routeProvider</a>, which is the provider of the <a href="api/ngRoute/service/$route">$route service</a>. 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 id="a-note-about-di-injector-and-providers">A Note About DI, Injector and Providers</h3> <p>As you <a href="tutorial/step_05">noticed</a>, <a href="guide/di">dependency injection</a> (DI) is at the core of AngularJS, so it's important for you to understand a thing or two about how it works.</p> <p>When the application bootstraps, Angular creates an injector that will be used to find and inject all of the services that are required by your app. The injector itself doesn't know anything about what <code>$http</code> or <code>$route</code> services do, in fact it doesn't even know about the existence of these services unless it is configured with proper module definitions.</p> <p>The injector only carries out the following steps :</p> <ul> <li>load the module definition(s) that you specify in your app</li> <li>register all Providers defined in these module definitions</li> <li>when asked to do so, inject a specified function and any necessary dependencies (services) that it lazily instantiates via their Providers.</li> </ul> <p>Providers are objects that provide (create) instances of services and expose configuration APIs that can be used to control the creation and runtime behavior of a service. In case of the <code>$route</code> service, the <code>$routeProvider</code> exposes APIs that allow you to define routes for your application.</p> <div class="alert alert-warning"> <strong>Note:</strong> Providers can only be injected into <code>config</code> functions. Thus you could not inject <code>$routeProvider</code> into <code>PhoneListCtrl</code>. </div> <p>Angular modules solve the problem of removing global state from the application and provide a way of configuring the injector. As opposed to AMD or require.js modules, Angular modules don't try to solve the problem of script load ordering or lazy script fetching. These goals are totally independent and both module systems can live side by side and fulfill their goals.</p> <p>To deepen your understanding of DI on Angular, see <a href="https://github.com/angular/angular.js/wiki/Understanding-Dependency-Injection">Understanding Dependency Injection</a>.</p> <h2 id="template">Template</h2> <p>The <code>$route</code> service is usually used in conjunction with the <a href="api/ngRoute/directive/ngView">ngView</a> directive. The role of the <code>ngView</code> directive is to include the view template for the current route into the layout template. This makes it a perfect fit for our <code>index.html</code> template.</p> <div class="alert alert-info"> <strong>Note:</strong> Starting with AngularJS version 1.2, <code>ngRoute</code> is in its own module and must be loaded by loading the additional <code>angular-route.js</code> file, which we download via Bower above. </div> <p><strong><code>app/index.html</code>:</strong></p> <pre><code class="lang-html"><!doctype html> <html lang="en" ng-app="phonecatApp"> <head> ... <script src="bower_components/angular/angular.js"></script> <script src="bower_components/angular-route/angular-route.js"></script> <script src="js/app.js"></script> <script src="js/controllers.js"></script> </head> <body> <div ng-view></div> </body> </html> </code></pre> <p>We have added two new <code><script></code> tags in our index file to load up extra JavaScript files into our application:</p> <ul> <li><code>angular-route.js</code> : defines the Angular <code>ngRoute</code> module, which provides us with routing.</li> <li><code>app.js</code> : this file now holds the root module of our application.</li> </ul> <p>Note that we removed most of the code in the <code>index.html</code> template and replaced it with a single line containing a div with the <code>ng-view</code> attribute. 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> <pre><code class="lang-html"><div class="container-fluid"> <div class="row"> <div class="col-md-2"> <!--Sidebar content--> Search: <input ng-model="query"> Sort by: <select ng-model="orderProp"> <option value="name">Alphabetical</option> <option value="age">Newest</option> </select> </div> <div class="col-md-10"> <!--Body content--> <ul class="phones"> <li ng-repeat="phone in phones | filter:query | orderBy:orderProp" class="thumbnail"> <a href="#/phones/{{phone.id}}" class="thumb"><img ng-src="{{phone.imageUrl}}"></a> <a href="#/phones/{{phone.id}}">{{phone.name}}</a> <p>{{phone.snippet}}</p> </li> </ul> </div> </div> </div> </code></pre> <div style="display:none"> TODO! <img class="diagram" src="img/tutorial/tutorial_07_final.png"> </div> <p>We also added a placeholder template for the phone details view:</p> <p><strong><code>app/partials/phone-detail.html</code>:</strong></p> <pre><code class="lang-html">TBD: detail view for <span>{{phoneId}}</span> </code></pre> <p>Note how we are using the <code>phoneId</code> expression which will be defined in the <code>PhoneDetailCtrl</code> controller.</p> <h2 id="the-app-module">The App Module</h2> <p>To improve the organization of the app, we are making use of Angular's <code>ngRoute</code> module and we've moved the controllers into their own module <code>phonecatControllers</code> (as shown below).</p> <p>We added <code>angular-route.js</code> to <code>index.html</code> and created a new <code>phonecatControllers</code> module in <code>controllers.js</code>. That's not all we need to do to be able to use their code, however. We also have to add the modules as dependencies of our app. By listing these two modules as dependencies of <code>phonecatApp</code>, we can use the directives and services they provide.</p> <p><strong><code>app/js/app.js</code>:</strong></p> <pre><code class="lang-js">var phonecatApp = angular.module('phonecatApp', [ 'ngRoute', 'phonecatControllers' ]); ... </code></pre> <p>Notice the second argument passed to <code>angular.module</code>, <code>['ngRoute', 'phonecatControllers']</code>. This array lists the modules that <code>phonecatApp</code> depends on.</p> <pre><code class="lang-js">... phonecatApp.config(['$routeProvider', function($routeProvider) { $routeProvider. when('/phones', { templateUrl: 'partials/phone-list.html', controller: 'PhoneListCtrl' }). when('/phones/:phoneId', { templateUrl: 'partials/phone-detail.html', controller: 'PhoneDetailCtrl' }). otherwise({ redirectTo: '/phones' }); }]); </code></pre> <p>Using the <code>phonecatApp.config()</code> method, we request the <code>$routeProvider</code> to be injected into our config function and use the <a href="api/ngRoute/provider/$routeProvider#when"><code>$routeProvider.when()</code></a> method to define our routes.</p> <p>Our application routes are defined as follows:</p> <ul> <li><p><code>when('/phones')</code>: 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><code>when('/phones/:phoneId')</code>: The phone details view will be shown when the URL hash fragment matches '/phones/: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> <li><p><code>otherwise({redirectTo: '/phones'})</code>: triggers a redirection to <code>/phones</code> when the browser address doesn't match either of our routes.</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>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 <a href="api/ngRoute/service/$routeParams"><code>$routeParams</code></a> object.</p> <h2 id="controllers">Controllers</h2> <p><strong><code>app/js/controllers.js</code>:</strong></p> <pre><code class="lang-js">var phonecatControllers = angular.module('phonecatControllers', []); phonecatControllers.controller('PhoneListCtrl', ['$scope', '$http', function ($scope, $http) { $http.get('phones/phones.json').success(function(data) { $scope.phones = data; }); $scope.orderProp = 'age'; }]); phonecatControllers.controller('PhoneDetailCtrl', ['$scope', '$routeParams', function($scope, $routeParams) { $scope.phoneId = $routeParams.phoneId; }]); </code></pre> <p>Again, note that we created a new module called <code>phonecatControllers</code>. For small AngularJS applications, it's common to create just one module for all of your controllers if there are just a few. As your application grows it is quite common to refactor your code into additional modules. For larger apps, you will probably want to create separate modules for each major feature of your app.</p> <p>Because our example app is relatively small, we'll just add all of our controllers to the <code>phonecatControllers</code> module.</p> <h2 id="test">Test</h2> <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> <pre><code class="lang-js">... it('should redirect index.html to index.html#/phones', function() { browser.get('app/index.html'); browser.getLocationAbsUrl().then(function(url) { expect(url.split('#')[1]).toBe('/phones'); }); }); describe('Phone list view', function() { beforeEach(function() { browser.get('app/index.html#/phones'); }); ... describe('Phone detail view', function() { beforeEach(function() { browser.get('app/index.html#/phones/nexus-s'); }); it('should display placeholder page with phoneId', function() { expect(element(by.binding('phoneId')).getText()).toBe('nexus-s'); }); }); </code></pre> <p>You can now rerun <code>npm run protractor</code> to see the tests run.</p> <h1 id="experiments">Experiments</h1> <ul> <li>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><div ng-view></code> element. If you add the same binding into the <code>phone-list.html</code> template, the binding will work as expected.</li> </ul> <div style="display: none"> * 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><p>hero = {{hero}}</p></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. </div> <h1 id="summary">Summary</h1> <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>