Skip to content

Commit 3751f17

Browse files
IgorMinarIgorMinar
committed
add new batch of tutorial docs and images
1 parent 3776e08 commit 3751f17

22 files changed

Lines changed: 1082 additions & 359 deletions

‎docs/content/tutorial/index.ngdoc‎

Lines changed: 69 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -2,105 +2,133 @@
22
@name Tutorial
33
@description
44

5-
A great way to get introduced to angular is to work through the {@link tutorial.step_00 angular
6-
tutorial}, which walks you through the construction of an angular web app. The app you will build
7-
in the tutorial is loosely based on the {@link http://www.google.com/phone/ Google phone gallery
8-
app}. The {@link http://angular.github.com/angular-phonecat/step-11/app/#/phones end result of our
9-
effort} is visually simpler, but demonstrates many of the angular features without distractions in
10-
the form of CSS code.
115

12-
The starting point for our tutorial is the {@link https://github.com/angular/angular-seed
13-
angular-seed project}.
6+
A great way to get introduced to angular is to work through this tutorial, which walks you through
7+
the construction of an angular web app. The app you will build is a catalog that displays a list of
8+
Android devices, lets you filter the list to see only devices that interest you, and then view
9+
details for any device.
1410

15-
The angular-seed project includes a simple example app, the latest angular libraries, test
16-
libraries, and scripts. It provides all of these in an environment that is pre-configured for
17-
developing a typical web app. For this tutorial, we modified the angular-seed as follows:
1811

19-
* Removed the example app
20-
* Added phone images to `app/img/phones`
21-
* Added phone data files (JSON) to `app/phones`
12+
<img src="img/tutorial/catalog_screen.png">
13+
14+
15+
As you work through this tutorial, you will learn how angular makes browsers smarter — without the
16+
use of extensions or plugins.
17+
18+
19+
* You will see examples of how to use client-side data binding and dependency injection to build
20+
dynamic views of data that change immediately in response to user actions.
21+
* You will see how Angular creates listeners on your data without the need for DOM manipulation.
22+
* You will learn a better, easier way to test your web apps.
23+
* You will learn how to use Angular services to make common web tasks, such as getting data into
24+
your app, easier.
25+
26+
27+
And all of this works in any browser without modifications!
2228

23-
**Note**: Using the angular seed app isn't required for building angular apps, but doing so helps
24-
you get started quickly and makes the development and testing process much easier.
2529

2630
When you finish the tutorial you will be able to:
2731

28-
* Create a simple dynamic application that works in any browser
32+
33+
* Create a dynamic application that works in any browser
2934
* Define the differences between angular and common JavaScript frameworks
3035
* Understand how data binding works in angular
3136
* Use the angular-seed project to quickly boot-strap your own projects
3237
* Create and run tests
3338
* Identify resources for learning more about angular
3439

40+
3541
Mac and Linux users can work through the tutorial, run tests, and experiment with the code using
36-
Git or the snapshots described below. Windows users will be able follow the tutorial and read
37-
through the source code and view the application running on our servers at different stages.
42+
Git or the snapshots described below. Windows users will be able read the tutorial but won't be
43+
able to run the tests or experiment with the code.
44+
3845

3946
You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day
40-
really digging into it. In any case, we promise that your time will be well spent!
47+
really digging into it. If you're looking for a shorter introduction to angular, check out {@link
48+
http://docs.angularjs.org/#!started started}.
49+
50+
51+
52+
53+
54+
55+
4156

4257
<a name="PreReqs"></a>
4358
# Prerequisites
4459

60+
4561
To run the tutorial app and tests on your machine you will need the following:
4662

