X Tutup
Skip to content

Commit 6181ca6

Browse files
IgorMinarIgorMinar
committed
new batch of tutorial docs
1 parent 11e9572 commit 6181ca6

File tree

13 files changed

+1900
-1588
lines changed

13 files changed

+1900
-1588
lines changed

‎docs/content/tutorial/index.ngdoc‎

Lines changed: 42 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,109 +1,80 @@
1-
@workInProgress
21
@ngdoc overview
32
@name Tutorial
43
@description
54

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

13-
This tutorial app ends up like a Google phone gallery app, but is originally based on the {@link
14-
https://github.com/angular/angular-seed angular-seed project}. The angular seed app isn't
15-
necessary for building angular apps, but it helps you get started quickly and makes the
16-
development and testing process much easier. Angular-seed includes a simple example, the latest
17-
angular libraries, test libraries, and scripts. It provides all of these in an environment that
18-
is pre-configured for developing a typical web app.
12+
The starting point for our tutorial is the {@link https://github.com/angular/angular-seed
13+
angular-seed project}.
1914

20-
Once you set up your tutorial environment, you should be able to get through the material in less
21-
than a day and you'll have fun doing it. More experienced coders may be able to zip through the
22-
exercises in an afternoon. In any case, we promise that your time will be well spent!
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:
18+
19+
* Removed the example app
20+
* Added phone images to `app/img/phones`
21+
* Added phone data files (JSON) to `app/phones`
22+
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.
2325

2426
When you finish the tutorial you will be able to:
2527

2628
* Create a simple dynamic application that works in any browser
2729
* Define the differences between angular and common JavaScript frameworks
28-
* Understand angular expressions
2930
* Understand how data binding works in angular
3031
* Use the angular-seed project to quickly boot-strap your own projects
3132
* Create and run tests
3233
* Identify resources for learning more about angular
3334

34-
You can work through the tutorial in any of the following ways:
35-
36-
* <a href="#UsingGit">Using Git</a>. Use the Git versioning system to get the files for each step.
37-
* <a href="#UsingSnapshots">Using Snapshots</a>. Download snapshots (files for each step of the
38-
tutorial) and tinker with them.
39-
* <a href="#ReadingExamples">Reading the Examples</a>. Read through the examples, and inspect
40-
results and code on our server.
35+
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.
4138

42-
The first two ways (Git and snapshots) give you a fuller experience, in that you can run the unit
43-
and end-to-end tests in addition to the tutorial app. They also give you the ability to play
44-
around with the code and get instant feedback in your browser. The last way (reading through the
45-
tutorial online) requires no setup on your machine, but you can't run the tests, and it won't be
46-
as easy to play around with the code.
39+
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!
4741

4842
<a name="PreReqs"></a>
49-
# Prerequisites for Git and Snapshots
43+
# Prerequisites
5044

51-
To run the tutorial app and tests on your machine (using Git or the snapshots) you will need the
52-
following:
45+
To run the tutorial app and tests on your machine you will need the following:
5346

54-
* You need to be running on a Mac or Linux machine.
47+
* A Mac or Linux machine (required by the tutorial scripts, not angular)
5548
* An http server running on your system. If you don't already have one installed, you can install
5649
`node.js` ({@link https://github.com/joyent/node/wiki/Installation node.js install}) or another
5750
http sever (such as Apache, etc.).
58-
* Java. This is required for running tests. Angular itself doesn't require Java.
59-
* A modern browser (including IE8+). Needed for viewing and debugging code.
60-
* A text editor of your choice.
51+
* Java. This is only required for if you want to run tests via JsTestDriver.
52+
* A web browser.
53+
* A text editor.
6154

62-
<a name="UsingGit"></a>
6355
# Using Git
6456

65-
The following instructions are for developers who are comfortable with Git's versioning system:
57+
The following instructions are for developers who are comfortable with Git versioning system:
6658

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

6961
2. Clone the angular-phonecat repository located at {@link
7062
https://github.com/angular/angular-phonecat angular-phonecat} by running the following command in
7163
a terminal:
7264

73-
git clone git://github.com/angular/angular-phonecat.git
74-
75-
This will create a directory called `angular-phonecat`.
76-
77-
3. In terminal, navigate to the `angular-phonecat` directory and run:
65+
git clone git://github.com/angular/angular-phonecat.git
7866

79-
git checkout step-0
67+
This will create a directory called `angular-phonecat` in the current directory.
8068

81-
(You can run `git checkout step-[0-11]` to go to any of the steps in the tutorial).
69+
3. Change your current directory to `angular-phonecat`.
8270

83-
4. To see the app running in a browser, do the following:
84-
* __For node.js users:__
85-
1. Run `./scripts/web-server.js` to start the app server.
86-
2. Open a browser window for the app and navigate to http://localhost:8000/app/index.html.
71+
cd angular-phonecat
8772

88-
* __For other http servers:__
89-
1. Configure the server to serve the files in the `angular-phonecat` directory.
90-
2. Run `./scripts/web-server.js` to start the app server.
91-
3. Navigate in your browser to
92-
http://localhost:[*port-number*]/[*context-path*]/app/index.html.
73+
The tutorial instructions assume you are running all commands from this directory.
9374

94-
5. To see tests running in a browser, do the following:
95-
* __For node.js users:__
96-
1. Run `./scripts/test-server.sh` to start the test web server.
97-
2. Open a browser window for the tests, navigate to http://localhost:9876, and choose
98-
"strict mode".
99-
* __For other http servers:__
100-
1. Configure the server to serve the files in the `angular-phonecat` directory.
101-
1. Run `./scripts/test-server.sh` to start the test web server.
102-
3. Navigate in your browser to http://localhost:[*port-number*]/, and choose "strict mode".
75+
Read the Tutorial Navigation section, then navigate to Step 0.
10376

10477

105-
106-
<a name="UsingSnapshots"></a>
10778
# Using Snapshots
10879

10980
Snapshots are the sets of files that reflect the state of the tutorial app at each step. These
@@ -113,60 +84,18 @@ knowledge of Git. You can download and install the snapshot files as follows:
11384

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

116-
2. Navigate to [*the angular server*], and download and unzip [*the snapshot file*] to an
117-
[*install-dir*] of your choosing.
87+
2. Navigate to [*the angular server*], download and then unzip [*the snapshot file*] to an
88+
[*install-dir*].
11889

11990
3. Change directories to [*install-dir*]/sandbox.
12091

121-
4. Run the following command:
122-
* `./goto_step.sh 0`
123-
124-
You have to start out at the beginning, which is Step 0. After you set up Step 0, you can skip
125-
around between any steps.
126-
127-
1. To see the app running in your browser, do the following:
128-
* __For node.js users:__
129-
1. Run `./scripts/web-server.js` to run the web server.
130-
2. Open a browser window for the app and navigate to http://localhost:8000/app/index.html.
131-
3. Open a browser window for the tests, navigate to http://localhost:9876, and choose
132-
"strict mode".
133-
134-
* __For other http servers:__
135-
1. Configure servers to serve the app and test files in the [*install-dir*]/sandbox.
136-
2. Start the server.
137-
3. Navigate in your app browser to
138-
http://localhost:[*port-number*]/[*context-path*]/app/index.html.
139-
4. Navigate in your test browser to http://localhost:[*port-number*] and choose "strict
140-
mode".
141-
142-
1. To view the tutorial app at different steps, run `./goto_step.sh [0-11]` and then refresh your
143-
browser. For example, say you're on Step 5 of the tutorial, and you want to see the app in action:
144-
145-
1. Run `goto_step.sh 5` from the command line in the `sandbox` directory.
146-
1. Refresh your app browser.
147-
148-
<a name="ReadingExamples"></a>
149-
# Reading the Examples
150-
151-
If you don't want to set up anything on your local machine, you can read through the tutorial and
152-
inspect the tutorial files on our servers; doing this will give you a good idea of what angular
153-
does, but you won't be able to make any code changes and experiment on your own.
154-
155-
To see the running app at each tutorial step, click the "Example" link at the top or bottom of
156-
each tutorial page.
157-
158-
To view the code differences between tutorial steps, click the Code Diff link at top or bottom of
159-
each tutorial page. Additions are highlighted in green; deletions are highlighted in red.
160-
161-
162-
# Relative URLs
163-
Throughout the tutorial, we use relative URLs to refer to files hosted on our local http server.
164-
The absolute URL depends on your configuration. For example, if you are using the node.js server,
165-
`app/index.html` translates to:
92+
cd [*install-dir*]/sandbox
16693

167-
http://localhost:8000/app/index.html
94+
Read the Tutorial Navigation section, then navigate to step-0.
16895

169-
If you are using your own http server running on port 8080 and the tutorial files are hosted at
170-
`/angular_tutorial`, `app/index.html` translates to:
96+
# Tutorial Navigation
17197

172-
http://localhost:8080/angular_tutorial/app/index.html
98+
To see the app running on the angular server, click the "Live Demo" link at the top or bottom of
99+
any tutorial page. To view the code differences between tutorial steps, click the Code Diff link
100+
at top or bottom of each tutorial page. In the Code Diff, additions are highlighted in green;
101+
deletions are highlighted in red.

‎docs/content/tutorial/step_00.ngdoc‎

Lines changed: 90 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,90 @@
1-
@workInProgress
2-
@ngdoc overview
3-
@name Tutorial: Step 0
4-
@description
5-
6-
<table id="tutorial_nav">
7-
<tr>
8-
<td id="previous_step">{@link tutorial Previous}</td>
9-
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-0/app Example}</td>
10-
<td id="tut_home">{@link tutorial Tutorial Home}</td>
11-
<td id="code_diff">Code Diff</td>
12-
<td id="next_step">{@link tutorial.step_01 Next}</td>
13-
</tr>
14-
</table>
15-
16-
The following sample code is our starting point. It is a static HTML page that displays next to
17-
nothing, but it has everything we need to proceed. You can think of this bit of code as our
18-
prototype template, consisting of basic HTML tags with a pair of angular specific attributes.
19-
20-
__`app/index.html`:__
21-
<pre>
22-
<!doctype html>
23-
<html xmlns:ng="http://angularjs.org/">
24-
<head>
25-
<meta charset="utf-8">
26-
<title>my angular app</title>
27-
<link rel="stylesheet" href="css/app.css"/>
28-
</head>
29-
<body>
30-
31-
Nothing here yet!
32-
33-
<script src="lib/angular/angular.js" ng:autobind></script>
34-
</body>
35-
</html>
36-
</pre>
37-
38-
## Discussion:
39-
40-
Although our app doesn't appear to do anything dynamic, note the following:
41-
42-
* __... `xmlns:ng="http://angularjs.org"` ...__ This `xmlns` declaration for the `ng` namespace
43-
must be specified if you use XHTML, or if you are targeting IE older than 9 (regardless of whether
44-
you are using XHTML or HTML).
45-
46-
* __`<script src="lib/angular/angular.js"` ...__ This downloads the `angular.js` script and
47-
registers a callback that will be executed by the browser when the containing HTML page is fully
48-
downloaded. When the callback is executed, angular looks for the {@link
49-
angular.directive.ng:autobind ng:autobind} attribute. If `ng:autobind` is found, it signals
50-
angular to bootstrap and compile and manage the whole html page.
51-
52-
Note: If you elected not to download any tutorial files but still want to try out some angular
53-
code on your system, you can change the relative path to the `angular.js` script in your
54-
template from `./lib/angular/angular.js` to the following:
55-
56-
<script src="http://code.angularjs.org/angular-0.9.14.js" ng:autobind></script>
57-
58-
This will download the angular script from the angular server instead of from a local file.
59-
60-
* To try this code out in your browser, you need to navigate to the step-0 page (you are currently
61-
on Step 0 of the tutorial). If your http server is running, navigate to `app/index.html`.
62-
Remember, this is a relative URL (see the Relative URL section in {@link tutorial Tutorial}). The
63-
browser will display the same thing as you would see if you go to
64-
http://angular.github.com/angular-phonecat/step-0/app (accessible from Example link at the bottom
65-
of the page).
66-
67-
Now we can move on and add some content to our developing web app.
68-
69-
<table id="tutorial_nav">
70-
<tr>
71-
<td id="previous_step">{@link tutorial Previous}</td>
72-
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-0/app Example}</td>
73-
<td id="tut_home">{@link tutorial Tutorial Home}</td>
74-
<td id="code_diff">Code Diff</td>
75-
<td id="next_step">{@link tutorial.step_01 Next}</td>
76-
</tr>
77-
</table>
1+
@ngdoc overview
2+
@name Tutorial: Step 0
3+
@description
4+
5+
<table id="tutorial_nav">
6+
<tr>
7+
<td id="previous_step">{@link tutorial Previous}</td>
8+
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-0/app Live Demo}</td>
9+
<td id="tut_home">{@link tutorial Tutorial Home}</td>
10+
<td id="code_diff">Code Diff</td>
11+
<td id="next_step">{@link tutorial.step_0 Next}</td>
12+
</tr>
13+
</table>
14+
15+
You are now ready to build the phone cat application. In this step, you will become familiar with
16+
the most important source code files, learn how to start the web services, and run the application
17+
in the browser.
18+
19+
1. Do one of the following:
20+
21+
* Git users: In the `angular-phonecat` directory, run this command:
22+
23+
git checkout step-0
24+
25+
* Snapshot users: In the `[install directory]/sandbox` directory, run this command:
26+
27+
./goto_step.sh 0
28+
29+
This resets your workspace to Step 0 of the tutorial app.
30+
31+
2. To see the app running in a browser, do one of the following:
32+
* __For node.js users:__
33+
1. In a _separate_ terminal tab or window, run `./scripts/web-server.js` to start the app
34+
server.
35+
2. Open a browser window for the app and navigate to http://localhost:8000/app/index.html.
36+
37+
* __For other http servers:__
38+
1. Configure the server to serve the files in the `angular-phonecat` directory.
39+
2. Run `./scripts/web-server.js` to start the app server.
40+
3. Navigate in your browser to
41+
http://localhost:[*port-number*]/[*context-path*]/app/index.html.
42+
43+
You can now see the app in the browser. It's not very exciting, but that's OK.
44+
45+
The code that created this app is shown below. You will see that it creates a static HTML page
46+
that displays "Nothing here yet!"; the code does, however, have everything we need to proceed.
47+
This bit of code serves as a prototype template, consisting of basic HTML tags with a pair of
48+
angular-specific attributes.
49+
50+
__`app/index.html`:__
51+
<pre>
52+
<!doctype html>
53+
<html xmlns:ng="http://angularjs.org/">
54+
<head>
55+
<meta charset="utf-8">
56+
<title>my angular app</title>
57+
<link rel="stylesheet" href="css/app.css"/>
58+
</head>
59+
<body>
60+
61+
Nothing here yet!
62+
63+
<script src="lib/angular/angular.js" ng:autobind></script>
64+
</body>
65+
</html>
66+
</pre>
67+
68+
## What is the code doing?
69+
70+
* __... `xmlns:ng="http://angularjs.org"` ...__ This `xmlns` declaration for the `ng` namespace
71+
must be specified in all angular applications if you use XHTML, or if you are targeting IE
72+
versions older than 9 (regardless of whether you are using XHTML or HTML).
73+
74+
* __`<script src="lib/angular/angular.js"` ...__ This downloads the `angular.js` script and
75+
registers a callback that will be executed by the browser when the containing HTML page is fully
76+
downloaded. When the callback is executed, angular looks for the {@link
77+
angular.directive.ng:autobind ng:autobind} attribute. If `ng:autobind` is found, it signals
78+
angular to bootstrap and compile and manage the whole html page.
79+
80+
Now let's go to Step 1 and add some content to the web app.
81+
82+
<table id="tutorial_nav">
83+
<tr>
84+
<td id="previous_step">{@link tutorial Previous}</td>
85+
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-0/app Live Demo}</td>
86+
<td id="tut_home">{@link tutorial Tutorial Home}</td>
87+
<td id="code_diff">Code Diff</td>
88+
<td id="next_step">{@link tutorial.step_01 Next}</td>
89+
</tr>
90+
</table>

0 commit comments

Comments
 (0)
X Tutup