Skip to content
This repository has been archived by the owner on Apr 12, 2024. It is now read-only.

Commit

Permalink
docs(tutorial): update tutorial intro + steps 0-3
Browse files Browse the repository at this point in the history
also contains all kinds of fixes that I had to make in the docs app to
get the tutorial to render correctly
  • Loading branch information
IgorMinar committed Apr 4, 2012
1 parent 6336b6e commit 53b2254
Show file tree
Hide file tree
Showing 30 changed files with 1,293 additions and 2,119 deletions.
32 changes: 15 additions & 17 deletions docs/content/tutorial/index.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
@name Tutorial
@description

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

<img src="img/tutorial/catalog_screen.png">
<img src="img/tutorial/catalog_screen.png" width="488" height="413">

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

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

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

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

The last thing to do is to make sure your computer has a web browser and a good text editor
installed. Now, let's get going with {@link step_00 step 0}.
installed. Now, let's get some cool stuff done!

{@link step_00 <span class="tutorial-start">Get Started!</span>}
102 changes: 79 additions & 23 deletions docs/content/tutorial/step_00.ngdoc
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
@ngdoc overview
@name Tutorial: 0 - angular-seed
@name Tutorial: 0 - Bootstrapping
@description

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


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

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

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

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

__`app/index.html`:__
<pre>
<!doctype html>
<html xmlns:ng="http://angularjs.org/" ng:app>
<html ng-app>
<head>
<meta charset="utf-8">
<title>my angular app</title>
<link rel="stylesheet" href="css/app.css"/>
<link rel="stylesheet" href="css/app.css">
<script src="lib/angular/angular.js"></script>
</head>
<body>

Nothing here yet!
Nothing here {{'yet' + '!'}}

<script src="lib/angular/angular.js"></script>
</body>
</html>
</pre>
Expand All @@ -168,30 +168,70 @@ __`app/index.html`:__

## What is the code doing?

* xmlns declaration
* `ng-app` directive:

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

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

* Angular script tag
* AngularJS script tag:

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

This single line of code is all that is needed to bootstrap an angular application.

The code downloads the `angular.js` script and registers a callback that will be executed by the
This code downloads the `angular.js` script and registers a callback that will be executed by the
browser when the containing HTML page is fully downloaded. When the callback is executed, Angular
looks for the {@link api/angular.directive.ng:app ng:app} attribute. If Angular finds
`ng:app`, it creates a root scope for the application and associates it with the element of
when `ng:app` was declared.
looks for the {@link api/angular.module.ng.$compileProvider.directive.ng-app ng-app} directive. If
Angular finds `ng-app`, it will bootstrap the application with the root of the application DOM being
the element on which the `ng-app` directive was defined.

* Double-curly binding with an expression:

Nothing here {{'yet' + '!'}}`

This line demonstrates the core feature of Angular's templating capabilities – a binding, denoted
by double-curlies `{{ }}` as well as a simple expression `'yet' + '!'` used in this binding.

The binding tells Angular, that it should evaluate an expression and insert the result into the
DOM in place of the binding. Rather than a one-time insert, as we'll see in the next steps, a
binding will result in efficient continuous updates whenever the result of the expression
evaluation changes.

{@link guide/dev_guide.expressions Angular expression} is a JavaScript-like code snippet that is
evaluated by Angular in the context of the current model scope, rather than within the scope of
the global context (`window`).

As expected, once this template is processed by Angular, the html page will contains text:
"Nothing here yet!".

## Bootstrapping AngularJS apps

Bootstrapping AngularJS apps automatically using the `ng-app` directive is very easy and suitable
for most cases. In advanced cases, such as when using script loaders, you can use
{@link guide/dev_guide.bootstrap.manual_bootstrap imperative / manual way} to bootstrap the app.

There are 3 important things that happen during the app bootstrap:

1. The {@link api/angular.module.AUTO.$injector injector} that will be used for dependency injection
within this app is created.

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

As you will see shortly, everything in Angular is evaluated within a scope. We'll learn more
about this in the next steps.
3. Angular will then "compile" the DOM starting at the `ng-app` root element, processing any
directives and bindings found along the way.


Once an application is bootstrapped, it will then wait for incoming browser events (such as mouse
click, key press or incoming HTTP response) that might change the model. Once such event occurs,
Angular detects if it caused any model changes and if changes are found, Angular will reflect them
in the view by updating all of the affected bindings.

The structure of our application is currently very simple. The template contains just one directive
and one static binding, and our model is empty. That will soon change!

<img src="img/tutorial/tutorial_00.png">


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



# Experiments

* Try adding a new expression to the `index.html` that will do some math:

<p>1 + 2 = {{ 1 + 2 }}</p>



# Summary

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


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

Move elsewhere:

Note: During the bootstrap the injector and the root scope will then be associated with the
element on which `ng-app` was declared, so when debugging the app you can retrieve them from
browser console via `angular.element(rootElement).scope()` and
`angular.element(rootElement).injector()`.
2 changes: 1 addition & 1 deletion docs/content/tutorial/step_01.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ __`app/index.html`:__
# Summary

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


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

0 comments on commit 53b2254

Please sign in to comment.