knowhow-server/public/js/lib/angular-1.2.9/docs/partials/tutorial/step_04.html

A personal workflow engine that can manage and use any network connected host

<a href="http://github.com/angular/angular.js/edit/master/docs/content/tutorial/step_04.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><div class="tutorial-page tutorial-4-two-way-data-binding-page"><ul doc-tutorial-nav="4"></ul>


<p>In this step, you will add a feature to let your users control the order of the items in the phone
list. The dynamic ordering is implemented by creating a new model property, wiring it together with
the repeater, and letting the data binding magic do the rest of the work.</p>
<div doc-tutorial-reset="4">
</div>


<p>You should see that in addition to the search box, the app displays a drop down menu that allows
users to control the order in which the phones are listed.</p>
<p>The most important differences between Steps 3 and 4 are listed below. You can see the full diff on
<a href="https://github.com/angular/angular-phonecat/compare/step-3...step-4">GitHub</a>:</p>
<h3 id="template">Template</h3>
<p><strong><code>app/index.html</code>:</strong>
<pre class="prettyprint linenums">
  Search: &lt;input ng-model="query"&gt;
  Sort by:
  &lt;select ng-model="orderProp"&gt;
    &lt;option value="name"&gt;Alphabetical&lt;/option&gt;
    &lt;option value="age"&gt;Newest&lt;/option&gt;
  &lt;/select&gt;


  &lt;ul class="phones"&gt;
    &lt;li ng-repeat="phone in phones | filter:query | orderBy:orderProp"&gt;
      {{phone.name}}
      &lt;p&gt;{{phone.snippet}}&lt;/p&gt;
    &lt;/li&gt;
  &lt;/ul&gt;
</pre>
<p>We made the following changes to the <code>index.html</code> template:</p>
<ul>
<li>First, we added a <code>&lt;select&gt;</code> html element named <code>orderProp</code>, so that our users can pick from the
two provided sorting options.</li>
</ul>
<p><img class="diagram" src="img/tutorial/tutorial_04.png"></p>
<ul>
<li>We then chained the <code>filter</code> filter with <a href="api/ng.filter:orderBy"><code><code>orderBy</code></code></a>
filter to further process the input into the repeater. <code>orderBy</code> is a filter that takes an input
array, copies it and reorders the copy which is then returned.</li>
</ul>
<p>Angular creates a two way data-binding between the select element and the <code>orderProp</code> model.
<code>orderProp</code> is then used as the input for the <code>orderBy</code> filter.</p>
<p>As we discussed in the section about data-binding and the repeater in step 3, whenever the model
changes (for example because a user changes the order with the select drop down menu), Angular&#39;s
data-binding will cause the view to automatically update. No bloated DOM manipulation code is
necessary!</p>
<h3 id="controller">Controller</h3>
<p><strong><code>app/js/controllers.js</code>:</strong>
<pre class="prettyprint linenums">
var phonecatApp = angular.module('phonecatApp', []);

