Improve this doc

PhoneCat Tutorial App

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.

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:

When you finish the tutorial you will be able to:

The tutorial guides you through the entire process of building a simple application, including writing and running unit and end-to-end tests. Experiments at the end of each step provide suggestions for you to learn more about AngularJS and the application you are building.

You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day really digging into it. If you're looking for a shorter introduction to AngularJS, check out the Getting Started document.

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 versioning system for source code management.

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.

Install Git

You'll need Git, which you can get from the Git site.

Clone the angular-phonecat repository located at GitHub by running the following command:

git clone https://github.com/angular/angular-phonecat.git

This command creates the angular-phonecat directory in your current directory.

Change your current directory to angular-phonecat.

cd angular-phonecat

The tutorial instructions, from now on, assume you are running all commands from the angular-phonecat directory.

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.

You can download Node.js from the node.js website.

You can check the version of Node.js that you have installed by running the following command:

node --version
Helpful note: If you need to run a different versions of node.js in your local environment, consider installing Node Version Manager (nvm) .

Once you have Node.js installed you can install the tool dependencies by running:

npm install

This command will download the following tools, into the node_modules directive:

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.

Running Development Web Server

The project is preconfigured to provide a simple static web server for hosting the application. Start the web server by running:

npm start

Now you can browse to the application at:

http://localhost:8000/app/index.html

Running Unit Tests

The project is preconfigured to use 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.

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.

Running End to End Tests

The project is preconfigured to use Protractor to run the end to end tests for the application. Set up the binaries protractor needs to run by running:

npm run update-webdriver

(You will only need to do this once) Execute the Protractor test scripts against your 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.

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.

Helpful note: 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.

Get Started

Now your environment is ready, it is time to get started developing the Angular PhoneCat application.

Step 0 - Bootstrapping