Skip to content

Commit 53b2254

Browse files
IgorMinarIgorMinar
committed
docs(tutorial): update tutorial intro + steps 0-3
also contains all kinds of fixes that I had to make in the docs app to get the tutorial to render correctly
1 parent 6336b6e commit 53b2254

30 files changed

Lines changed: 1293 additions & 2119 deletions

‎docs/content/tutorial/index.ngdoc‎

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22
@name Tutorial
33
@description
44

5-
A great way to get introduced to Angular is to work through this tutorial, which walks you through
5+
A great way to get introduced to AngularJS is to work through this tutorial, which walks you through
66
the construction of an AngularJS web app. The app you will build is a catalog that displays a list
77
of Android devices, lets you filter the list to see only devices that interest you, and then view
88
details for any device.
99

10-
<img src="img/tutorial/catalog_screen.png">
10+
<img src="img/tutorial/catalog_screen.png" width="488" height="413">
1111

1212
Work through the tutorial to see how Angular makes browsers smarter — without the use of extensions
1313
or plug-ins. As you work through the tutorial, you will:
@@ -72,9 +72,8 @@ directory.</p></li>
7272
directory.</p></li>
7373
<li><p>You will need an http server running on your system. Mac and Linux machines typically
7474
have Apache pre-installed, but If you don't already have one installed, you can <a
75-
href="https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager">install
76-
node.js</a>. Use <code>node</code> to run <code>scripts/web-server.js</code>, a simple bundled
77-
http server.</p></li>
75+
href="http://nodejs.org/#download">install node.js</a>. Use <code>node</code> to run
76+
<code>scripts/web-server.js</code>, a simple bundled http server.</p></li>
7877
</ol>
7978
</doc:tutorial-instruction>
8079

@@ -97,11 +96,10 @@ directory.</p>
9796
<p>You should run all <code>git</code> commands from msysGit bash.</p>
9897
<p>Other commands like <code>test-server.bat</code> or <code>test.bat</code> should be
9998
executed from the Windows command line.</li>
100-
<li><p>You need an http server running on your system. If you don't already have one
101-
installed, you can install <a href="http://nodejs.org/">node.js</a>. Download the <a
102-
href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them, and then add
103-
<code>nodejs\bin</code> into your <code>PATH</code>. Use <code>node</code> to run
104-
<code>scripts\web-server.js</code>, a simple, bundled http server.</p></li>
99+
<li><p>You need an http server running on your system, but if you don't already have one
100+
already installed, you can install <a href="http://nodejs.org/#download">node.js</a>. Make sure that
101+
<code>nodejs\bin</code> was added into your <code>PATH</code>. Use <code>node</code> to run
102+
<code>scripts\web-server.js</code>, a simple bundled http server.</p></li>
105103
</ol>
106104
</doc:tutorial-instruction>
107105

@@ -119,9 +117,8 @@ containing all of the files and unzip them into the [tutorial-dir] directory</p>
119117
<code>sandbox</code> directory.</p></li>
120118
<li><p>You need an http server running on your system and Mac and Linux machines typically
121119
have Apache pre-installed. If you don't have an http server installed, you can <a
122-
href="https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager">install
123-
node.js</a> and use it to run <code>scripts/web-server.js</code>, a simple bundled http
124-
server.</p></li>
120+
href="http://nodejs.org/#download">install node.js</a> and use it to run
121+
<code>scripts/web-server.js</code>, a simple bundled http server.</p></li>
125122
</ol>
126123
</doc:tutorial-instruction>
127124

