/angular-phonecat

Tutorial on building an angular application.

Primary LanguageJavaScript

AngularJS Phone Catalog Tutorial Application

Overview

This application takes the developer thought the process of building a web-application using angular. The application is loosely based on Google phone gallery. Each commit is a separate lesson teaching a single aspect of angular.

Prerequisites

Git

  • A good place to learn about setting up git is here
  • Git home (download, documentation)

Node.js

Java

Workings of the application

  • The application filesystem layout structure is based on the angular-seed project.
  • There is no backend (no server) for this application. Instead we fake the XHRs by fetching static json files.
  • Read the Development section at the end to familiarize yourself with running and developing an angular application.

Commits / Tutorial Outline

You can check out any point of the tutorial using git checkout step-?

To see the changes which between any two lessons use the git diff command. git diff step-?..step-?

step-0

step-1

  • We have converted the seed application by removing all of the boiler-plate code.
  • We have added single static HTML file which shows a static list of phones. (we will convert this static page into dynamic one with the help of angular)

step-2

  • Converted static page into dynamic one by:
    • create a root controller for the application
    • extracting the data from HTML into a the controller as a mock dataset
    • convert the static document into a template with the use of ng: directive (iterate over mock data using ng:repeat and render it into a view)
  • Added unit test, which mostly shows how one goes about writing a unit test, rather then test something of value on our mock dataset.

step-3

  • added a search box to demonstrate how:
    • the data-binding works on input fields
    • to use $filter function
    • ng:repeat automatically shrinks and grows the number of phones in the view
  • added an end-to-end test to:
    • show how end-to-end tests are written and used
    • to prove that the search box and the repeater are correctly wired together

step-4

step-5

  • adding phone image and links to phone pages
  • css to style the page just a notch

step-6

  • making the order predicate for catalog dynamic
    • adding 'predicates' section to the view with links that control the order
    • ordering defaults to 'age' property
  • css sugar

step-7

  • Introduce the [$route] service which allows binding URLs for deep-linking with views
    • Replace content of root controller PhonesCtrl with [$route] configuration
    • Map `/phones' to PhoneListCtrl and partails/phones-list.html
    • Map `/phones/phone-id' to PhoneDetailCtrl and partails/phones-detail.html
    • Copy deep linking parameters to root controller params property for access in sub controllers
    • Replace content of index.html with ng:view
  • Create PhoneListCtrl view
    • Move code which fetches phones data into PhoneListCtrl
    • Move existing HTML from index.html to partials/phone-list.html
  • Create PhoneDetailsCtrl view
    • Wire [$route] service to map /phanes/phone-id to map to this controller.
    • Empty PhoneDetailsCtrl
    • Place holder partials/phane-details.html

step-8

  • Fetch data for and render phone detail view
    • $xhr to fetch details for a specific phone
    • template for the phone detailed view
  • CSS to make it look pretty
  • Detail data for phones in JSON format

step-9

Development with angular-seed

The following docs apply to all angular-seed projects and since the phonecat tutorial is a project based on angular-seed, the instructions apply to it as well.

Running the app during development

  1. run ./scripts/web-server.js
  2. navigate your browser to http://localhost:8000/app/index.html to see the app running in your browser.

Running unit tests

Requires java.

  1. start ./scripts/test-server.sh (on windows scripts\test-server.bat)
  2. navigate your browser to http://localhost:9876/
  3. click on: capture strict link
  4. run scripts/test.sh (on windows scripts\test.bat)
  5. edit files in app/ or src/ and save them
  6. go to step 4.

Continuous unit testing

Requires ruby and watchr gem.

  1. start JSTD server and capture a browser as described above
  2. start watchr with watchr scripts/watchr.rb
  3. in a different window/tab/editor tail -f logs/jstd.log
  4. edit files in app/ or src/ and save them
  5. watch the log to see updates

End to end testing

angular ships with a baked-in end-to-end test runner that understands angular, your app and allows you to write your tests with jasmine-like BDD syntax.

Requires a webserver, node.js or your backend server that hosts the angular static files.

Check out the end-to-end runner's documentation for more info.

  • create your end-to-end tests in test/e2e/scenarios.js
  • serve your project directory with your http/backend server or node.js + scripts/web-server.js
  • open http://localhost:port/test/e2e/runner.html in your browser

Application Directory Layout

app/                --> all of the files to be used in production
  css/              --> css files
    app.css         --> default stylesheet
  img/              --> image files
  index.html        --> app layout file (the main html template file of the app)
  js/               --> javascript files
    controllers.js  --> application controllers
    filters.js      --> custom angular filters
    services.js     --> custom angular services
    widgets.js      --> custom angular widgets
  lib/              --> angular and 3rd party javascript libraries
    angular/
      angular.js            --> the latest angular js
      angular.min.js        --> the latest minified angular js
      angular-*.js  --> angular add-on modules
      version.txt           --> version number
  partials/         --> angular view partials (partial html templates)

config/jsTestDriver.conf    --> config file for JsTestDriver

logs/               --> JSTD and other logs go here (git-ignored)

scripts/            --> handy shell/js/ruby scripts
  test-server.bat   --> starts JSTD server (windows)
  test-server.sh    --> starts JSTD server (*nix)
  test.bat          --> runs all unit tests (windows)
  test.sh           --> runs all unit tests (*nix)
  watchr.rb         --> config script for continuous testing with watchr
  web-server.js     --> simple development webserver based on node.js

test/               --> test source files and libraries
  e2e/              -->
    runner.html     --> end-to-end test runner (open in your browser to run)
    scenarios.js    --> end-to-end specs
  lib/
    angular/                --> angular testing libraries
      angular-mocks.js      --> mocks that replace certain angular services in tests
      angular-scenario.js   --> angular's scenario (end-to-end) test runner library
      version.txt           --> version file
    jasmine/                --> Pivotal's Jasmine - an elegant BDD-style testing framework
    jasmine-jstd-adapter/   --> bridge between JSTD and Jasmine
    jstestdriver/           --> JSTD - JavaScript test runner
  unit/                     --> unit level specs/tests
    controllersSpec.js      --> specs for controllers

Contact

For more information on angular please check out http://angularjs.org/