47-
* A Mac or Linux machine (required by the tutorial scripts, not angular)
48-
* An http server running on your system. If you don't already have one installed, you can install
49-
`node.js` ({@link https://github.com/joyent/node/wiki/Installation node.js install guide}) or
50-
another http sever (such as Apache, etc.).
51-
* Java. This is required for running tests with JsTestDriver.
63+
64+
* A Mac or Linux machine (required for running the tutorial scripts)
65+
* An http server running on your system. Mac and Linux machines typically have Apache preinstalled.
66+
If you don't already have an http server installed, you can install `node.js` ({@link
67+
https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager node.js install guide})
68+
or another http sever.
69+
* {@link http://java.com Java}.
5270
* A web browser.
5371
* A text editor.
5472

5573

74+
75+
5676
# Working with the code
5777

78+
5879
There are two ways that you can you follow this tutorial and hack on the code:
5980

81+
6082
## Using Git
6183

62-
The following instructions are for developers who are comfortable with the Git versioning system:
84+
85+
The following instructions are for Git users. If you're not a Git user, skip down to the "Using
86+
Snapshots" section.
87+
6388

6489
1. Check to be sure you have all of the <a href="#PreReqs">prerequisites</a> on your system.
6590

91+
6692
2. Clone the angular-phonecat repository located at {@link
6793
https://github.com/angular/angular-phonecat GitHub} by running the following command in a terminal:
6894

95+
6996
git clone git://github.com/angular/angular-phonecat.git
7097

71-
This will create a directory called `angular-phonecat` in the current directory.
7298

73-
3. Change your current directory to `angular-phonecat`.
99+
This will create a directory called `angular-phonecat` in the current directory.
100+
101+
102+
3. Change your current directory to `angular-phonecat`.
103+
104+
105+
cd angular-phonecat
74106

75-
cd angular-phonecat
76107

77108
The tutorial instructions assume you are running all commands from this directory.
78109

79110

111+
112+
80113
## Using Snapshots
81114

82-
Snapshots are the sets of files that reflect the state of the tutorial app at each step. These
83-
files include the HTML, CSS, and JavaScript for the app, plus Jasmine JavaScript files and Java
84-
libraries for the test stack. These will let you run the tutorial app and tests, without requiring
85-
knowledge of Git. You can download and install the snapshot files as follows:
86115

87116
1. Check to be sure you have all of the <a href="#PreReqs">prerequisites</a> on your system.
88117

89-
2. {@link TODO Download the zip archive} with all files and unzip them into `[tutorial-dir]`
90-
directory.
118+
119+
2. {@link http://code.angularjs.org/angular-phonecat-snapshots.zip Download the zip archive} with
120+
all files and unzip them into `[tutorial-dir]` directory.
121+
122+
91123

92124

93125
3. Change directories to `[tutorial-dir]/sandbox`.
94126

127+
95128
cd [tutorial-dir]/sandbox
96129

97130

98-
# Tutorial Navigation
99131

100-
To see the app running on the angular server, click the "Live Demo" link at the top or bottom of
101-
any tutorial page. To view the code differences between tutorial steps, click the Code Diff link
102-
at top or bottom of each tutorial page. In the Code Diff, additions are highlighted in green;
103-
deletions are highlighted in red.
104132

133+
Let's get going with {@link tutorial/step_00 step 0}.
105134

106-
Let's get going and proceed to {@link tutorial/step_00 step 0}.

‎docs/content/tutorial/step_00.ngdoc‎

Lines changed: 89 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1-
@ngdoc overview
1+
@ngdoc overview
22
@name Tutorial: Step 0
33
@description
44

5+
56
<table id="tutorial_nav">
67
<tr>
78
<td id="previous_step">{@link tutorial Previous}</td>
@@ -12,39 +13,54 @@
1213
</tr>
1314
</table>
1415

16+
1517
You are now ready to build the phone cat application. In this step, you will become familiar with
1618
the most important source code files, learn how to start the development servers bundled with
1719
angular-seed, and run the application in the browser.
1820

21+
1922
1. Do one of the following:
2023

24+
2125
* Git users: In the `angular-phonecat` directory, run this command:
2226

23-
git checkout step-0
27+
28+
git checkout -f step-0
29+
2430

2531
* Snapshot users: In the `[tutorial-dir]/sandbox` directory, run this command:
2632

33+
2734
./goto_step.sh 0
2835

29-
This resets your workspace to Step 0 of the tutorial app.
36+
37+
This resets your workspace to Step 0 of the tutorial app.
38+
39+
40+
You must repeat this for every future step in the tutorial and change the number to the number of
41+
the step you are on. Either command will cause any changes you made within your working directory
42+
to be lost.
43+
3044

3145
2. To see the app running in a browser, do one of the following:
3246
* __For node.js users:__
3347
1. In a _separate_ terminal tab or window, run `./scripts/web-server.js` to start the app
34-
server.
48+
server.
3549
2. Open a browser window for the app and navigate to http://localhost:8000/app/index.html.
3650

51+
3752
* __For other http servers:__
3853
1. Configure the server to serve the files in the `angular-phonecat` directory.
3954
2. Navigate in your browser to
40-
http://localhost:[*port-number*]/[*context-path*]/app/index.html.
55+
http://localhost:[*port-number*]/[*context-path*]/app/index.html.
56+
57+
58+
You can now see the page in your browser. It's not very exciting, but that's OK.
4159

42-
You can now see the app in the browser. It's not very exciting, but that's OK.
4360

44-
The code that created this app is shown below. You will see that it creates a static HTML page
45-
that displays "Nothing here yet!"; the code does, however, have everything we need to proceed.
46-
This bit of code serves as a prototype template, consisting of basic HTML tags with a pair of
47-
angular-specific attributes.
61+
The static HTML page that displays "Nothing here yet!" was constructed with the HTML code shown
62+
below. The code contains some key angular elements that we will need going forward.
63+
4864

4965
__`app/index.html`:__
5066
<pre>
@@ -57,29 +73,84 @@ __`app/index.html`:__
5773
</head>
5874
<body>
5975

76+
6077
Nothing here yet!
6178

79+
6280
<script src="lib/angular/angular.js" ng:autobind></script>
6381
</body>
6482
</html>
6583
</pre>
6684

85+
86+
87+
88+
89+
6790
## What is the code doing?
6891

69-
* __... `xmlns:ng="http://angularjs.org"` ...__ This `xmlns` declaration for the `ng` namespace
70-
must be specified in all angular applications if you use XHTML, or if you are targeting IE
71-
versions older than 9 (regardless of whether you are using XHTML or HTML).
7292

73-
* __`<script src="lib/angular/angular.js"` ...__ This downloads the `angular.js` script and
74-
registers a callback that will be executed by the browser when the containing HTML page is fully
75-
downloaded. When the callback is executed, angular looks for the {@link
76-
angular.directive.ng:autobind ng:autobind} attribute. If `ng:autobind` is found, it signals
77-
angular to bootstrap, compile, and manage the whole html page.
93+
* xmlns declaration
94+
95+
96+
<html xmlns:ng="http://angularjs.org">
97+
98+
99+
This `xmlns` declaration for the `ng` namespace must be specified in all angular applications in
100+
order to make angular work with XHTML and IE versions older than 9 (regardless of whether you are
101+
using XHTML or HTML).
102+
103+
104+
* angular script tag
105+
106+
107+
<script src="lib/angular/angular.js" ng:autobind>
108+
109+
110+
This single line of code is all that is needed to bootstrap an angular application.
111+
112+
113+
The code downloads the `angular.js` script and registers a callback that will be executed by the
114+
browser when the containing HTML page is fully downloaded. When the callback is executed, angular
115+
looks for the {@link angular.directive.ng:autobind ng:autobind} attribute. If angular finds
116+
`ng:autobind`, it creates a root scope for the application and associates it with the `<html>`
117+
element of the template:
118+
119+
120+
<img src="img/tutorial/tutorial_00_final.png"/>
121+
122+
123+
As you will see shortly, everything in angular is evaluated within a scope. We'll learn more
124+
about this in the next steps.
125+
126+
127+
128+
129+
## What are all these files in my working directory?
130+
131+
132+
Most of the files in your working directory come from the {@link
133+
https://github.com/angular/angular-seed angular-seed project} which is typically used to bootstrap
134+
new angular projects. The seed project includes the latest angular libraries, test libraries,
135+
scripts and a simple example app, all pre-configured for developing a typical web app.
136+
137+
138+
For the purposes of this tutorial, we modified the angular-seed with the following changes:
139+
140+
141+
* Removed the example app
142+
* Added phone images to `app/img/phones`
143+
* Added phone data files (JSON) to `app/phones`
144+
145+
146+
78147

79148
# Summary
80149

150+
81151
Now let's go to step 1 and add some content to the web app.
82152

153+
83154
<table id="tutorial_nav">
84155
<tr>
85156
<td id="previous_step">{@link tutorial Previous}</td>

0 commit comments

Comments
 (0)