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_7.ngdoc | 114 +++++++++++++++++++++++++++------------------
1 file changed, 68 insertions(+), 46 deletions(-)
(limited to 'docs/tutorial.step_7.ngdoc')
diff --git a/docs/tutorial.step_7.ngdoc b/docs/tutorial.step_7.ngdoc
index 3b5984b4..aa4209a2 100755
--- a/docs/tutorial.step_7.ngdoc
+++ b/docs/tutorial.step_7.ngdoc
@@ -5,40 +5,60 @@
| {@link tutorial.step_6 Previous} |
-{@link http://angular.github.com/angular-phonecat/step-7/app Example} |
+{@link http://angular.github.com/angular-phonecat/step-7/app Live Demo
+} |
{@link tutorial Tutorial Home} |
-{@link
-https://github.com/angular/angular-phonecat/commit/43ff5d76f1c0a464da67d691418e33e6c9d8dbc8 Code
+ | {@link https://github.com/angular/angular-phonecat/compare/step-6...step-7 Code
Diff} |
{@link tutorial.step_8 Next} |
-In this step we introduce angular's {@link angular.service.$route $route} service. This service
-is usually used in conjunction with the {@link angular.widget.ng:view ng:view} directive. The
-`$route` service makes it easy to wire together controllers, View templates, and the current URL
+Our app is slowly growing and becoming more complex. Up until now, the app provided our users with
+just one view (the list of all phones), and all of our template code was located in the
+`index.html` file. The next step in building our app is the addition of a view that will show
+detailed information about each of the devices in our list.
+
+To add the detailed view, we could expand the `index.html` file to contain template code for both
+views, but that would get messy very quickly. Instead, we are going to turn the `index.html`
+template into what we call a "layout template". This is a template that is common for all views in
+our application. Other "partial templates" are then included into this layout template depending
+on the current "route" — the view that is currently displayed to the user.
+
+Similarly as with templates, angular also allows for controllers and scopes managed by these
+controllers to be nested. We are going to create a "root" controller called `PhoneCatCtrl`, which
+will contain the declaration of routes for the application.
+
+Application routes in angular are declared via the {@link angular.service.$route $route} service.
+This services makes it easy to wire together controllers, View templates, and the current URL
location in the browser. Using this feature we can implement {@link
http://en.wikipedia.org/wiki/Deep_linking deep linking}, which lets us utilize the browser's
-History, and Back and Forward browser navigation.
+History, and Back and Forward browser navigation.
+
+We'll use the $route service to declare that our application consists of two different views: one
+view presents the phone listing, and the other view presents the details for a particular phone.
+Each view will have the template stored in a separate file in the `app/partials/` directory.
+Similarly each view will have a controller associated with it. These will be stored in the
+existing `app/js/controllers.js` file.
-We'll use {@link angular.service.$route $route} to implement two different views for our
-application: one view presents the phone listing, and the other view presents the details for a
-particular phone. We'll use {@link angular.widget.ng:view ng:view} to include one or the other of
-those views in our main layout page (`index.html`). The view presented in the layout page is based
-on which URL the user navigates to.
+The `$route` service is usually used in conjunction with the {@link angular.widget.ng:view
+ng:view} widget. The role of the `ng:view` widget is to include the view template for the current
+route into the layout template, which makes it a perfect fit for our `index.html` template.
-To manage our two different views, we'll move the existing phone list controller into a
-sub-controller, add a second sub-controller to handle the phone details, and we'll create a new
-root controller to implement the routing. (We'll save the implementation of the phone details
-View for the next step.)
+For now we are going to get all the routing going, and move the phone listing template into a
+separate file. We'll save the implementation of the phone details View for the next step.
__`app/index.html`:__
-
...
+
-...
+
+
+
+
+
__`app/partials/phone-list.html`:__
@@ -65,6 +85,11 @@ __`app/partials/phone-list.html`:__
+__`app/partials/phone-list.html`:__
+
+TBD: detail view for {{params.phoneId}}
+
+
__`app/js/controller.js`:__
/* App Controllers */
@@ -106,53 +131,50 @@ function PhoneDetailCtrl() {}
## Discussion:
-We have many changes to discuss here in Step 7:
-
* __The View.__ Our View template in `index.html` has been reduced down to this:
-``. It is now what we call a "layout template", because it contains
-information common for all views, including the layout of our application. The {@link
-angular.widget.ng:view ng:view} directive behaves like an "include" declaration (it's a
-specialized sibling of the {@link angular.widget.ng:include ng:include} directive) that works
-specifically with the {@link angular.service.$route $route} service. The View template associated
-with the current route definition gets included "between those tags" (there's more to it than a
-simple include, but that explanation will do for now).
-
- * We added two new View templates:
+``. As described above, it is now a "layout template". We added the following
+two new View templates:
- * `app/partials/phone-list.html` for the phone list;
+ * `app/partials/phone-list.html` for the phone list. The phone-list view was formerly our
+ main view. We simply moved the code from `index.html` to here.
- * `app/partials/phone-detail.html` for the phone details (just a stub for this step);
+ * `app/partials/phone-detail.html` for the phone details (just a placeholder template for now).
* __The Controller(s).__ We now have a new root controller (`PhoneCatCtrl`) and two
-sub-controllers (`PhoneListCtrl` and `PhoneDetailCtrl`).
+sub-controllers (`PhoneListCtrl` and `PhoneDetailCtrl`). These inherit the model properties and
+behavior from the root controller.
* __`$route.`__ The root controller's job now is to set up the `$route` configuration:
- * When the fragment part of the URL in the browser ends in "/phones", `$route` grabs the
- `phone-list.html` template, compiles it, and links it with a new scope that is controlled
- by our `PhoneListCtrl` controller.
+ * When the fragment part of the URL in the browser ends in "/phones", `$route` service
+ grabs the `phone-list.html` template, compiles it, and links it with a new scope that is
+ controlled by our `PhoneListCtrl` controller.
* When the URL ends in "/phones/:phoneId", `$route` compiles and links the
`phone-detail.html` template as it did with `phone-list.html`. But note the use of the
- variable `:phoneId` in the `path` parameter of `$route.when()`: `$route` stores that
- portion of the current URL fragment in its current parameters in a property called
- `params.phoneId`. We made the `$route` parameters available to our sub-controllers in the
- `$route.onChange()` function in our root controller. We will use the `phoneId` property
- when we fetch the phone details in Step 8.
+ `:phoneId` parameter declaration in the `path` argument of `$route.when()`: `$route`
+ services provides all the values for variables defined in this way as
+ `$route.current.params` map. In our route, `$route.current.params.phoneId` always holds
+ the current contents of the `:phoneId` portion of the URL. We will use the `phoneId`
+ parameter when we fetch the phone details in Step 8.
* Any other URL fragment gets redirected to `/phones`.
- * __Deep Linking.__ In `$route`'s `onChange()` method, we copied {@link
- http://en.wikipedia.org/wiki/Deep_linking deep linking} parameters to the `params` property in
- the root scope, so we can use them in the child scopes managed by our sub-controllers.
+ * __Controller/Scope inheritance.__ In the function passed into `$route`'s `onChange()`
+ method, we copied url parameters extracted from the current route to the `params` property in
+ the root scope. This property is inherited by child scopes created for our view controllers
+ and accessible by these controllers.
+
+ * __Tests.__ To automatically verify that everything is wired properly, we write end to end
+ tests that navigate to various URLs and verify that the correct view was rendered.
| {@link tutorial.step_6 Previous} |
-{@link http://angular.github.com/angular-phonecat/step-7/app Example} |
+{@link http://angular.github.com/angular-phonecat/step-7/app Live Demo
+} |
{@link tutorial Tutorial Home} |
-{@link
-https://github.com/angular/angular-phonecat/commit/43ff5d76f1c0a464da67d691418e33e6c9d8dbc8 Code
+ | {@link https://github.com/angular/angular-phonecat/compare/step-6...step-7 Code
Diff} |
{@link tutorial.step_8 Next} |
--
cgit v1.2.3