From e205bd7137fd793d223dbe3e020a628f8e7d98f3 Mon Sep 17 00:00:00 2001 From: Kenneth R. Culp Date: Fri, 29 Apr 2011 10:04:40 -0700 Subject: Update tutorial docs. --- docs/tutorial.step_5.ngdoc | 74 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 56 insertions(+), 18 deletions(-) (limited to 'docs/tutorial.step_5.ngdoc') diff --git a/docs/tutorial.step_5.ngdoc b/docs/tutorial.step_5.ngdoc index 3480e437..c28d7bf8 100755 --- a/docs/tutorial.step_5.ngdoc +++ b/docs/tutorial.step_5.ngdoc @@ -7,17 +7,16 @@ {@link tutorial.step_4 Previous} {@link http://angular.github.com/angular-phonecat/step-5/app Example} {@link tutorial Tutorial Home} - {@link - https://github.com/angular/angular-phonecat/commit/4f0a518557b5c7442568666b211aa79499870276 Code - Diff} +{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5 Code +Diff} {@link tutorial.step_6 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 -`HttpXmlRequest` request to communicate with a server. Angular provides the built-in {@link -angular.service.$xhr $xhr} service for this purpose. +`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 @@ -83,27 +82,66 @@ to web apps. Angular provides several built-in services (such as {@link angular $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 a parameter to the function in which you are using that service. Angular's {@link guide.di DI -subsystem} recognizes the identity of the service by name, provides it for you when you need it, -and manages any transitive dependencies the service may have (services often depend upon other -services). +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). -* __`$xhr`:__ We moved our data set out of the controller and into the file `phones/phones.json`. -This file serves as our data store rather than an actual server (to the browser they look the -same). We now use the `$xhr` service to return our phone data, which you'll note is still within -the scope of our controller function. + 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. -* __Testing:__ The unit test has been expanded. It now verifies that the `$xhr` service behaves -as expected. +* __`$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_4 Previous} {@link http://angular.github.com/angular-phonecat/step-5/app Example} {@link tutorial Tutorial Home}{@link - https://github.com/angular/angular-phonecat/commit/4f0a518557b5c7442568666b211aa79499870276 Code - Diff}{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5 + Code Diff} {@link tutorial.step_6 Next}
-- cgit v1.2.3