kylefang/angular.js
1
0
Fork 0
mirror of https://github.com/zhigang1992/angular.js.git synced 2026-04-01 12:33:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(tutorial): clean up and elaborate introduction

Browse Source
This commit is contained in:
Peter Bacon Darwin
2014-04-04 10:22:33 +01:00
parent a526ae8f77
commit 7b0c5b937c
1 changed files with 112 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

181
docs/content/tutorial/index.ngdoc
View File

@@ -13,23 +13,25 @@ details for any device.
<img class="diagram" src="img/tutorial/catalog_screen.png" width="488" height="413" alt="demo
application running in the browser">
Work through the tutorial to see how Angular makes browsers smarter — without the use of native
extensions or plug-ins. As you work through the tutorial, you will:
Follow the tutorial to see how Angular makes browsers smarter — without the use of native
extensions or plug-ins:
* See examples of how to use client-side data binding and dependency injection to build dynamic
views of data that change immediately in response to user actions.
* See how Angular creates listeners on your data without the need for DOM manipulation.
* Learn a better, easier way to test your web apps.
* Learn how to use Angular services to make common web tasks, such as getting data into your app,
easier.
* See examples of how to use client-side data binding to build dynamic views of data that change
immediately in response to user actions.
* See how Angular keeps your views in synch with your data without the need for DOM manipulation.
* Learn a better, easier way to test your web apps, with Karma and Protractor.
* Learn how to use dependency injection and services to make common web tasks, such as getting data
into your app, easier.
When you finish the tutorial you will be able to:
* Create a dynamic application that works in all modern browsers.
* Define the differences between Angular and common JavaScript frameworks.
* Understand how data binding works in AngularJS.
* Create and run unit tests.
* Create and run end to end tests.
* Use data binding to wire up your data model to your views.
* Create and run unit tests, with Karma.
* Create and run end to end tests, with Protractor.
* Move application logic out of the template and into Controllers.
* Get data from a server using Angular services.
* Apply animations to your application, using ngAnimate.
* Identify resources for learning more about AngularJS.
The tutorial guides you through the entire process of building a simple application, including
@@ -40,31 +42,46 @@ You can go through the whole tutorial in a couple of hours or you may want to sp
really digging into it. If you're looking for a shorter introduction to AngularJS, check out the
{@link misc/started Getting Started} document.
# Get Started
The rest of this page explains how you can set up your machine to work with the code on your local
machine. If you just want to read the tutorial then you can just go straight to the first step:
[Step 0 - Bootstrapping](tutorial/step_00).
# Working with the code
You can follow along with this tutorial and hack on the code in either the Mac/Linux or the Windows
environment. The tutorial relies on the use of the [Git][git] versioning system for source code
management.
You can follow along with this tutorial and hack on the code in the comfort of your own computer.
In this way you can get hands-on practice of really writing AngularJS code and also on using the
recommended testing tools.
You don't need to know anything about Git to follow the tutorial. Select one of the tabs below
and follow the instructions for setting up your computer.
The tutorial relies on the use of the [Git][git] versioning system for source code management.
You don't need to know anything about Git to follow the tutorial other than how to install and run
a few git commands.
## Install Git
### Install Git
You'll need Git, which you can get from [the Git site][git].
You can download and install Git from http://git-scm.com/download. Once installed you should have
access to the `git` command line tool. The main commands that you will need to use are:
- `git clone ...` : clone a remote repository onto your local machine
- `git checkout ...` : check out a particular branch or a tagged version of the code to hack on
### Download angular-phonecat
Clone the [angular-phonecat repository][angular-phonecat] located at GitHub by running the following
command:
```
git clone https://github.com/angular/angular-phonecat.git
git clone --depth=14 https://github.com/angular/angular-phonecat.git
```
This command creates the `angular-phonecat` directory in your current directory.
<div class="alert alert-info">The `--depth=14` option just tells Git to pull down only the last 14 commits. This makes the
download much smaller and faster.
</div>
Change your current directory to `angular-phonecat`.
```
@@ -75,118 +92,144 @@ The tutorial instructions, from now on, assume you are running all commands from
`angular-phonecat` directory.
## Install Node.js
### Install Node.js
If you want to run the built-in web-server and the test tools then you will also need
Node.js v0.10, or later.
If you want to run the preconfigured local web-server and the test tools then you will also need
[Node.js v0.10+][node].
You can download Node.js from the [node.js website][node].
You can download a Node.js installer for your operating system from http://nodejs.org/download/.
You can check the version of Node.js that you have installed by running the following command:
Check the version of Node.js that you have installed by running the following command:
```
node --version
```
<div class="alert alert-info"><strong>Helpful note:<strong> If you need to run a different versions of node.js
<div class="alert alert-info">If you need to run a different versions of node.js
in your local environment, consider installing
<a href="https://github.com/creationix/nvm" title="Node Version Manager Github Repo link">
Node Version Manager (nvm)
</a>.
</div>
Once you have Node.js installed you can install the tool dependencies by running:
Once you have Node.js installed on your machine you can download the tool dependencies by running:
```
npm install
```
This command will download the following tools, into the `node_modules` directive:
This command will download the following tools, into the `node_modules` directory:
- [Bower][bower] - client-side code package manager
- [http-server][http-server] - simple local static web server
- [Http-Server][http-server] - simple local static web server
- [Karma][karma] - unit test runner
- [protractor][protractor] - end 2 end test runner
- [Protractor][protractor] - end 2 end test runner
Running `npm install` will also automatically run `bower install`, which will download the Angular
framework into the `bower_components` directory.
The project is preconfigured with a number of npm helper scripts to make it easy to run the common
tasks that you will need while developing.
tasks that you will need while developing:
## Running Development Web Server
- `npm start` : start a local development web-server
- `npm test` : start the Karma unit test runner
- `npm run protractor` : run the Protractor end 2 end tests
- `npm update-webdriver` : install the drivers needed by Protractor
The project is preconfigured to provide a simple static web server for hosting the application.
Start the web server by running:
### Running Development Web Server
While Angular applications are purely client-side code, and it is possible to open them in a web
browser directly from the file system, it is better to server them from a HTTP web server. In
particular, for security reasons, most modern browsers will not allow JavaScript to make server
requests if the page is loaded directly from the file system.
The angular-phonecat project is configured with a simple static web server for hosting the
application during development. Start the web server by running:
```
npm start
```
Now you can browse to the application at:
This will create a local webserver that is listening to port 8000 on your local machine.
You can now browse to the application at:
```
http://localhost:8000/app/index.html
```
## Running Unit Tests
### Running Unit Tests
The project is preconfigured to use [Karma][karma] to run the unit tests for the application. Start
Karma by running:
We use unit tests to ensure that the JavaScript code in our application is operating correctly.
Unit tests focus on testing small isolated parts of the application. The unit tests are kept in the
`test/unit` directory.
The angular-phonecat project is configured to use [Karma][karma] to run the unit tests for the
application. Start Karma by running:
```
npm test
```
This will start the Karma unit test runner, open up a Chrome browser and execute all the unit tests
in this browser. Karma will then sit and watch all the source and test JavaScript files.
Whenever one of these files changes Karma re-runs all the unit tests.
This will start the Karma unit test runner. Karma will read the configuration file at
`test/karma.conf.js`. This configuration file tells Karma to:
It is good to leave this running all the time as you will get immediate feedback from Karma as you
are working on the code.
- open up a Chrome browser and connect it to Karma
- execute all the unit tests in this browser
- report the results of these tests in the terminal/command line window
- watch all the project's JavaScript files and re-run the tests whenever any of these change
It is good to leave this running all the time, in the background, as it will give you immediate
feedback about whether your changes pass the unit tests while you are working on the code.
## Running End to End Tests
### Running End to End Tests
The project is preconfigured to use [Protractor][protractor] to run the end to end tests for the
application. Set up the binaries protractor needs to run by running:
We use End to End tests to ensure that the application as a whole operates as expected.
End to End tests are designed to test the whole client side application, in particular that the
views are displaying and behaving correctly. It does this by simulating real user interaction with
the real application running in the browser.
The End to End tests are kept in the `test/e2e` directory.
The angular-phonecat project is configured to use [Protractor][protractor] to run the End to End
tests for the application. Protractor relies upon a set of drivers to allow it to interact with
the browser. You can install these drivers by running:
```
npm run update-webdriver
```
(You will only need to do this once) Execute the Protractor test scripts against your application
by running:
*(You should only need to do this once.)*
Since Protractor works by interacting with a running application, we need to start our web server:
```
npm start
```
Then in a separate terminal/command line window, we can run the Protractor test scripts against the
application by running:
```
npm run protractor
```
This will start the Protractor end to end test runner, open up a Chrome browser and execute all the
end to end test scripts in this browser. Once the test scripts finish, the browser will close down
and Protractor will exit.
Protractor will read the configuration file at `test/protractor-conf.js`. This configuration tells
Protractor to:
- open up a Chrome browser and connect it to the application
- execute all the End to End tests in this browser
- report the results of these tests in the terminal/command line window
- close down the browser and exit
It is good to run the end to end tests whenever you make changes to the HTML views or want to check
that the application as a whole is executing correctly.
<div class="alert alert-info"><strong>Helpful note:</strong> Protractor requires that a web server is running
and serving up the application at the default URL: `http://localhost:8000/app/index.html`. You can
start the provided development server by running `npm start`.
</div>
that the application as a whole is executing correctly. It is very common to run End to End tests
before pushing a new commit of changes to a remote repository.
# Get Started
Now your environment is ready, it is time to get started developing the Angular PhoneCat
application.
<a href="tutorial/step_00" title="Next Step"><span class="btn btn-primary">Step 0 - Bootstrapping</span></a>
[git]: http://git-scm.com/download
[angular-phonecat]: https://github.com/angular/angular-phonecat
[git]: http://git-scm.com/
[node]: http://nodejs.org/
[angular-phonecat]: https://github.com/angular/angular-phonecat
[protractor]: https://github.com/angular/protractor
[bower]: http://bower.io/
[http-server]: https://github.com/nodeapps/http-server