diff options
Diffstat (limited to 'docs/content/tutorial/step_04.ngdoc')
| -rwxr-xr-x | docs/content/tutorial/step_04.ngdoc | 97 |
1 files changed, 82 insertions, 15 deletions
diff --git a/docs/content/tutorial/step_04.ngdoc b/docs/content/tutorial/step_04.ngdoc index 2ca34929..9848c821 100755 --- a/docs/content/tutorial/step_04.ngdoc +++ b/docs/content/tutorial/step_04.ngdoc @@ -1,4 +1,4 @@ -@ngdoc overview +@ngdoc overview @name Tutorial: Step 4 @description <table id="tutorial_nav"> @@ -12,35 +12,48 @@ Diff}</td> </tr> </table> + 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. +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. + + 1. Reset your workspace to Step 4 using: - git checkout --force step-4 + + git checkout -f step-4 + or + ./goto_step.sh 4 + 2. Refresh your browser or check the app out on {@link -http://angular.github.com/angular-phonecat/step-4/app angular's server}. You should see that in +http://angular.github.com/angular-phonecat/step-4/app angular's server}. + +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. + The most important changes are listed below. You can see the full diff on {@link https://github.com/angular/angular-phonecat/compare/step-3...step-4 GitHub}: + + ## Template + __`app/index.html`:__ <pre> ... - <ul class="predicates"> + <ul class="controls"> <li> Search: <input type="text" name="query"/> </li> @@ -53,6 +66,7 @@ __`app/index.html`:__ </li> </ul> + <ul class="phones"> <li ng:repeat="phone in phones.$filter(query).$orderBy(orderProp)"> {{phone.name}} @@ -62,31 +76,44 @@ __`app/index.html`:__ ... </pre> + In the `index.html` template we made the following changes: + * First, we added a `<select>` html element named `orderProp`, so that our users can pick from the two provided sorting options. + + <img src="img/tutorial/tutorial_04-06_final.png"> + + * We then chained the `$filter` method with {@link angular.Array.orderBy `$orderBy`} method to further process the input into the repeater. `$orderBy` is a utility method similar to {@link angular.Array.filter `$filter`}, but instead of filtering an array, it reorders it. + Angular creates a two way data-binding between the select element and the `orderProp` model. `orderProp` is then used as the input for the `$orderBy` method. + 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! +necessary! + + + ## Controller + __`app/js/controller.js`:__ <pre> /* App Controllers */ + function PhoneListCtrl() { this.phones = [{"name": "Nexus S", "snippet": "Fast just got faster with Nexus S.", @@ -98,48 +125,63 @@ function PhoneListCtrl() { "snippet": "The Next, Next Generation tablet.", "age": 2}]; + this.orderProp = 'age'; } </pre> + * We modified the `phones` model - the array of phones - and added an `age` property to each phone record. This property is used to order phones by age. + * We added a line to the controller that sets the default value of `orderProp` to `age`. If we had not set the default value here, angular would have used the value of the first `<option>` element (`'name'`) when it initialized the data model. - 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 `orderProp` to - `'age'` 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. + + 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 `orderProp` to `'age'` +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. + + + ## Test + 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. + __`test/unit/controllerSpec.js`:__ <pre> describe('PhoneCat controllers', function() { + describe('PhoneListCtrl', function(){ var scope, $browser, ctrl; + beforeEach(function() { ctrl = new PhoneListCtrl(); }); + + it('should create "phones" model with 3 phones', function() { expect(ctrl.phones.length).toBe(3); }); + + it('should set the default value of orderProp model', function() { expect(ctrl.orderProp).toBe('age'); }); @@ -148,35 +190,48 @@ describe('PhoneCat controllers', function() { </pre> + + The unit test now verifies that the default ordering property is set. + We used Jasmine's API to extract the controller construction into a `beforeEach` block, which is shared by all tests in the nearest `describe` block. + To run the unit tests, once again execute the `./scripts/test.sh` script and you should see the following output. + Chrome: Runner reset. .. Total 2 tests (Passed: 2; Fails: 0; Errors: 0) (3.00 ms) Chrome 11.0.696.57 Mac OS: Run 2 tests (Passed: 2; Fails: 0; Errors 0) (3.00 ms) + + Let's turn our attention to the end-to-end test. + __`test/e2e/scenarios.js`:__ <pre> ... it('should be possible to control phone order via the drop down select box', function() { - input('query').enter('tablet'); //let's narrow the dataset to make the test assertions - shorter + + + //let's narrow the dataset to make the test assertions shorter + input('query').enter('tablet'); + expect(repeater('.phones li', 'Phone List').column('a')). toEqual(["Motorola XOOM\u2122 with Wi-Fi", "MOTOROLA XOOM\u2122"]); + select('orderProp').option('alphabetical'); + expect(repeater('.phones li', 'Phone List').column('a')). toEqual(["MOTOROLA XOOM\u2122", "Motorola XOOM\u2122 with Wi-Fi"]); @@ -184,28 +239,37 @@ __`test/e2e/scenarios.js`:__ ... </pre> + The end-to-end test verifies that the ordering mechanism of the select box is working correctly. + 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 {@link http://angular.github.com/angular-phonecat/step-4/test/e2e/runner.html angular's server}. + # Experiments + * In the `PhoneListCtrl` controller, remove the statement that sets the `orderProp` value and you'll see that the ordering as well as the current selection in the dropdown menu will default to "Alphabetical". + * Add an `{{orderProp}}` binding into the `index.html` template to display its current value as text. + # Summary + Now that you have added list sorting and tested the app, go to step 5 to learn about angular services and how angular uses dependency injection. + + <table id="tutorial_nav"> <tr> <td id="previous_step">{@link tutorial.step_03 Previous}</td> @@ -216,3 +280,6 @@ Diff}</td> <td id="next_step">{@link tutorial.step_05 Next}</td> </tr> </table> + + + |