159 lines
7.3 KiB
HTML
Executable file
159 lines
7.3 KiB
HTML
Executable file
<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>Template</h2>
|
|
<p><strong><code>app/index.html</code>:</strong>
|
|
<pre class="prettyprint linenums">
|
|
Search: <input ng-model="query">
|
|
Sort by:
|
|
<select ng-model="orderProp">
|
|
<option value="name">Alphabetical</option>
|
|
<option value="age">Newest</option>
|
|
</select>
|
|
|
|
|
|
<ul class="phones">
|
|
<li ng-repeat="phone in phones | filter:query | orderBy:orderProp">
|
|
{{phone.name}}
|
|
<p>{{phone.snippet}}</p>
|
|
</li>
|
|
</ul>
|
|
</pre>
|
|
<p>We made the following changes to the <code>index.html</code> template:</p>
|
|
<ul>
|
|
<li><p>First, we added a <code><select></code> html element named <code>orderProp</code>, so that our users can pick from the
|
|
two provided sorting options.</p>
|
|
<pre><code><img class="diagram" src="img/tutorial/tutorial_04.png"></code></pre>
|
|
</li>
|
|
<li><p>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.</p>
|
|
</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's
|
|
data-binding will cause the view to automatically update. No bloated DOM manipulation code is
|
|
necessary!</p>
|
|
<h2>Controller</h2>
|
|
<p><strong><code>app/js/controllers.js</code>:</strong>
|
|
<pre class="prettyprint linenums">
|
|
function PhoneListCtrl($scope) {
|
|
$scope.phones = [
|
|
{"name": "Nexus S",
|
|
"snippet": "Fast just got faster with Nexus S.",
|
|
"age": 0},
|
|
{"name": "Motorola XOOM™ with Wi-Fi",
|
|
"snippet": "The Next, Next Generation tablet.",
|
|
"age": 1},
|
|
{"name": "MOTOROLA XOOM™",
|
|
"snippet": "The Next, Next Generation tablet.",
|
|
"age": 2}
|
|
];
|
|
|
|
$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 the default value here, the model would stay uninitialized until our user would pick 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, "Newest" is selected in the drop down menu. This is because we set <code>orderProp</code> to <code>'age'</code>
|
|
in the controller. So the binding works in the direction from our model to the UI. Now if you
|
|
select "Alphabetically" 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>
|
|
<h2>Test</h3>
|
|
<p>The changes we made should be verified with both a unit test and an end-to-end test. Let'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(function() {
|
|
scope = {},
|
|
ctrl = new PhoneListCtrl(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'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'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's server</a>.</p>
|
|
<h2>Experiments</h1>
|
|
<ul>
|
|
<li><p>In the <code>PhoneListCtrl</code> controller, remove the statement that sets the <code>orderProp</code> value and
|
|
you'll see that Angular will temporarily add a new "unknown" 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><option value="-age">Oldest</option></code></p>
|
|
</li>
|
|
</ul>
|
|
<h1>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>
|