From 53b2254ea70019937463d8e079e1991b3d3d1d8b Mon Sep 17 00:00:00 2001
From: Igor Minar
Date: Mon, 2 Apr 2012 08:32:30 -0700
Subject: docs(tutorial): update tutorial intro + steps 0-3
also contains all kinds of fixes that I had to make in the docs app to
get the tutorial to render correctly
---
docs/content/tutorial/index.ngdoc | 32 ++++++-----
docs/content/tutorial/step_00.ngdoc | 102 ++++++++++++++++++++++++++++--------
docs/content/tutorial/step_01.ngdoc | 2 +-
docs/content/tutorial/step_02.ngdoc | 93 +++++++++++++++++---------------
docs/content/tutorial/step_03.ngdoc | 37 ++++++-------
docs/content/tutorial/step_04.ngdoc | 2 +
docs/content/tutorial/step_05.ngdoc | 2 +
docs/content/tutorial/step_06.ngdoc | 2 +
docs/content/tutorial/step_07.ngdoc | 2 +
docs/content/tutorial/step_08.ngdoc | 2 +
docs/content/tutorial/step_09.ngdoc | 2 +
docs/content/tutorial/step_10.ngdoc | 2 +
docs/content/tutorial/step_11.ngdoc | 2 +
docs/content/tutorial/the_end.ngdoc | 2 +
14 files changed, 182 insertions(+), 102 deletions(-)
(limited to 'docs/content/tutorial')
diff --git a/docs/content/tutorial/index.ngdoc b/docs/content/tutorial/index.ngdoc
index c26ea2df..1190aaf2 100644
--- a/docs/content/tutorial/index.ngdoc
+++ b/docs/content/tutorial/index.ngdoc
@@ -2,12 +2,12 @@
@name Tutorial
@description
-A great way to get introduced to Angular is to work through this tutorial, which walks you through
+A great way to get introduced to AngularJS is to work through this tutorial, which walks you through
the construction of an AngularJS web app. The app you will build is a catalog that displays a list
of Android devices, lets you filter the list to see only devices that interest you, and then view
details for any device.
-
+
Work through the tutorial to see how Angular makes browsers smarter — without the use of extensions
or plug-ins. As you work through the tutorial, you will:
@@ -72,9 +72,8 @@ directory.
directory.
You will need an http server running on your system. Mac and Linux machines typically
have Apache pre-installed, but If you don't already have one installed, you can install
-node.js. Use node to run scripts/web-server.js, a simple bundled
-http server.
+href="http://nodejs.org/#download">install node.js. Use node to run
+scripts/web-server.js, a simple bundled http server.
@@ -97,11 +96,10 @@ directory.
You should run all git commands from msysGit bash.
Other commands like test-server.bat or test.bat should be
executed from the Windows command line.
-
You need an http server running on your system. If you don't already have one
-installed, you can install node.js. Download the pre-compiled binaries, unzip them, and then add
-nodejs\bin into your PATH. Use node to run
-scripts\web-server.js, a simple, bundled http server.
+
You need an http server running on your system, but if you don't already have one
+already installed, you can install node.js. Make sure that
+nodejs\bin was added into your PATH. Use node to run
+scripts\web-server.js, a simple bundled http server.
@@ -119,9 +117,8 @@ containing all of the files and unzip them into the [tutorial-dir] directory
sandbox directory.
You need an http server running on your system and Mac and Linux machines typically
have Apache pre-installed. If you don't have an http server installed, you can install
-node.js and use it to run scripts/web-server.js, a simple bundled http
-server.
+href="http://nodejs.org/#download">install node.js and use it to run
+scripts/web-server.js, a simple bundled http server.
@@ -138,13 +135,14 @@ and unzip the files into the [tutorial-dir] directory
cd [tutorial-dir]/sandbox
The tutorial instructions assume you are running all commands from this directory.
You need an http server running on your system, but if you don't already have one
-already installed, you can install node.js. Download the pre-compiled binaries, unzip them, and then add
-nodejs\bin into your PATH. Use node to run
+already installed, you can install node.js. Make sure that
+nodejs\bin was added into your PATH. Use node to run
scripts\web-server.js, a simple bundled http server.
The last thing to do is to make sure your computer has a web browser and a good text editor
-installed. Now, let's get going with {@link step_00 step 0}.
+installed. Now, let's get some cool stuff done!
+
+{@link step_00 Get Started!}
diff --git a/docs/content/tutorial/step_00.ngdoc b/docs/content/tutorial/step_00.ngdoc
index b7f469ff..643ec23b 100644
--- a/docs/content/tutorial/step_00.ngdoc
+++ b/docs/content/tutorial/step_00.ngdoc
@@ -1,11 +1,11 @@
@ngdoc overview
-@name Tutorial: 0 - angular-seed
+@name Tutorial: 0 - Bootstrapping
@description
-You are now ready to build the Angular phonecat application. In this step, you will become familiar
+You are now ready to build the AngularJS phonecat app. In this step, you will become familiar
with the most important source code files, learn how to start the development servers bundled with
angular-seed, and run the application in the browser.
@@ -143,23 +143,23 @@ href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html
You can now see the page in your browser. It's not very exciting, but that's OK.
-The static HTML page that displays "Nothing here yet!" was constructed with the HTML code shown
-below. The code contains some key Angular elements that we will need going forward.
+The HTML page that displays "Nothing here yet!" was constructed with the HTML code shown below.
+The code contains some key Angular elements that we will need going forward.
__`app/index.html`:__
-
+
my angular app
-
+
+
- Nothing here yet!
+ Nothing here {{'yet' + '!'}}
-
@@ -168,30 +168,70 @@ __`app/index.html`:__
## What is the code doing?
-* xmlns declaration
+* `ng-app` directive:
-
+
- This `xmlns` declaration for the `ng` namespace must be specified in all Angular applications in
-order to make Angular work with XHTML and IE versions older than 9 (regardless of whether you are
-using XHTML or HTML).
+ `ng-app` directive is a special tag used to flag an element which Angular should consider to be
+ the root element of our application. This gives application developers the freedom to tell Angular
+ if the entire html page or only a portion of it should be treated as the Angular application.
-* Angular script tag
+* AngularJS script tag:
+
+
+
-
+
{{phone.name}}
{{phone.snippet}}
-
-
-
-We replaced the hard-coded phone list with the {@link api/angular.widget.@ng:repeat ng:repeat
-widget} and two {@link guide/dev_guide.expressions Angular expressions} enclosed in curly braces:
+We replaced the hard-coded phone list with the
+{@link api/angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat directive} and two
+{@link guide/dev_guide.expressions Angular expressions} enclosed in curly braces:
`{{phone.name}}` and `{{phone.snippet}}`:
-* The `ng:repeat="phone in phones"` statement in the `
` tag is an Angular repeater. The
+* The `ng-repeat="phone in phones"` statement in the `
` tag is an Angular repeater. The
repeater tells Angular to create a `
` element for each phone in the list using the first `
`
tag as the template.
-
-
-* The curly braces around `phone.name` and `phone.snippet` are examples of {@link
-guide/dev_guide.compiler.markup Angular markup}. The curly markup is shorthand for the Angular
-directive {@link api/angular.directive.ng:bind ng:bind}. An `ng:bind` directive indicates a
-template binding point to Angular. Binding points are locations in a template where Angular creates
-data-binding between the view and the model.
+* As we've learned in step 0, the curly braces around `phone.name` and `phone.snippet` denote
+bindings. As opposed to evaluating constants, these expression are refering to our application
+model, which was set up in our `PhoneListCtrl` controller.
-In Angular, the view is a projection of the model through the HTML template. This means that
-whenever the model changes, Angular refreshes the appropriate binding points, which updates the
-view.
+
## Model and Controller
The data __model__ (a simple array of phones in object literal notation) is instantiated within
-the __controller__ function(`PhoneListCtrl`):
+the `PhoneListCtrl` __controller__:
__`app/js/controllers.js`:__
-function PhoneListCtrl() {
- this.phones = [{"name": "Nexus S",
- "snippet": "Fast just got faster with Nexus S."},
- {"name": "Motorola XOOM™ with Wi-Fi",
- "snippet": "The Next, Next Generation tablet."},
- {"name": "MOTOROLA XOOM™",
- "snippet": "The Next, Next Generation tablet."}];
+function PhoneListCtrl($scope) {
+ $scope.phones = [{"name": "Nexus S",
+ "snippet": "Fast just got faster with Nexus S."},
+ {"name": "Motorola XOOM™ with Wi-Fi",
+ "snippet": "The Next, Next Generation tablet."},
+ {"name": "MOTOROLA XOOM™",
+ "snippet": "The Next, Next Generation tablet."}];
}
@@ -92,10 +92,15 @@ providing context for our data model, the controller allows us to establish data
the model and the view. We connected the dots between the presentation, data, and logic components
as follows:
-* The name of our controller function(in the JavaScript file `controllers.js`) matches the {@link
-api/angular.directive.ng:controller ng:controller} directive in the `` tag (`PhoneListCtrl`).
-* The data is instantiated within the *scope* of our controller function; our template binding
-points are located within the block bounded by the `` tag.
+* `PhoneListCtrl` — the name of our controller function (located in the JavaScript file
+`controllers.js`), matches the value of the
+{@link api/angular.module.ng.$compileProvider.directive.ng-controller ng-controller} directive located
+on the `` tag.
+
+* The phone data is then attached to the *scope* (`$scope`) that was injected into our controller
+function. The controller scope is a prototypically descendant of the root scope that was created
+when the application bootstrapped. This controller scope is available to all bindings located within
+the `` tag.
The concept of a scope in Angular is crucial; a scope can be seen as the glue which allows the
template, model and controller to work together. Angular uses scopes, along with the information
@@ -118,8 +123,10 @@ describe('PhoneCat controllers', function() {
describe('PhoneListCtrl', function() {
it('should create "phones" model with 3 phones', function() {
- var ctrl = new PhoneListCtrl();
- expect(ctrl.phones.length).toBe(3);
+ var scope = {},
+ ctrl = new PhoneListCtrl(scope);
+
+ expect(scope.phones.length).toBe(3);
});
});
});
@@ -142,11 +149,11 @@ http://code.google.com/p/js-test-driver/ JsTestDriver}. To run the test, do the
1. In a _separate_ terminal window or tab, go to the `angular-phonecat` directory and run
`./scripts/test-server.sh` to start the test web server.
-2. Open a new browser tab or window and navigate to {@link http://localhost:9876}.
+2. Open a new browser window and navigate to {@link http://localhost:9876}.
3. Choose "Capture this browser in strict mode".
- At this point, you can leave this tab open and forget about it. JsTestDriver will use it to
+ At this point, you can leave this window open and forget about it. JsTestDriver will use it to
execute the tests and report the results in the terminal.
4. Execute the test by running `./scripts/test.sh`
@@ -160,8 +167,8 @@ execute the tests and report the results in the terminal.
Yay! The test passed! Or not...
- Note: If you see errors after you run the test, close the browser tab and go back to the terminal
-and kill the script, then repeat the procedure above.
+ Note: If you see errors after you run the test, close the browser window and go back to the
+ terminal and kill the script, then repeat the procedure above.
# Experiments
@@ -179,14 +186,14 @@ and kill the script, then repeat the procedure above.
row number
-
{{i}}
+
{{i}}
Now, make the list 1-based by incrementing `i` by one in the binding:
row number
-
{{i+1}}
+
{{i+1}}
* Make the unit test fail by changing the `toBe(3)` statement to `toBe(4)`, and rerun the
diff --git a/docs/content/tutorial/step_03.ngdoc b/docs/content/tutorial/step_03.ngdoc
index fef4743f..3c997337 100644
--- a/docs/content/tutorial/step_03.ngdoc
+++ b/docs/content/tutorial/step_03.ngdoc
@@ -32,10 +32,10 @@ We made no changes to the controller.
__`app/index.html`:__
...
- Fulltext Search:
+ Fulltext Search:
-
+
{{phone.name}}
{{phone.snippet}}
@@ -43,8 +43,9 @@ __`app/index.html`:__
...
-We added a standard HTML `` tag and used angular's {@link api/angular.module.ng.$filter.filter $filter}
-function to process the input for the `ng:repeater`.
+We added a standard HTML `` tag and used angular's
+{@link api/angular.module.ng.$filter.filter $filter} function to process the input for the
+`ng-repeater`.
This lets a user enter search criteria and immediately see the effects of their search on the phone
list. This new code demonstrates the following:
@@ -53,17 +54,17 @@ list. This new code demonstrates the following:
name of the input box to a variable of the same name in the data model and keeps the two in sync.
In this code, the data that a user types into the input box (named __`query`__) is immediately
-available as a filter input in the list repeater (`phone in phones.$filter(`__`query`__`)`). When
+available as a filter input in the list repeater (`phone in phones | filter(`__`query`__`)`). When
changes to the data model cause the repeater's input to change, the repeater efficiently updates
the DOM to reflect the current state of the model.
-
+
-* Use of `$filter`. The {@link api/angular.module.ng.$filter.filter $filter} method uses the `query` value to
-create a new array that contains only those records that match the `query`.
+* Use of `filter` filter. The {@link api/angular.module.ng.$filter.filter filter} function uses the
+`query` value to create a new array that contains only those records that match the `query`.
- `ng:repeat` automatically updates the view in response to the changing number of phones returned
-by the `$filter`. The process is completely transparent to the developer.
+ `ng-repeat` automatically updates the view in response to the changing number of phones returned
+by the `filter` filter. The process is completely transparent to the developer.
## Test
@@ -127,23 +128,23 @@ really is that easy to set up any functional, readable, end-to-end test.
However, when you reload the page, you won't see the expected result. This is because the "query"
model lives in the scope defined by the body element:
-
+
If you want to bind to the query model from the `` element, you must __move__ the
-`ng:controller` declaration to the HTML element because it is the common parent of both the body
+`ng-controller` declaration to the HTML element because it is the common parent of both the body
and title elements:
- <html ng:controller="PhoneListCtrl">
+ <html ng-app ng-controller="PhoneListCtrl">
- Be sure to *remove* the `ng:controller` declaration from the body element.
+ Be sure to *remove* the `ng-controller` declaration from the body element.
While using double curlies works fine in within the title element, you might have noticed that
for a split second they are actually displayed to the user while the page is loading. A better
-solution would be to use the {@link api/angular.directive.ng:bind ng:bind} or {@link
-api/angular.directive.ng:bind-template ng:bind-template} directives, which are invisible to the
-user while the page is loading:
+solution would be to use the {@link api/angular.module.ng.$compileProvider.directive.ng-bind
+ng-bind} or {@link api/angular.module.ng.$compileProvider.directive.ng-bind-template
+ng-bind-template} directives, which are invisible to the user while the page is loading:
- <title ng:bind-template="Google Phone Gallery: {{query}}">Google Phone Gallery
+ Google Phone Gallery
* Add the following end-to-end test into the `describe` block within `test/e2e/scenarios.js`:
diff --git a/docs/content/tutorial/step_04.ngdoc b/docs/content/tutorial/step_04.ngdoc
index a5fefd74..ebeb7cca 100644
--- a/docs/content/tutorial/step_04.ngdoc
+++ b/docs/content/tutorial/step_04.ngdoc
@@ -2,6 +2,8 @@
@name Tutorial: 4 - Two-way Data Binding
@description
+
This page has not been updated for AngularJS 1.0 yet
This page has not been updated for AngularJS 1.0 yet
+
diff --git a/docs/content/tutorial/the_end.ngdoc b/docs/content/tutorial/the_end.ngdoc
index ed6eda97..f392452e 100644
--- a/docs/content/tutorial/the_end.ngdoc
+++ b/docs/content/tutorial/the_end.ngdoc
@@ -2,6 +2,8 @@
@name Tutorial: The End
@description
+
This page has not been updated for AngularJS 1.0 yet
+
Our application is now complete. Feel free to experiment with the code further, and jump back to
previous steps using the `git checkout` or `goto_step.sh` commands.
--
cgit v1.2.3
+
-
-* The curly braces around `phone.name` and `phone.snippet` are examples of {@link
-guide/dev_guide.compiler.markup Angular markup}. The curly markup is shorthand for the Angular
-directive {@link api/angular.directive.ng:bind ng:bind}. An `ng:bind` directive indicates a
-template binding point to Angular. Binding points are locations in a template where Angular creates
-data-binding between the view and the model.
+* As we've learned in step 0, the curly braces around `phone.name` and `phone.snippet` denote
+bindings. As opposed to evaluating constants, these expression are refering to our application
+model, which was set up in our `PhoneListCtrl` controller.
-In Angular, the view is a projection of the model through the HTML template. This means that
-whenever the model changes, Angular refreshes the appropriate binding points, which updates the
-view.
+ 
## Model and Controller
The data __model__ (a simple array of phones in object literal notation) is instantiated within
-the __controller__ function(`PhoneListCtrl`):
+the `PhoneListCtrl` __controller__:
__`app/js/controllers.js`:__
+ 
-* Use of `$filter`. The {@link api/angular.module.ng.$filter.filter $filter} method uses the `query` value to
-create a new array that contains only those records that match the `query`.
+* Use of `filter` filter. The {@link api/angular.module.ng.$filter.filter filter} function uses the
+`query` value to create a new array that contains only those records that match the `query`.
- `ng:repeat` automatically updates the view in response to the changing number of phones returned
-by the `$filter`. The process is completely transparent to the developer.
+ `ng-repeat` automatically updates the view in response to the changing number of phones returned
+by the `filter` filter. The process is completely transparent to the developer.
## Test
@@ -127,23 +128,23 @@ really is that easy to set up any functional, readable, end-to-end test.
However, when you reload the page, you won't see the expected result. This is because the "query"
model lives in the scope defined by the body element:
-
+
If you want to bind to the query model from the `