phonecatApp.controller('PhoneListCtrl', function ($scope) {
  $scope.phones = [
    {'name': 'Nexus S',
     'snippet': 'Fast just got faster with Nexus S.',
     'age': 1},
    {'name': 'Motorola XOOM™ with Wi-Fi',
     'snippet': 'The Next, Next Generation tablet.',
     'age': 2},
    {'name': 'MOTOROLA XOOM™',
     'snippet': 'The Next, Next Generation tablet.',
     'age': 3}
  ];

  $scope.orderProp = 'age';
});
</pre>
<ul>
<li><p>We modified the <code>phones</code> model - the array of phones - and added an <code>age</code> property to each phone
record. This property is used to order phones by age.</p>
</li>
<li><p>We added a line to the controller that sets the default value of <code>orderProp</code> to <code>age</code>. If we had
not set a default value here, the <code>orderBy</code> filter would remain uninitialized until our 
user picked an option from the drop down menu.</p>
<p>This is a good time to talk about two-way data-binding. Notice that when the app is loaded in the
browser, &quot;Newest&quot; is selected in the drop down menu. This is because we set <code>orderProp</code> to <code>&#39;age&#39;</code>
in the controller. So the binding works in the direction from our model to the UI. Now if you
select &quot;Alphabetically&quot; in the drop down menu, the model will be updated as well and the phones
will be reordered. That is the data-binding doing its job in the opposite direction — from the UI
to the model.</p>
</li>
</ul>
<h3 id="test">Test</h3>
<p>The changes we made should be verified with both a unit test and an end-to-end test. Let&#39;s look at
the unit test first.</p>
<p><strong><code>test/unit/controllersSpec.js</code>:</strong>
<pre class="prettyprint linenums">
describe('PhoneCat controllers', function() {

  describe('PhoneListCtrl', function(){
    var scope, ctrl;

    beforeEach(module('phonecatApp'));
    
    beforeEach(inject(function($controller) {
      scope = {};
      ctrl = $controller('PhoneListCtrl', {$scope:scope});
    }));

    it('should create "phones" model with 3 phones', function() {
      expect(scope.phones.length).toBe(3);
    });


    it('should set the default value of orderProp model', function() {
      expect(scope.orderProp).toBe('age');
    });
  });
});
</pre>
<p>The unit test now verifies that the default ordering property is set.</p>
<p>We used Jasmine&#39;s API to extract the controller construction into a <code>beforeEach</code> block, which is
shared by all tests in the parent <code>describe</code> block.</p>
<p>You should now see the following output in the Karma tab:</p>
<pre><code>    Chrome 22.0: Executed 2 of 2 SUCCESS (0.021 secs / 0.001 secs)</code></pre>
<p>Let&#39;s turn our attention to the end-to-end test.</p>
<p><strong><code>test/e2e/scenarios.js</code>:</strong>
<pre class="prettyprint linenums">
...
    it('should be possible to control phone order via the drop down select box',
        function() {
      //let's narrow the dataset to make the test assertions shorter
      input('query').enter('tablet');

      expect(repeater('.phones li', 'Phone List').column('phone.name')).
          toEqual(["Motorola XOOM\u2122 with Wi-Fi",
                   "MOTOROLA XOOM\u2122"]);

      select('orderProp').option('Alphabetical');

      expect(repeater('.phones li', 'Phone List').column('phone.name')).
          toEqual(["MOTOROLA XOOM\u2122",
                   "Motorola XOOM\u2122 with Wi-Fi"]);
    });
...
</pre>
<p>The end-to-end test verifies that the ordering mechanism of the select box is working correctly.</p>
<p>You can now rerun <code>./scripts/e2e-test.sh</code> or refresh the browser tab with the end-to-end test
<code>runner.html</code> to see the tests run, or you can see them running on <a href="http://angular.github.com/angular-phonecat/step-4/test/e2e/runner.html">Angular&#39;s server</a>.</p>
<h2 id="experiments">Experiments</h2>
<ul>
<li><p>In the <code>PhoneListCtrl</code> controller, remove the statement that sets the <code>orderProp</code> value and
you&#39;ll see that Angular will temporarily add a new &quot;unknown&quot; option to the drop-down list and the
ordering will default to unordered/natural order.</p>
</li>
<li><p>Add an <code>{{orderProp}}</code> binding into the <code>index.html</code> template to display its current value as
text.</p>
</li>
<li><p>Reverse the sort order by adding a <code>-</code> symbol before the sorting value: <code>&lt;option value=&quot;-age&quot;&gt;Oldest&lt;/option&gt;</code></p>
</li>
</ul>
<h2 id="summary">Summary</h2>
<p>Now that you have added list sorting and tested the app, go to <a href="tutorial/step_05">step 5</a> to learn
about Angular services and how Angular uses dependency injection.</p>
<ul doc-tutorial-nav="4"></ul></div></div>