Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit 2845301

Browse files
petebacondarwinpetebacondarwin
committed
docs(tutorial): synchronize with angular-phonecat changes
1 parent 6b7a1b8 commit 2845301

12 files changed

+356
-283
lines changed

‎docs/content/tutorial/step_01.ngdoc

+2-5
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,12 @@ dynamically display the same result with any set of data.
1212

1313
In this step you will add some basic information about two cell phones to an HTML page.
1414

15+
- The page now contains a list with information about two phones.
1516

1617
<div doc-tutorial-reset="1"></div>
1718

1819

19-
The page now contains a list with information about two phones.
20-
21-
The most important changes are listed below. You can see the full diff on [GitHub](https://github.com/angular/angular-phonecat/compare/step-0...step-1):
22-
23-
__`app/index.html`:__
20+
**`app/index.html`:**
2421

2522
```html
2623
<ul>

‎docs/content/tutorial/step_02.ngdoc

+66-65
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,16 @@
99
Now it's time to make the web page dynamic — with AngularJS. We'll also add a test that verifies the
1010
code for the controller we are going to add.
1111

12-
There are many ways to structure the code for an application. For Angular apps, we encourage the
13-
use of [the Model-View-Controller (MVC)
14-
design pattern](http://en.wikipedia.org/wiki/Model–View–Controller) to decouple the code and to separate concerns. With that in mind, let's use a
15-
little Angular and JavaScript to add model, view, and controller components to our app.
12+
There are many ways to structure the code for an application. For Angular apps, we encourage the use of
13+
[the Model-View-Controller (MVC) design pattern](http://en.wikipedia.org/wiki/Model–View–Controller)
14+
to decouple the code and to separate concerns. With that in mind, let's use a little Angular and
15+
JavaScript to add model, view, and controller components to our app.
1616

17+
- The list of three phones is now generated dynamically from data
1718

1819
<div doc-tutorial-reset="2"></div>
1920

2021

21-
The app now contains a list with three phones.
22-
23-
The most important changes are listed below. You can see the full diff on [GitHub](https://github.com/angular/angular-phonecat/compare/step-1...step-2):
24-
25-
2622
## View and Template
2723

2824
In Angular, the __view__ is a projection of the model through the HTML __template__. This means that
@@ -37,7 +33,7 @@ __`app/index.html`:__
3733
<html ng-app="phonecatApp">
3834
<head>
3935
...
40-
<script src="lib/angular/angular.js"></script>
36+
<script src="../bower_components/angular/angular.js"></script>
4137
<script src="js/controllers.js"></script>
4238
</head>
4339
<body ng-controller="PhoneListCtrl">
@@ -53,21 +49,21 @@ __`app/index.html`:__
5349
</html>
5450
```
5551

56-
We replaced the hard-coded phone list with the
57-
{@link ng.directive:ngRepeat ngRepeat directive} and two
58-
{@link guide/expression Angular expressions} enclosed in curly braces:
59-
`{{phone.name}}` and `{{phone.snippet}}`:
52+
We replaced the hard-coded phone list with the {@link ng.directive:ngRepeat ngRepeat directive}
53+
and two {@link guide/expression Angular expressions}:
6054

61-
* The `ng-repeat="phone in phones"` statement in the `<li>` tag is an Angular repeater. The
62-
repeater tells Angular to create a `<li>` element for each phone in the list using the first `<li>`
55+
* The `ng-repeat="phone in phones"` attribute in the `<li>` tag is an Angular repeater directive.
56+
The repeater tells Angular to create a `<li>` element for each phone in the list using the `<li>`
6357
tag as the template.
58+
* The expressions wrapped in curly braces (`{{phone.name}}` and `{{phone.snippet}}`) will be replaced
59+
by the value of the expressions.
6460

6561
We have added a new directive, called `ng-controller`, which attaches a `PhoneListCtrl`
66-
__controller__ to the DOM at this point.
62+
__controller__ to the DOM at this point:
6763

68-
* As we've learned in {@link step_00 step 0}, the curly braces around `phone.name` and `phone.snippet` denote
69-
bindings. As opposed to evaluating constants, these expressions are referring to our application
70-
model, which was set up in our `PhoneListCtrl` controller.
64+
* The expressions in curly braces (`{{phone.name}}` and `{{phone.snippet}}` denote
65+
bindings, which are referring to our application model, which is set up in our `PhoneListCtrl`
66+
controller.
7167

7268
<img class="diagram" src="img/tutorial/tutorial_02.png">
7369

@@ -128,23 +124,19 @@ To learn more about Angular scopes, see the {@link ng.$rootScope.Scope angular s
128124
## Tests
129125

130126
The "Angular way" of separating controller from the view, makes it easy to test code as it is being
131-
developed. If our controller is available on the global namespace then we can simply instantiate it
132-
with a mock `scope` object. Take a look at the following unit test for our controller:
133-
134-
__`test/unit/controllersSpec.js`:__
127+
developed. If our controller is available on the global namespace then we could simply instantiate it
128+
with a mock `scope` object:
135129

136130
```js
137-
describe('PhoneCat controllers', function() {
131+
describe('PhoneListCtrl', function(){
138132

139-
describe('PhoneListCtrl', function(){
133+
it('should create "phones" model with 3 phones', function() {
134+
var scope = {},
135+
ctrl = new PhoneListCtrl(scope);
140136

141-
it('should create "phones" model with 3 phones', function() {
142-
var scope = {},
143-
ctrl = new PhoneListCtrl(scope);
144-
145-
expect(scope.phones.length).toBe(3);
146-
});
137+
expect(scope.phones.length).toBe(3);
147138
});
139+
148140
});
149141
```
150142

@@ -154,67 +146,72 @@ Angular. Since testing is such a critical part of software development, we make
154146
tests in Angular so that developers are encouraged to write them.
155147

156148
### Testing non-Global Controllers
157-
In practice, you will not want to have your controller functions in the global namespace. Instead,
158-
we have registered our controllers in the `phonecatApp` module. In this case Angular provides a
159-
service, `$controller`, which will retrieve your controller by name. Here is the same test using
160-
`$controller`:
149+
150+
In practice, you will not want to have your controller functions in the global namespace. Instead,
151+
you can see that we have registered it via an anonymous constructor function on the `phoneCatApp`
152+
module.
153+
154+
In this case Angular provides a service, `$controller`, which will retrieve your controller by name.
155+
Here is the same test using `$controller`:
161156

162157
__`test/unit/controllersSpec.js`:__
163158

164159
```js
165-
describe('PhoneCat controllers', function() {
160+
describe('PhoneListCtrl', function(){
161+
166162
beforeEach(module('phonecatApp'));
167163

168-
describe('PhoneListCtrl', function(){
164+
it('should create "phones" model with 3 phones', inject(function($controller) {
165+
var scope = {},
166+
ctrl = $controller('PhoneListCtrl', {$scope:scope});
169167

170-
it('should create "phones" model with 3 phones', inject(function($controller) {
171-
var scope = {},
172-
ctrl = $controller('PhoneListCtrl', { $scope: scope });
168+
expect(scope.phones.length).toBe(3);
169+
}));
173170

174-
expect(scope.phones.length).toBe(3);
175-
}));
176-
});
177171
});
178172
```
179173

180-
Don't forget that we need to load up the `phonecatApp` module into the test so that the controller
181-
is available to be injected.
174+
* Before each test we tell Angular to load the `phonecatApp` module.
175+
* We ask Angular to `inject` the `$controller` service into our test function
176+
* We use `$controller` to create an instance of the `PhoneListCtrl`
177+
* With this instance, we verify that the phones array property on the scope contains three records.
178+
182179

183180
### Writing and Running Tests
181+
184182
Angular developers prefer the syntax of Jasmine's Behavior-driven Development (BDD) framework when
185183
writing tests. Although Angular does not require you to use Jasmine, we wrote all of the tests in
186-
this tutorial in Jasmine. You can learn about Jasmine on the [Jasmine home page](http://jasmine.github.io/) and at the [Jasmine docs](http://jasmine.github.io/).
187-
188-
The angular-seed project is pre-configured to run all unit tests using [Karma](http://karma-runner.github.io/). Ensure that the necessary karma plugins are installed.
189-
You can do this by issuing `npm install` into your terminal.
184+
this tutorial in Jasmine v1.3. You can learn about Jasmine on the [Jasmine home page][jasmine] and
185+
at the [Jasmine docs][jasmine-docs].
190186

187+
The angular-seed project is pre-configured to run unit tests using [Karma][karma] but you will need
188+
to ensure that Karma and its necessary plugins are installed. You can do this by running
189+
`npm install`.
191190

192-
To run the test, do the following:
191+
To run the tests, and then watch the files for changes: `npm test`.
193192

194-
1. In a _separate_ terminal window or tab, go to the `angular-phonecat` directory and run
195-
`npm test` to start the Karma server (the config file necessary to start the server is
196-
located at `./test/karma.conf.js`).
197-
198-
2. Karma will start a new instance of Chrome browser automatically. Just ignore it and let it run in
193+
* Karma will start a new instance of Chrome browser automatically. Just ignore it and let it run in
199194
the background. Karma will use this browser for test execution.
195+
* You should see the following or similar output in the terminal:
200196

201-
3. You should see the following or similar output in the terminal:
202-
203-
info: Karma server started at http://localhost:9876/
204-
info (launcher): Starting browser "Chrome"
205-
info (Chrome 22.0): Connected on socket id tPUm9DXcLHtZTKbAEO-n
206-
Chrome 22.0: Executed 1 of 1 SUCCESS (0.093 secs / 0.004 secs)
197+
<pre>
198+
info: Karma server started at http://localhost:9876/
199+
info (launcher): Starting browser "Chrome"
200+
info (Chrome 22.0): Connected on socket id tPUm9DXcLHtZTKbAEO-n
201+
Chrome 22.0: Executed 1 of 1 SUCCESS (0.093 secs / 0.004 secs)
202+
</pre>
207203

208204
Yay! The test passed! Or not...
209-
210-
4. To rerun the tests, just change any of the source or test .js files. Karma will notice the change
205+
* To rerun the tests, just change any of the source or test .js files. Karma will notice the change
211206
and will rerun the tests for you. Now isn't that sweet?
212207

213208
# Experiments
214209

215210
* Add another binding to `index.html`. For example:
216211

217-
<p>Total number of phones: {{phones.length}}</p>
212+
```html
213+
<p>Total number of phones: {{phones.length}}</p>
214+
```
218215

219216
* Create a new model property in the controller and bind to it from the template. For example:
220217

@@ -255,3 +252,7 @@ to the app.
255252

256253

257254
<ul doc-tutorial-nav="2"></ul>
255+
256+
[jasmine]: http://jasmine.github.io/
257+
[jasmine-docs]: http://jasmine.github.io/1.3/introduction.html
258+
[karma]: http://karma-runner.github.io/

‎docs/content/tutorial/step_03.ngdoc

+14-15
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,10 @@ simple; we will add full text search (yes, it will be simple!). We will also wri
1111
test, because a good end-to-end test is a good friend. It stays with your app, keeps an eye on it,
1212
and quickly detects regressions.
1313

14-
15-
<div doc-tutorial-reset="3"></div>
16-
17-
18-
The app now has a search box. Notice that the phone list on the page changes depending on what a
14+
* The app now has a search box. Notice that the phone list on the page changes depending on what a
1915
user types into the search box.
2016

21-
The most important differences between Steps 2 and 3 are listed below. You can see the full diff on
22-
[GitHub](https://github.com/angular/angular-phonecat/compare/step-2...step-3):
17+
<div doc-tutorial-reset="3"></div>
2318

2419

2520
## Controller
@@ -118,22 +113,26 @@ describe('PhoneCat App', function() {
118113
});
119114
```
120115

116+
This test verifies that the search box and the repeater are correctly wired together. Notice how
117+
easy it is to write end-to-end tests in Angular. Although this example is for a simple test, it
118+
really is that easy to set up any functional, readable, end-to-end test.
119+
120+
### Running End to End Tests with Protractor
121121
Even though the syntax of this test looks very much like our controller unit test written with
122-
Jasmine, the end-to-end test uses APIs of {@link guide/e2e-testing Angular's end-to-end
123-
test runner}.
122+
Jasmine, the end-to-end test uses APIs of [Protractor](https://github.com/angular/protractor). Read
123+
about the Protractor APIs at https://github.com/angular/protractor/blob/master/docs/api.md.
124124

125125
Much like Karma is the test runner for unit tests, we use Protractor to run end-to-end tests.
126126
Try it with `npm run protractor`. End-to-end tests are slow, so unlike with unit tests, Protractor
127127
will exit after the test run and will not automatically rerun the test suite on every file change.
128128
To rerun the test suite, execute `npm run protractor` again.
129129

130-
Note: You must ensure you've installed the protractor and updated webdriver prior to running the
131-
`npm run protractor`. You can do this by issuing `npm install` and `npm run update-webdriver` into
132-
your terminal.
130+
<div class="alert alert-info">
131+
Note: You must ensure you've installed the protractor and updated webdriver prior to running the
132+
`npm run protractor`. You can do this by issuing `npm install` and `npm run update-webdriver` into
133+
your terminal.
134+
</div>
133135

134-
This test verifies that the search box and the repeater are correctly wired together. Notice how
135-
easy it is to write end-to-end tests in Angular. Although this example is for a simple test, it
136-
really is that easy to set up any functional, readable, end-to-end test.
137136

138137
# Experiments
139138

‎docs/content/tutorial/step_04.ngdoc

+4-8
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,11 @@ In this step, you will add a feature to let your users control the order of the
1010
list. The dynamic ordering is implemented by creating a new model property, wiring it together with
1111
the repeater, and letting the data binding magic do the rest of the work.
1212

13-
14-
<div doc-tutorial-reset="4"></div>
13+
* In addition to the search box, the app displays a drop down menu that allows users to control the
14+
order in which the phones are listed.
1515

1616

17-
You should see that in addition to the search box, the app displays a drop down menu that allows
18-
users to control the order in which the phones are listed.
19-
20-
The most important differences between Steps 3 and 4 are listed below. You can see the full diff on
21-
[GitHub](https://github.com/angular/angular-phonecat/compare/step-3...step-4):
17+
<div doc-tutorial-reset="4"></div>
2218

2319

2420
## Template
@@ -143,7 +139,7 @@ shared by all tests in the parent `describe` block.
143139

144140
You should now see the following output in the Karma tab:
145141

146-
Chrome 22.0: Executed 2 of 2 SUCCESS (0.021 secs / 0.001 secs)
142+
<pre>Chrome 22.0: Executed 2 of 2 SUCCESS (0.021 secs / 0.001 secs)</pre>
147143

148144

149145
Let's turn our attention to the end-to-end test.

‎docs/content/tutorial/step_05.ngdoc

+5-8
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,11 @@ from our server using one of Angular's built-in {@link guide/services services}
1111
ng.$http $http}. We will use Angular's {@link guide/di dependency
1212
injection (DI)} to provide the service to the `PhoneListCtrl` controller.
1313

14+
* There are now a list of 20 phones, loaded from the server.
1415

1516
<div doc-tutorial-reset="5"></div>
1617

1718

18-
You should now see a list of 20 phones.
19-
20-
The most important changes are listed below. You can see the full diff on [GitHub](https://github.com/angular/angular-phonecat/compare/step-4...step-5):
21-
2219
## Data
2320
The `app/phones/phones.json` file in your project is a dataset that contains a larger list of phones
2421
stored in the JSON format.
@@ -165,9 +162,9 @@ __`test/unit/controllersSpec.js`:__
165162

166163
Because we started using dependency injection and our controller has dependencies, constructing the
167164
controller in our tests is a bit more complicated. We could use the `new` operator and provide the
168-
constructor with some kind of fake `$http` implementation. However, the recommended (and easier) way
169-
is to create a controller in the test environment in the same way that Angular does it in the
170-
production code behind the scenes, as follows:
165+
constructor with some kind of fake `$http` implementation. However, Angular provides a mock `$http`
166+
service that we can use in unit tests. We configure "fake" responses to server requests by calling
167+
methods on a service called $httpBackend:
171168

172169
```js
173170
describe('PhoneCat controllers', function() {
@@ -251,7 +248,7 @@ Finally, we verify that the default value of `orderProp` is set correctly:
251248

252249
You should now see the following output in the Karma tab:
253250

254-
Chrome 22.0: Executed 2 of 2 SUCCESS (0.028 secs / 0.007 secs)
251+
<pre>Chrome 22.0: Executed 2 of 2 SUCCESS (0.028 secs / 0.007 secs)</pre>
255252

256253

257254

‎docs/content/tutorial/step_06.ngdoc

+1-6
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,10 @@ In this step, you will add thumbnail images for the phones in the phone list, an
1010
now, will go nowhere. In subsequent steps you will use the links to display additional information
1111
about the phones in the catalog.
1212

13+
* There are now links and images of the phones in the list.
1314

1415
<div doc-tutorial-reset="6"></div>
1516

16-
17-
You should now see links and images of the phones in the list.
18-
19-
The most important changes are listed below. You can see the full diff on [GitHub](https://github.com/angular/angular-phonecat/compare/step-5...step-6):
20-
21-
2217
## Data
2318

2419
Note that the `phones.json` file contains unique ids and image urls for each of the phones. The

0 commit comments

Comments
 (0)