angular · Oct 18, 2012 · Oct 18, 2012 · Oct 18, 2012 · Oct 18, 2012 · Oct 18, 2012
diff --git a/README.md b/README.md
@@ -1,67 +1,162 @@
-# angular-seed — the seed for AngularJS apps
+# AngularJS Phone Catalog Tutorial Application
 
-This project is an application skeleton for a typical [AngularJS](http://angularjs.org/) web app.
-You can use it to quickly bootstrap your angular webapp projects and dev environment for these
-projects.
+## Overview
 
-The seed contains AngularJS libraries, test libraries and a bunch of scripts all preconfigured for
-instant web development gratification. Just clone the repo (or download the zip/tarball), start up
-our (or yours) webserver and you are ready to develop and test your application.
+This application takes the developer thought the process of building a web-application using
+angular. The application is loosely based on
+[Google phone gallery](http://www.google.com/phone/). Each commit is a separate lesson
+teaching a single aspect of angular.
 
-The seed app doesn't do much, just shows how to wire two controllers and views together. You can
-check it out by opening app/index.html in your browser (might not work file `file://` scheme in
-certain browsers, see note below).
 
-_Note: While angular is client-side-only technology and it's possible to create angular webapps that
-don't require a backend server at all, we recommend hosting the project files using a local
-webserver during development to avoid issues with security restrictions (sandbox) in browsers. The
-sandbox implementation varies between browsers, but quite often prevents things like cookies, xhr,
-etc to function properly when an html page is opened via `file://` scheme instead of `http://`._
+## Prerequisites
 
+### Git
+- A good place to learn about setting up git is [here][git-github]
+- Git [home][git-home] (download, documentation)
 
-## How to use angular-seed
+### Node.js
+- Generic [installation instructions][node-generic].
+- Mac DMG [here][node-mac]
+- Windows download from [here][node-windows]. (You will also need [7 Zip] to unzip the node archive)
+  (and don't forget to add `node.exe` to  your executable path)
 
-Clone the angular-seed repository and start hacking...
+### Java
+- http://www.java.com
 
+## Workings of the application
 
-### Running the app during development
+- 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
+
+- Initial [angular-seed] project layout
+
+
+### 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
+
+- replaced the mock data with data loaded from the server (in our case the JSON return is just a
+  static file)
+  - The JSON is loaded using the [$xhr] service
+- Demonstrate the use of [services][service] and [dependency injection][DI]
+  - The [$xhr] is injected into the controller through [dependency injection][DI]
 
-You can pick one of these options:
 
-* serve this repository with your webserver
-* install node.js and run `scripts/web-server.js`
+### step-5
 
-Then navigate your browser to `http://localhost:<port>/app/index.html` to see the app running in
-your browser.
+- adding phone image and links to phone pages
+- css to style the page just a notch
 
 
-### Running the app in production
+### step-6
 
-This really depends on how complex is your app and the overall infrastructure of your system, but
-the general rule is that all you need in production are all the files under the `app/` directory.
-Everything else should be omitted.
+- 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
 
-Angular apps are really just a bunch of static html, css and js files that just need to be hosted
-somewhere, where they can be accessed by browsers.
 
-If your Angular app is talking to the backend server via xhr or other means, you need to figure
-out what is the best way to host the static files to comply with the same origin policy if
-applicable. Usually this is done by hosting the files by the backend server or through
-reverse-proxying the backend server(s) and a webserver(s).
+### 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
+
+- replace [$xhr] with [$resource]
+  - demonstrate how a resource can be created using a [service]
+
+## 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
 
-We recommend using [jasmine](http://pivotal.github.com/jasmine/) and
-[Testacular](http://vojtajina.github.com/testacular/) for your unit tests/specs, but you are free
-to use whatever works for you.
+Requires java.
 
-Requires [node.js](http://nodejs.org/), Testacular (`sudo npm install -g testacular`) and a local
-or remote browser.
+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.
 
-* start `scripts/test.sh` (on windows: `scripts\test.bat`)
-  * a browser will start and connect to the Testacular server (Chrome is default browser, others can be captured by loading the same url as the one in Chrome or by changing the `config/testacular.conf.js` file)
-* to run or re-run tests just change any of your source or test javascript files
+
+### Continuous unit testing
+
+Requires ruby and [watchr](https://github.com/mynyml/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
@@ -82,14 +177,7 @@ info.
   * run the tests from console with [Testacular](vojtajina.github.com/testacular) via
     `scripts/e2e-test.sh` or `script/e2e-test.bat`
 
-
-### Receiving updates from upstream
-
-When we upgrade angular-seed's repo with newer angular or testing library code, you can just
-fetch the changes and merge them into your project with git.
-
-
-## Directory Layout
+## Application Directory Layout
 
     app/                --> all of the files to be used in production
       css/              --> css files
@@ -141,3 +229,21 @@ fetch the changes and merge them into your project with git.
 ## Contact
 
 For more information on AngularJS please check out http://angularjs.org/
+
+[7 Zip]: http://www.7-zip.org/
+[angular-seed]: https://github.com/angular/angular-seed
+[DI]: http://docs.angularjs.org/#!guide.di
+[directive]: http://docs.angularjs.org/#!angular.directive
+[$filter]: http://docs.angularjs.org/#!angular.Array.filter
+[git-home]: http://git-scm.com
+[git-github]: http://help.github.com/set-up-git-redirect
+[ng:repeat]: http://docs.angularjs.org/#!angular.widget.@ng:repeat
+[ng:view]: http://docs.angularjs.org/#!angular.widget.ng:view
+[node-mac]: http://code.google.com/p/rudix/downloads/detail?name=node-0.4.0-0.dmg&can=2&q=
+[node-windows]: http://node-js.prcn.co.cc/
+[node-generic]: https://github.com/joyent/node/wiki/Installation
+[java]: http://www.java.com
+[$resource]: http://docs.angularjs.org/#!angular.service.$resource
+[$rouet]: http://docs.angularjs.org/#!angular.service.$route
+[service]: http://docs.angularjs.org/#!angular.service
+[$xhr]: http://docs.angularjs.org/#!angular.service.$xhr
diff --git a/app/css/app.css b/app/css/app.css
@@ -1,30 +1,84 @@
 /* app css stylesheet */
 
-.menu {
+body {
+  padding-top: 20px;
+}
+
+.phones {
   list-style: none;
-  border-bottom: 0.1em solid black;
+}
+
+.thumb {
+  float: left;
+  margin: -1em 1em 1.5em 0em;
+  padding-bottom: 1em;
+  height: 100px;
+  width: 100px;
+}
+
+.phones li {
+  clear: both;
+  height: 100px;
+  padding-top: 15px;
+}
+
+/** Detail View **/
+img.phone {
+  float: left;
+  border: 1px solid black;
+  margin-right: 3em;
   margin-bottom: 2em;
-  padding: 0 0 0.5em;
+  background-color: white;
+  padding: 2em;
+  height: 400px;
+  width: 400px;
 }
 
-.menu:before {
-  content: "[";
+ul.phone-thumbs {
+  margin: 0;
+  list-style: none;
 }
 
-.menu:after {
-  content: "]";
+ul.phone-thumbs li {
+  border: 1px solid black;
+  display: inline-block;
+  margin: 1em;
+  background-color: white;
 }
 
-.menu > li {
-  display: inline;
+ul.phone-thumbs img {
+  height: 100px;
+  width: 100px;
+  padding: 1em;
 }
 
-.menu > li:before {
-  content: "|";
-  padding-right: 0.3em;
+ul.phone-thumbs img:hover {
+  cursor: pointer;
 }
 
-.menu > li:nth-child(1):before {
-  content: "";
+
+ul.specs {
+  clear: both;
+  margin: 0;
   padding: 0;
+  list-style: none;
+}
+
+ul.specs > li{
+  display: inline-block;
+  width: 200px;
+  vertical-align: top;
+}
+
+ul.specs > li > span{
+  font-weight: bold;
+  font-size: 1.2em;
+}
+
+ul.specs dt {
+  font-weight: bold;
+}
+
+h1 {
+  border-bottom: 1px solid gray;
 }