From 3751f172b3986604853700a1475a7ad81b42a9b1 Mon Sep 17 00:00:00 2001
From: Igor Minar
Date: Tue, 10 May 2011 17:45:42 -0700
Subject: add new batch of tutorial docs and images

---
 docs/content/tutorial/step_04.ngdoc | 97 +++++++++++++++++++++++++++++++------
 1 file changed, 82 insertions(+), 15 deletions(-)

(limited to 'docs/content/tutorial/step_04.ngdoc')

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>
+
+
+
-- 
cgit v1.2.3