From 11e9572b952e49b01035e956c412d6095533031a Mon Sep 17 00:00:00 2001
From: Misko Hevery
Date: Fri, 29 Apr 2011 15:18:27 -0700
Subject: Move documentation under individual headings

---
 docs/content/tutorial/step_04.ngdoc | 161 ++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100755 docs/content/tutorial/step_04.ngdoc

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

diff --git a/docs/content/tutorial/step_04.ngdoc b/docs/content/tutorial/step_04.ngdoc
new file mode 100755
index 00000000..0589ba75
--- /dev/null
+++ b/docs/content/tutorial/step_04.ngdoc
@@ -0,0 +1,161 @@
+@workInProgress
+@ngdoc overview
+@name Tutorial: Step 4
+@description
+<table id="tutorial_nav">
+<tr>
+<td id="previous_step">{@link tutorial.step_03 Previous}</td>
+<td id="step_result">{@link  http://angular.github.com/angular-phonecat/step-4/app Example}</td>
+<td id="tut_home">{@link tutorial Tutorial Home}</td>
+<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-3...step-4 Code
+Diff}</td>
+<td id="next_step">{@link tutorial.step_05 Next}</td>
+</tr>
+</table>
+
+In this step, we add a feature that lets our users choose which way to order the phone list.
+
+__`app/index.html`:__
+<pre>
+...
+  <ul class="predicates">
+    <li>
+      Search: <input type="text" name="query"/>
+    </li>
+    <li>
+      Sort by:
+      <select name="orderProp">
+        <option value="name">Alphabetical</option>
+        <option value="age">Newest</option>
+      </select>
+    </li>
+  </ul>
+
+  <ul class="phones">
+    <li ng:repeat="phone in phones.$filter(query).$orderBy(orderProp)">
+      {{phone.name}}
+      <p>{{phone.snippet}}</p>
+    </li>
+  </ul>
+...
+</pre>
+
+__`app/js/controller.js`:__
+<pre>
+/* App Controllers */
+
+function PhoneListCtrl() {
+  this.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}];
+
+  this.orderProp = 'age';
+}
+</pre>
+
+__`test/unit/controllerSpec.js`:__
+<pre>
+/* jasmine specs for controllers go here */
+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');
+    });
+  });
+});
+</pre>
+
+__`test/e2e/scenarios.js`:__
+<pre>
+/* jasmine-like end2end tests go here */
+describe('PhoneCat App', function() {
+
+  describe('Phone list view', function() {
+
+    beforeEach(function() {
+      browser().navigateTo('../../app/index.html');
+    });
+
+
+    it('should filter the phone list as user types into the search box', function() {
+      expect(repeater('.phones li').count()).toBe(3);
+
+      input('query').enter('nexus');
+      expect(repeater('.phones li').count()).toBe(1);
+
+      input('query').enter('motorola');
+      expect(repeater('.phones li').count()).toBe(2);
+    });
+
+
+    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
+
+      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"]);
+    });
+  });
+});
+</pre>
+
+## Discussion:
+
+To provide dynamic ordering, we employ another one of angular's "array type augmenters" and let
+the data binding do the rest of the work for us:
+
+* First, we provide a `<select>` element named `orderProp` for our users so they can choose to
+sort the phone list either alphabetically or by the age of the phone.  We added the `age` property
+to each phone record so we can sort by that field.
+
+* Like {@link angular.Array.filter $filter}, {@link angular.Array.orderBy $orderBy} is a built-in
+method available on array objects in angular expressions.  In our UI template, we set up a select
+box that lets the user set the `orderProp` model variable to one of the string constants: `age` or
+`name`.
+
+* In our controller, we added a line to set the default value of `orderProp` to `age`.  If we
+don't override the default value, angular uses the value of the first `<option>` element when it
+initializes the data model.
+
+* Our unit test now verifies that our default ordering property is set.
+
+* We added an end-to-end test to verify that our select box ordering mechanism works properly.
+
+* Once again we added a little more CSS to improve the View.
+
+<table id="tutorial_nav">
+<tr>
+<td id="previous_step">{@link tutorial.step_03 Previous}</td>
+<td id="step_result">{@link  http://angular.github.com/angular-phonecat/step-4/app Example}</td>
+<td id="tut_home">{@link tutorial Tutorial Home}</td>
+<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-3...step-4 Code
+Diff}</td>
+<td id="next_step">{@link tutorial.step_05 Next}</td>
+</tr>
+</table>
-- 
cgit v1.2.3