new batch of tutorial docs

1 files changed, 219 insertions, 147 deletions

diff --git a/docs/content/tutorial/step_05.ngdoc b/docs/content/tutorial/step_05.ngdoc
index 8ec0fca4..0c8f0dde 100755
--- a/docs/content/tutorial/step_05.ngdoc
+++ b/docs/content/tutorial/step_05.ngdoc
@@ -1,147 +1,219 @@
-@workInProgress

-@ngdoc overview

-@name Tutorial: Step 5

-@description

-<table id="tutorial_nav">

-<tr>

- <td id="previous_step">{@link tutorial.step_04 Previous}</td>

- <td id="step_result">{@link  http://angular.github.com/angular-phonecat/step-5/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-4...step-5 Code

-Diff}</td>

- <td id="next_step">{@link tutorial.step_06 Next}</td>

-</tr>

-</table>

-

-In this step, the View template remains the same but the Model and Controller change.  We'll

-introduce the use of an angular {@link angular.service service}, which we will use to implement an

-`XMLHttpRequest` request to communicate with a server. Angular provides the built-in {@link

-angular.service.$xhr $xhr} service to make this easy.

-

-The addition of the `$xhr` service to our app gives us the opportunity to talk about {@link

-guide.di Dependency Injection} (DI).  The use of DI is another cornerstone of the angular

-philosophy. DI helps make your web apps well structured, loosely coupled, and ultimately easier to

-test.

-

-__`app/js/controllers.js:`__

-<pre>

-/* App Controllers */

-

-function PhoneListCtrl($xhr) {

-  var self = this;

-

-  $xhr('GET', 'phones/phones.json', function(code, response) {

-    self.phones = response;

-  });

-

-  self.orderProp = 'age';

-}

-

-//PhoneListCtrl.$inject = ['$xhr'];

-</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() {

-      scope = angular.scope();

-      $browser = scope.$service('$browser');

-

-      $browser.xhr.expectGET('phones/phones.json').respond([{name: 'Nexus S'},

-                                                            {name: 'Motorola DROID'}]);

-      ctrl = scope.$new(PhoneListCtrl);

-    });

-

-

-    it('should create "phones" model with 2 phones fetched from xhr', function() {

-      expect(ctrl.phones).toBeUndefined();

-      $browser.xhr.flush();

-

-      expect(ctrl.phones).toEqual([{name: 'Nexus S'},

-                                   {name: 'Motorola DROID'}]);

-    });

-

-

-    it('should set the default value of orderProp model', function() {

-      expect(ctrl.orderProp).toBe('age');

-    });

-  });

-});

-</pre>

-

-## Discussion:

-

-* __Services:__ {@link angular.service Services} are substitutable objects managed by angular's

-{@link guide.di DI subsystem}.  Angular services simplify some of the standard operations common

-to web apps.  Angular provides several built-in services (such as {@link angular.service.$xhr

-$xhr}). You can also create your own custom services.

-

-* __Dependency Injection:__ To use an angular service, you simply provide the name of the service

-as an argument to the controller's constructor function. The name of the argument is significant,

-because angular's {@link guide.di DI subsystem} recognizes the identity of a service by its name,

-and provides the name of the service to the controller during the controller's construction. The

-dependency injector also takes care of creating any transitive dependencies the service may have

-(services often depend upon other services).

-

-  Note: if you minify the javascript code for this controller, all function arguments will be

-  minified as well. This will result in the dependency injector not being able to identify

-  services correctly. To overcome this issue, just assign an array with service identifier strings

-  into the `$inject` property of the controller function.

-

-* __`$xhr`:__ We moved our data set out of the controller and into the file

-`app/phones/phones.json` (and added some more phones). We used the `$xhr` service to make a GET

-HTTP request to our web server, asking for `phone/phones.json` (the url is relative to our

-`index.html` file). The server responds with the contents of the json file, which serves as the

-source of our data. Keep in mind that the response might just as well have been dynamically

-generated by a sophisticated backend server. To our web server they both look the same, but using

-a real backend server to generate a response would make our tutorial unnecessarily complicated.

-

-    Notice that the $xhr service takes a callback as the last parameter. This callback is used to

-    process the response. In our case, we just assign the response to the current scope controlled

-    by the controller, as a model called `phones`. Have you realized that we didn't even have to

-    parse the response? Angular took care of that for us.

-

-* __Testing:__  The unit tests have been expanded. Because of the dependency injection business,

-we now need to create the controller the same way that angular does it behind the scenes. For this

-reason, we need to:

-

-    * Create a root scope object by calling `angular.scope()`