@@ -138,13 +135,14 @@ and unzip the files into the [tutorial-dir] directory</p></li>
138135
<pre><code>cd [tutorial-dir]/sandbox</code></pre>
139136
<p>The tutorial instructions assume you are running all commands from this directory.</p></li>
140137
<li><p>You need an http server running on your system, but if you don't already have one
141-
already installed, you can install <a href="http://nodejs.org/">node.js</a>. Download the <a
142-
href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them, and then add
143-
<code>nodejs\bin</code> into your <code>PATH</code>. Use <code>node</code> to run
138+
already installed, you can install <a href="http://nodejs.org/#download">node.js</a>. Make sure that
139+
<code>nodejs\bin</code> was added into your <code>PATH</code>. Use <code>node</code> to run
144140
<code>scripts\web-server.js</code>, a simple bundled http server.</p></li>
145141
</ol>
146142
</doc:tutorial-instruction>
147143
</doc:tutorial-instructions>
148144

149145
The last thing to do is to make sure your computer has a web browser and a good text editor
150-
installed. Now, let's get going with {@link step_00 step 0}.
146+
installed. Now, let's get some cool stuff done!
147+
148+
{@link step_00 <span class="tutorial-start">Get Started!</span>}

‎docs/content/tutorial/step_00.ngdoc‎

Lines changed: 79 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
@ngdoc overview
2-
@name Tutorial: 0 - angular-seed
2+
@name Tutorial: 0 - Bootstrapping
33
@description
44

55
<ul doc:tutorial-nav="0"></ul>
66

77

8-
You are now ready to build the Angular phonecat application. In this step, you will become familiar
8+
You are now ready to build the AngularJS phonecat app. In this step, you will become familiar
99
with the most important source code files, learn how to start the development servers bundled with
1010
angular-seed, and run the application in the browser.
1111

@@ -143,23 +143,23 @@ href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html
143143

144144
You can now see the page in your browser. It's not very exciting, but that's OK.
145145

146-
The static HTML page that displays "Nothing here yet!" was constructed with the HTML code shown
147-
below. The code contains some key Angular elements that we will need going forward.
146+
The HTML page that displays "Nothing here yet!" was constructed with the HTML code shown below.
147+
The code contains some key Angular elements that we will need going forward.
148148

149149
__`app/index.html`:__
150150
<pre>
151151
<!doctype html>
152-
<html xmlns:ng="http://angularjs.org/" ng:app>
152+
<html ng-app>
153153
<head>
154154
<meta charset="utf-8">
155155
<title>my angular app</title>
156-
<link rel="stylesheet" href="css/app.css"/>
156+
<link rel="stylesheet" href="css/app.css">
157+
<script src="lib/angular/angular.js"></script>
157158
</head>
158159
<body>
159160

160-
Nothing here yet!
161+
Nothing here {{'yet' + '!'}}
161162

162-
<script src="lib/angular/angular.js"></script>
163163
</body>
164164
</html>
165165
</pre>
@@ -168,30 +168,70 @@ __`app/index.html`:__
168168

169169
## What is the code doing?
170170

171-
* xmlns declaration
171+
* `ng-app` directive:
172172

173-
<html xmlns:ng="http://angularjs.org" ng:app>
173+
<html ng-app>
174174

175-
This `xmlns` declaration for the `ng` namespace must be specified in all Angular applications in
176-
order to make Angular work with XHTML and IE versions older than 9 (regardless of whether you are
177-
using XHTML or HTML).
175+
`ng-app` directive is a special tag used to flag an element which Angular should consider to be
176+
the root element of our application. This gives application developers the freedom to tell Angular
177+
if the entire html page or only a portion of it should be treated as the Angular application.
178178

179-
* Angular script tag
179+
* AngularJS script tag:
180180

181181
<script src="lib/angular/angular.js">
182182

