Note: obviously, hardly any of this work is mine. My version only has small differences with a couple extra features, tests, and some style differences.
This application takes the developer through the process of building a web-application using AngularJS. The application is loosely based on the Google Phone Gallery, which no longer exists. Here is a historical reference: Google Phone Gallery on WayBack
Each tagged commit is a separate lesson teaching a single aspect of the framework.
The full tutorial can be found at https://docs.angularjs.org/tutorial.
- A good place to learn about setting up git is here.
- You can find documentation and download git here.
- Get Node.js.
- Install the tool dependencies:
npm install
- The application filesystem layout structure is based on the angular-seed project.
- There is no dynamic backend (no application server) for this application. Instead we fake the application server by fetching static JSON files.
- Read the Development section at the end to familiarize yourself with running and developing an Angular application.
You can check out any point of the tutorial using:
git checkout step-?
To see the changes made between any two lessons use the git diff
command:
git diff step-?..step-?
- Add the 'angular.js' script.
- Add the
ngApp
directive to bootstrap the application. - Add a simple template with an expression.
- Add a stylesheet file ('app/app.css').
- Add a static list with two phones.
- Convert the static phone list to dynamic by:
- Creating a
PhoneListController
controller. - Extracting the data from HTML into the controller as an in-memory dataset.
- Converting the static document into a template with the use of the
ngRepeat
directive.
- Creating a
- Add a simple unit test for the
PhoneListController
controller to show how to write tests and run them using Karma.
- Introduce components.
- Combine the controller and the template into a reusable, isolated
phoneList
component. - Refactor the application and tests to use the
phoneList
component.
- Refactor the layout of files and directories, applying best practices and techniques that will
make the application easier to maintain and expand in the future:
- Put each entity in its own file.
- Organize code by feature area (instead of by function).
- Split code into modules that other modules can depend on.
- Use external templates in
.html
files (instead of inline HTML strings).
- Add a search box to demonstrate:
- How the data-binding works on input fields.
- How to use the
filter
filter. - How
ngRepeat
automatically shrinks and grows the number of phones in the view.
- Add an end-to-end test to:
- Show how end-to-end tests are written and used.
- Prove that the search box and the repeater are correctly wired together.
- Add an
age
property to the phone model. - Add a drop-down menu to control the phone list order.
- Override the default order value in controller.
- Add unit and end-to-end tests for this feature.
- Replace the in-memory dataset with data loaded from the server (in the form of a static
'phone.json' file to keep the tutorial backend agnostic):
- The JSON data is loaded using the
$http
service.
- The JSON data is loaded using the
- Demonstrate the use of
services
anddependency injection
(DI):$http
is injected into the controller through DI.- Introduce DI annotation methods:
.$inject
and inline array
- Add a phone image and links to phone pages.
- Add an end-to-end test that verifies the phone links.
- Tweak the CSS to style the page just a notch.
- Introduce the
$route
service, which allows binding URLs to views for routing and deep-linking:- Add the
ngRoute
module as a dependency. - Configure routes for the application.
- Use the
ngView
directive in 'index.html'.
- Add the
- Create a phone list route (
/phones
):- Map
/phones
to the existingphoneList
component.
- Map
- Create a phone detail route (
/phones/:phoneId
):- Map
/phones/:phoneId
to a newphoneDetail
component. - Create a dummy
phoneDetail
component, which displays the selected phone ID. - Pass the
phoneId
parameter to the component's controller via$routeParams
.
- Map
- Implement fetching data for the selected phone and rendering to the view:
- Use
$http
inPhoneDetailController
to fetch the phone details from a JSON file. - Create the template for the detail view.
- Use
- Add CSS styles to make the phone detail page look "pretty-ish".
- Implement a custom
checkmark
filter. - Update the
phoneDetail
template to use thecheckmark
filter. - Add a unit test for the
checkmark
filter.
- Make the thumbnail images in the phone detail view clickable:
- Introduce a
mainImageUrl
property onPhoneDetailController
. - Implement the
setImage()
method for changing the main image. - Use
ngClick
on the thumbnails to register a handler that changes the main image. - Add an end-to-end test for this feature.
- Introduce a
- Replace
$http
with$resource
. - Create a custom
Phone
service that represents the RESTful client. - Use a custom Jasmine equality tester in unit tests to ignore irrelevant properties.
- Add animations to the application:
- Animate changes to the phone list, adding, removing and reordering phones with
ngRepeat
. - Animate view transitions with
ngView
. - Animate changes to the main phone image in the phone detail view.
- Animate changes to the phone list, adding, removing and reordering phones with
- Showcase three different kinds of animations:
- CSS transition animations.
- CSS keyframe animations.
- JavaScript-based animations.
The following docs describe how you can test and develop this application further.
The application relies upon various Node.js tools, such as Bower, Karma and Protractor. You can install these by running:
npm install
This will also run Bower, which will download the Angular files needed for the current step of the tutorial.
Most of the scripts described below will run this automatically but it doesn't do any harm to run it whenever you like.
- Run
npm start
. - Navigate your browser to http://localhost:8000/ to see the application
- running.
We recommend using Jasmine and Karma for your unit tests/specs, but you are free to use whatever works for you.
- Start Karma with
npm test
. - A browser will start and connect to the Karma server. Chrome and Firefox are the default browsers,
others can be captured by loading the same URL or by changing the
karma.conf.js
file. - Karma will sit and watch your application and test JavaScript files. To run or re-run tests just change any of your these files.
We recommend using Protractor for end-to-end (e2e) testing.
It requires a webserver that serves the application. See the Running the Application during Development section, above.
- Serve the application with:
npm start
- In a separate terminal/command line window run the e2e tests:
npm run protractor
. - Protractor will execute the e2e test scripts against the web application itself. The project is
set up to run the tests on Chrome directly. If you want to run against other browsers, you must
modify the configuration at
e2e-tests/protractor-conf.js
.
app/ --> all the source code of the app (along with unit tests)
bower_components/... --> 3rd party JS/CSS libraries, including Angular and jQuery
core/ --> all the source code of the core module (stuff used throughout the app)
checkmark/... --> files for the `checkmark` filter, including JS source code, specs
phone/... --> files for the `core.phone` submodule, including JS source code, specs
core.module.js --> the core module
img/... --> image files
phone-detail/... --> files for the `phoneDetail` module, including JS source code, HTML templates, specs
phone-list/... --> files for the `phoneList` module, including JS source code, HTML templates, specs
phones/... --> static JSON files with phone data (used to fake a backend API)
app.animations.css --> hooks for running CSS animations with `ngAnimate`
app.animations.js --> hooks for running JS animations with `ngAnimate`
app.config.js --> app-wide configuration of Angular services
app.css --> default stylesheet
app.module.js --> the main app module
index.html --> app layout file (the main HTML template file of the app)
e2e-tests/ --> config and source files for e2e tests
protractor.conf.js --> config file for running e2e tests with Protractor
scenarios.js --> e2e specs
node_modules/... --> development tools (fetched using `npm`)
scripts/ --> handy scripts
private/... --> private scripts used by the Angular Team to maintain this repo
update-repo.sh --> script for pulling down the latest version of this repo (!!! DELETES ALL CHANGES YOU HAVE MADE !!!)
bower.json --> Bower specific metadata, including client-side dependencies
karma.conf.js --> config file for running unit tests with Karma
package.json --> Node.js specific metadata, including development tools dependencies
For more information on AngularJS, please check out https://angularjs.org/.