-

-    * Call `scope.$new(PhoneListCtrl)` to get angular to create the child scope associated with

-    our controller.

-

-    At the same time, we need to tell the testing harness that it should expect an incoming

-    request from our controller. To do this we:

-

-    * Use the `$service` method to retrieve the `$browser` service - this is a service that in

-    angular represents various browser APIs. In tests, angular automatically uses a mock version

-    of this service that allows you to write tests without having to deal with these native APIs

-    and the global state associated with them.

-

-    * We use the `$browser.expectGET` method to train the `$browser` object to expect an incoming

-    http request and tell it what to respond with. Note that the responses are not returned before

-    we call the `$browser.xhr.flush()` method.

-

-    * We then make assertions to verify that the `phones` model doesn't exist on the scope, before

-    the response is received.

-

-    * We flush the xhr queue in the browser by calling `$browser.xhr.flush()`. This causes the

-    callback we passed into the `$xhr` service to be executed with the trained response.

-

-    * Finally, we make the assertions, verifying that the phone model now exists on the scope.

-

-<table id="tutorial_nav">

-<tr>

- <td id="previous_step">{@link tutorial.step_04 Previous}</td>

- <td id="step_result">{@link  http://angular.github.com/angular-phonecat/step-5/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-4...step-5

- Code Diff}</td>

- <td id="next_step">{@link tutorial.step_06 Next}</td>

-</tr>

-</table>