183-
This single line of code is all that is needed to bootstrap an angular application.
184-
185-
The code downloads the `angular.js` script and registers a callback that will be executed by the
183+
This code downloads the `angular.js` script and registers a callback that will be executed by the
186184
browser when the containing HTML page is fully downloaded. When the callback is executed, Angular
187-
looks for the {@link api/angular.directive.ng:app ng:app} attribute. If Angular finds
188-
`ng:app`, it creates a root scope for the application and associates it with the element of
189-
when `ng:app` was declared.
185+
looks for the {@link api/angular.module.ng.$compileProvider.directive.ng-app ng-app} directive. If
186+
Angular finds `ng-app`, it will bootstrap the application with the root of the application DOM being
187+
the element on which the `ng-app` directive was defined.
188+
189+
* Double-curly binding with an expression:
190+
191+
Nothing here {{'yet' + '!'}}`
192+
193+
This line demonstrates the core feature of Angular's templating capabilities – a binding, denoted
194+
by double-curlies `{{ }}` as well as a simple expression `'yet' + '!'` used in this binding.
195+
196+
The binding tells Angular, that it should evaluate an expression and insert the result into the
197+
DOM in place of the binding. Rather than a one-time insert, as we'll see in the next steps, a
198+
binding will result in efficient continuous updates whenever the result of the expression
199+
evaluation changes.
200+
201+
{@link guide/dev_guide.expressions Angular expression} is a JavaScript-like code snippet that is
202+
evaluated by Angular in the context of the current model scope, rather than within the scope of
203+
the global context (`window`).
204+
205+
As expected, once this template is processed by Angular, the html page will contains text:
206+
"Nothing here yet!".
207+
208+
## Bootstrapping AngularJS apps
209+
210+
Bootstrapping AngularJS apps automatically using the `ng-app` directive is very easy and suitable
211+
for most cases. In advanced cases, such as when using script loaders, you can use
212+
{@link guide/dev_guide.bootstrap.manual_bootstrap imperative / manual way} to bootstrap the app.
213+
214+
There are 3 important things that happen during the app bootstrap:
215+
216+
1. The {@link api/angular.module.AUTO.$injector injector} that will be used for dependency injection
217+
within this app is created.
190218

191-
<img src="img/tutorial/tutorial_00_final.png">
219+
2. The injector will then create the {@link api/angular.module.ng.$rootScope root scope} that will
220+
become the context for the model of our application.
192221

193-
As you will see shortly, everything in Angular is evaluated within a scope. We'll learn more
194-
about this in the next steps.
222+
3. Angular will then "compile" the DOM starting at the `ng-app` root element, processing any
223+
directives and bindings found along the way.
224+
225+
226+
Once an application is bootstrapped, it will then wait for incoming browser events (such as mouse
227+
click, key press or incoming HTTP response) that might change the model. Once such event occurs,
228+
Angular detects if it caused any model changes and if changes are found, Angular will reflect them
229+
in the view by updating all of the affected bindings.
230+
231+
The structure of our application is currently very simple. The template contains just one directive
232+
and one static binding, and our model is empty. That will soon change!
233+
234+
<img src="img/tutorial/tutorial_00.png">
195235

196236

197237
## What are all these files in my working directory?
@@ -208,9 +248,25 @@ For the purposes of this tutorial, we modified the angular-seed with the followi
208248
* Added phone data files (JSON) to `app/phones`
209249

210250

251+
252+
# Experiments
253+
254+
* Try adding a new expression to the `index.html` that will do some math:
255+
256+
<p>1 + 2 = {{ 1 + 2 }}</p>
257+
258+
259+
211260
# Summary
212261

213262
Now let's go to {@link step_01 step 1} and add some content to the web app.
214263

215264

216265
<ul doc:tutorial-nav="0"></ul>
266+
267+
Move elsewhere:
268+
269+
Note: During the bootstrap the injector and the root scope will then be associated with the
270+
element on which `ng-app` was declared, so when debugging the app you can retrieve them from
271+
browser console via `angular.element(rootElement).scope()` and
272+
`angular.element(rootElement).injector()`.

‎docs/content/tutorial/step_01.ngdoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ __`app/index.html`:__
5151
# Summary
5252

5353
This addition to your app uses static HTML to display the list. Now, let's go to {@link step_02
54-
step 2} to learn how to use angular to dynamically generate the same list.
54+
step 2} to learn how to use AngularJS to dynamically generate the same list.
5555

5656

5757
<ul doc:tutorial-nav="1"></ul>

0 commit comments

Comments
 (0)