From 6181ca600d3deced0a054551ff6c704bc17d6b7d Mon Sep 17 00:00:00 2001 From: Igor Minar Date: Mon, 2 May 2011 10:16:50 -0700 Subject: new batch of tutorial docs --- docs/content/tutorial/step_05.ngdoc | 366 +++++++++++++++++++++--------------- 1 file changed, 219 insertions(+), 147 deletions(-) (limited to 'docs/content/tutorial/step_05.ngdoc') 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 - - - - - - - - -
{@link tutorial.step_04 Previous}{@link http://angular.github.com/angular-phonecat/step-5/app Example}{@link tutorial Tutorial Home}{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5 Code -Diff}{@link tutorial.step_06 Next}
- -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:`__ -
-/* 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'];
-
- -__`test/unit/controllerSpec.js`:__ -
-/* 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');
-    });
-  });
-});
-
- -## 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. - - - - - - - - - -
{@link tutorial.step_04 Previous}{@link http://angular.github.com/angular-phonecat/step-5/app Example}{@link tutorial Tutorial Home}{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5 - Code Diff}{@link tutorial.step_06 Next}
+@ngdoc overview +@name Tutorial: Step 5 +@description + + + + + + + + +
{@link tutorial.step_04 Previous}{@link http://angular.github.com/angular-phonecat/step-5/app Live Demo +}{@link tutorial Tutorial Home}{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5 Code +Diff}{@link tutorial.step_06 Next}
+ +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: +
+[
+ {
+  "age": 13,
+  "id": "motorola-defy-with-motoblur",
+  "name": "Motorola DEFY\u2122 with MOTOBLUR\u2122",
+  "snippet": "Are you ready for everything life throws your way?"
+  ...
+ },
+...
+]
+
+ + +## 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:`__ +
+function PhoneListCtrl($xhr) {
+  var self = this;
+
+  $xhr('GET', 'phones/phones.json', function(code, response) {
+    self.phones = response;
+  });
+
+  self.orderProp = 'age';
+}
+
+//PhoneListCtrl.$inject = ['$xhr'];
+
+ +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`:__ +
+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');
+    });
+  });
+});
+
+ + +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. + + + + + + + + + + +
{@link tutorial.step_04 Previous}{@link http://angular.github.com/angular-phonecat/step-5/app Live Demo +}{@link tutorial Tutorial Home}{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5 + Code Diff}{@link tutorial.step_06 Next}
-- cgit v1.2.3