+@ngdoc overview
+@name Tutorial: Step 5
+@description
+<table id="tutorial_nav">
+<tr>
+ <td id="previous_step">{@link tutorial.step_04 Previous}</td>
+ <td id="step_result">{@link  http://angular.github.com/angular-phonecat/step-5/app Live Demo
+}</td>
+ <td id="tut_home">{@link tutorial Tutorial Home}</td>
+<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5 Code
+Diff}</td>
+ <td id="next_step">{@link tutorial.step_06 Next}</td>
+</tr>
+</table>
+
+Enough of building an app with three phones in a hard-coded dataset! Let's fetch a larger dataset
+from our server using one of angular's built-in {@link angular.service services} called {@link
+angular.service.$xhr $xhr}. We will use angular's dependency injection to provide the service to
+the `PhoneListCtrl` controller.
+
+1. Reset your workspace to Step 5 using:
+
+   git checkout --force step-5
+
+or
+
+   ./goto_step.sh 5
+
+2. Refresh your browser or check the app out on {@link
+http://angular.github.com/angular-phonecat/step-5/app our server}. You should now see a list of 20
+phones.
+
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-4...step-5
+GitHub}:
+
+## Data
+
+The `app/phones/phone.json` file in your project is a dataset that contains a larger list of
+phones stored in the JSON format.
+
+Following is a sample of the file:
+<pre>
+[
+ {
+  "age": 13,
+  "id": "motorola-defy-with-motoblur",
+  "name": "Motorola DEFY\u2122 with MOTOBLUR\u2122",
+  "snippet": "Are you ready for everything life throws your way?"
+  ...
+ },
+...
+]
+</pre>
+
+
+## Controller
+
+In this step, the view template will remain the same but the model and controller will change.
+We'll use angular's {@link angular.service.$xhr} service to make an HTTP request to your web
+server to fetch the data in the `phones.json` file.
+
+__`app/js/controllers.js:`__
+<pre>
+function PhoneListCtrl($xhr) {
+  var self = this;
+
+  $xhr('GET', 'phones/phones.json', function(code, response) {
+    self.phones = response;
+  });
+
+  self.orderProp = 'age';
+}
+
+//PhoneListCtrl.$inject = ['$xhr'];
+</pre>
+
+We removed the hard-coded dataset from the controller and instead are using the `$xhr`  service to
+access the data stored in `app/phones/phones.json`. The `$xhr` service makes a HTTP GET request to
+our web server, asking for `phone/phones.json` (the url is relative to our `index.html` file). The
+server responds by providing the data in the json file.
+
+Keep in mind that the response might just as well have been dynamically generated by a backend
+server. To the browser and our app they both look the same. For the sake of simplicity we used a
+json file in this tutorial. 
+
+Notice that the `$xhr` service takes a callback as the last parameter. This callback is used to
+process the response. In our case, we just assign the response to the current scope controlled by
+the controller, as a model called `phones`. Have you realized that we didn't even have to parse
+the response? Angular took care of that for us.
+
+We already mentioned that the `$xhr` function we just used is an angular service. {@link
+angular.service Angular services} are substitutable objects managed by angular's {@link guide.di
+DI subsystem}.
+
+Dependency injection helps to make your web apps well structured, loosely coupled, and much easier
+to test. What's important to understand is how the controllers get access to these services
+through dependency injection.
+
+The dependency injection pattern is based on declaring the dependencies we require and letting the
+system provide them to us. To do this in angular, you simply provide the names of the services you
+need as arguments to the controller's constructor function, as follows:
+
+    function PhoneListCtrl($xhr) {
+
+The name of the argument is significant, because angular recognizes the identity of a service by
+the argument name. Once angular knows what services are being requested, it provides them to the
+controller when the controller is being constructed. The dependency injector also takes care of
+creating any transitive dependencies the service may have (services often depend upon other
+services).
+
+As we mentioned earlier, angular infers the controller's dependencies from the names of arguments
+of the controller's constructor function. If you were to minify the JavaScript code for this
+controller, all of these function arguments would be minified as well, and the dependency injector
+would not being able to identify services correctly. 
+
+To overcome issues caused by minification, just assign an array with service identifier strings
+into the `$inject` property of the controller function, just like the last line in the snippet
+(commented out) suggests:
+
+    PhoneListCtrl.$inject = ['$xhr'];
+
+
+## Test
+
+__`test/unit/controllersSpec.js`:__
+<pre>
+describe('PhoneCat controllers', function() {
+
+  describe('PhoneListCtrl', function(){
+    var scope, $browser, ctrl;
+
+    beforeEach(function() {
+      scope = angular.scope();
+      $browser = scope.$service('$browser');
+
+      $browser.xhr.expectGET('phones/phones.json').respond([{name: 'Nexus S'},
+                                                            {name: 'Motorola DROID'}]);
+      ctrl = scope.$new(PhoneListCtrl);
+    });
+
+
+    it('should create "phones" model with 2 phones fetched from xhr', function() {
+      expect(ctrl.phones).toBeUndefined();
+      $browser.xhr.flush();
+
+      expect(ctrl.phones).toEqual([{name: 'Nexus S'},
+                                   {name: 'Motorola DROID'}]);
+    });
+
+
+    it('should set the default value of orderProp model', function() {
+      expect(ctrl.orderProp).toBe('age');
+    });
+  });
+});
+</pre>
+
+
+Because we started using dependency injection and our controller has dependencies, constructing
+the controller in our tests is a bit more complicated. We could use the `new` operator and provide
+the constructor with some kind of fake `$xhr` implementation. However, the recommended (and
+easier) way is to create a controller in the test environment in the same way that angular does it
+in the production code behind the scenes. 
+
+To create the controller in the test environment, do the following:
+
+    * Create a root scope object by calling `angular.scope()`
+
+    * Call `scope.$new(PhoneListCtrl)` to get angular to create the child scope associated with
+    the `PhoneListCtrl` controller.
+
+Because our code now uses the `$xhr` service to fetch the phone list data in our controller,
+before we create the `PhoneListCtrl` child scope, we need to tell the testing harness to expect an
+incoming request from the controller. To do this we:
+
+    * Use the `{@link angular.scope.$service $service}` method to retrieve the `$browser` service,
+    a service that angular uses to represent various browser APIs. In tests, angular automatically
+    uses a mock version of this service that allows you to write tests without having to deal with
+    these native APIs and the global state associated with them.
+
+    * We use the `$browser.expectGET` method to train the `$browser` object to expect an incoming
+    HTTP request and tell it what to respond with. Note that the responses are not returned before
+    we call the `$browser.xhr.flush()` method.
+
+    * We then make assertions to verify that the `phones` model doesn't exist on the scope, before
+    the response is received.
+
+    * We flush the xhr queue in the browser by calling `$browser.xhr.flush()`. This causes the
+    callback we passed into the `$xhr` service to be executed with the trained response.
+
+    * Finally, we make the assertions, verifying that the phone model now exists on the scope.
+
+To run the unit tests, 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)
+
+
+Now that you have learned how easy it is to use angular services (thanks to angular's
+implementation of dependency injection), go to Step 6, where you will add some thumbnail images of
+phones and some links.
+
+
+<table id="tutorial_nav">
+<tr>
+ <td id="previous_step">{@link tutorial.step_04 Previous}</td>
+ <td id="step_result">{@link  http://angular.github.com/angular-phonecat/step-5/app Live Demo
+}</td>
+ <td id="tut_home">{@link tutorial Tutorial Home}</td>
+ <td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5
+ Code Diff}</td>
+ <td id="next_step">{@link tutorial.step_06 Next}</td>
+</tr>
+</table>