Skip to content

Commit 65630f3

Browse files
gkalpakgkalpak
committed
WIP - docs(tutorial): update to use v1.5.x and best practices
Related to angular/angular-phonecat#326. Related to angular/angular-seed#329. Related to angular/angular-seed#333. Fixes angular#12755 Fixes angular#13312 Fixes angular#13623 Fixes angular#13632 Closes angular#8952 Closes angular#11726 Closes angular#12946 Closes angular#12947 Closes angular#13198 Closes angular#13284 Closes angular#13834 Closes angular#14178 Closes angular#14223
1 parent 71cf28c commit 65630f3

25 files changed

+3012
-2148
lines changed

‎docs/content/tutorial/index.ngdoc

+107-95
Large diffs are not rendered by default.

‎docs/content/tutorial/step_00.ngdoc

+90-75
Original file line numberDiff line numberDiff line change
@@ -7,130 +7,143 @@
77

88

99
In this step of the tutorial, you will become familiar with the most important source code files of
10-
the AngularJS phonecat app. You will also learn how to start the development servers bundled with
11-
angular-seed, and run the application in the browser.
10+
the AngularJS Phonecat App. You will also learn how to start the development servers bundled with
11+
[angular-seed][angular-seed], and run the application in the browser.
1212

13-
Before you continue, make sure you have set up your development environment and installed all necessary
14-
dependencies, as described in {@link index#get-started Get Started}.
13+
Before you continue, make sure you have set up your development environment and installed all
14+
necessary dependencies, as described in the {@link tutorial/#environment-setup Environment Setup}
15+
section.
1516

1617
In the `angular-phonecat` directory, run this command:
1718

1819
```
1920
git checkout -f step-0
2021
```
2122

22-
2323
This resets your workspace to step 0 of the tutorial app.
2424

2525
You must repeat this for every future step in the tutorial and change the number to the number of
2626
the step you are on. This will cause any changes you made within your working directory to be lost.
2727

28-
If you haven't already done so you need to install the dependencies by running:
28+
If you haven't already done so, you need to install the dependencies by running:
2929

3030
```
3131
npm install
3232
```
3333

34-
To see the app running in a browser, open a *separate* terminal/command line tab or window, then
35-
run `npm start` to start the web server. Now, open a browser window for the app and navigate to
36-
<a href="http://localhost:8000/app/" target="_blank" title="Open app on localhost">`http://localhost:8000/app/`</a>
34+
To see the app running in a browser, open a _separate_ terminal/command line tab or window, then run
35+
`npm start` to start the web server. Now, open a browser window for the app and navigate to
36+
http://localhost:8000/index.html.
3737

38-
Note that if you already ran the master branch app prior to checking out step-0, you may see the cached
39-
master version of the app in your browser window at this point. Just hit refresh to re-load the page.
38+
Note that if you already ran the master branch app prior to checking out step-0, you may see the
39+
cached master version of the app in your browser window at this point. Just hit refresh to re-load
40+
the page.
4041

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

4344
The HTML page that displays "Nothing here yet!" was constructed with the HTML code shown below.
4445
The code contains some key Angular elements that we will need as we progress.
4546

46-
__`app/index.html`:__
47+
**`app/index.html`:**
4748

4849
```html
4950
<!doctype html>
50-
<html lang="en" ng-app>
51-
<head>
52-
<meta charset="utf-8">
53-
<title>My HTML File</title>
54-
<link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap.css">
55-
<link rel="stylesheet" href="css/app.css">
56-
<script src="bower_components/angular/angular.js"></script>
57-
</head>
58-
<body>
59-
60-
<p>Nothing here {{'yet' + '!'}}</p>
61-
62-
</body>
51+
<html lang="en" ng-app="phonecatApp">
52+
<head>
53+
<meta charset="utf-8">
54+
<title>My HTML File</title>
55+
<link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap.css" />
56+
<script src="bower_components/angular/angular.js"></script>
57+
</head>
58+
<body>
59+
60+
<p>Nothing here {{'yet' + '!'}}</p>
61+
62+
</body>
6363
</html>
6464
```
6565

6666

67-
6867
## What is the code doing?
6968

70-
**`ng-app` directive:**
69+
<br />
70+
**`ng-app` attribute:**
71+
72+
```html
73+
<html ng-app>
74+
```
7175

72-
<html ng-app>
76+
The `ng-app` attribute represents an Angular directive, named `ngApp` (Angular uses `kebab-case` for
77+
its custom attributes and `camelCase` for the corresponding directives which implement them). This
78+
directive is used to flag the HTML element that Angular should consider to be the root element of
79+
our application. This gives application developers the freedom to tell Angular if the entire HTML
80+
page or only a portion of it should be treated as the AngularJS application.
7381

74-
The `ng-app` attribute represents an Angular directive named `ngApp` (Angular uses
75-
`spinal-case` for its custom attributes and `camelCase` for the corresponding directives
76-
which implement them).
77-
This directive is used to flag the html element that Angular should consider to be the root element
78-
of our application.
79-
This gives application developers the freedom to tell Angular if the entire html page or only a
80-
portion of it should be treated as the Angular application.
82+
For more info on `ngApp`, check out the {@link ng.directive:ngApp API Reference}.
8183

82-
**AngularJS script tag:**
84+
<br />
85+
**`angular.js` script tag:**
8386

84-
<script src="bower_components/angular/angular.js">
87+
```html
88+
<script src="bower_components/angular/angular.js">
89+
```
8590

86-
This code downloads the `angular.js` script which registers a callback that will be executed by the
91+
This code downloads the `angular.js` script which registers a callback that will be executed by the
8792
browser when the containing HTML page is fully downloaded. When the callback is executed, Angular
88-
looks for the {@link ng.directive:ngApp ngApp} directive. If
89-
Angular finds the directive, it will bootstrap the application with the root of the application DOM
90-
being the element on which the `ngApp` directive was defined.
93+
looks for the {@link ng.directive:ngApp ngApp} directive. If Angular finds the directive, it will
94+
bootstrap the application with the root of the application DOM being the element on which the
95+
`ngApp` directive was defined.
96+
97+
For more info on bootstrapping your app, checkout the [Bootstrap](guide/bootstrap) section of the
98+
Developer Guide.
9199

100+
<br />
92101
**Double-curly binding with an expression:**
93102

94-
Nothing here {{'yet' + '!'}}
103+
```html
104+
Nothing here {{'yet' + '!'}}
105+
```
95106

96107
This line demonstrates two core features of Angular's templating capabilities:
97108

98-
* a binding, denoted by double-curlies `{{ }}`
99-
* a simple expression `'yet' + '!'` used in this binding.
109+
* A binding, denoted by double-curlies: `{{ }}`
110+
* A simple expression used in this binding: `'yet' + '!'`
100111

101-
The binding tells Angular that it should evaluate an expression and insert the result into the
102-
DOM in place of the binding. Rather than a one-time insert, as we'll see in the next steps, a
103-
binding will result in efficient continuous updates whenever the result of the expression
104-
evaluation changes.
112+
The binding tells Angular that it should evaluate an expression and insert the result into the DOM
113+
in place of the binding. As we will see in the next steps, rather than a one-time insert, a binding
114+
will result in efficient continuous updates whenever the result of the expression evaluation
115+
changes.
105116

106-
{@link guide/expression Angular expression} is a JavaScript-like code snippet that is
107-
evaluated by Angular in the context of the current model scope, rather than within the scope of
108-
the global context (`window`).
117+
{@link guide/expression Angular expressions} are JavaScript-like code snippets that are evaluated by
118+
Angular in the context of the current model scope, rather than within the scope of the global
119+
context (`window`).
109120

110-
As expected, once this template is processed by Angular, the html page contains the text:
111-
"Nothing here yet!".
121+
As expected, once this template is processed by Angular, the HTML page contains the text:
122+
123+
```
124+
Nothing here yet!
125+
```
112126

113-
## Bootstrapping AngularJS apps
127+
## Bootstrapping Angular Applications
114128

115-
Bootstrapping AngularJS apps automatically using the `ngApp` directive is very easy and suitable
116-
for most cases. In advanced cases, such as when using script loaders, you can use the
117-
{@link guide/bootstrap imperative / manual way} to bootstrap the app.
129+
Bootstrapping Angular applications automatically using the `ngApp` directive is very easy and
130+
suitable for most cases. In advanced cases, such as when using script loaders, you can use the
131+
{@link guide/bootstrap#manual-initialization imperative/manual way} to bootstrap the application.
118132

119-
There are 3 important things that happen during the app bootstrap:
133+
There are 3 important things that happen during the bootstrap phase:
120134

121135
1. The {@link auto.$injector injector} that will be used for dependency injection is created.
122136

123-
2. The injector will then create the {@link ng.$rootScope root scope} that will
124-
become the context for the model of our application.
137+
2. The injector will then create the {@link ng.$rootScope root scope} that will become the context
138+
for the model of our application.
125139

126140
3. Angular will then "compile" the DOM starting at the `ngApp` root element, processing any
127141
directives and bindings found along the way.
128142

129-
130143
Once an application is bootstrapped, it will then wait for incoming browser events (such as mouse
131-
click, key press or incoming HTTP response) that might change the model. Once such an event occurs,
132-
Angular detects if it caused any model changes and if changes are found, Angular will reflect them
133-
in the view by updating all of the affected bindings.
144+
clicks, key presses or incoming HTTP responses) that might change the model. Once such an event
145+
occurs, Angular detects if it caused any model changes and if changes are found, Angular will
146+
reflect them in the view by updating all of the affected bindings.
134147

135148
The structure of our application is currently very simple. The template contains just one directive
136149
and one static binding, and our model is empty. That will soon change!
@@ -140,27 +153,29 @@ and one static binding, and our model is empty. That will soon change!
140153

141154
## What are all these files in my working directory?
142155

143-
144-
Most of the files in your working directory come from the [angular-seed project][angular-seed] which
145-
is typically used to bootstrap new Angular projects. The seed project is pre-configured to install
146-
the angular framework (via `bower` into the `app/bower_components/` folder) and tools for developing
147-
a typical web app (via `npm`).
156+
Most of the files in your working directory come from the [angular-seed project][angular-seed],
157+
which is typically used to bootstrap new AngularJS projects. The seed project is pre-configured to
158+
install the AngularJS framework (via `bower` into the `app/bower_components/` directory) and tools
159+
for developing and testing a typical web application (via `npm`).
148160

149161
For the purposes of this tutorial, we modified the angular-seed with the following changes:
150162

151-
* Removed the example app
152-
* Added phone images to `app/img/phones/`
153-
* Added phone data files (JSON) to `app/phones/`
163+
* Removed the example app.
164+
* Removed unused dependencies.
165+
* Added phone images to `app/img/phones/`.
166+
* Added phone data files (JSON) to `app/phones/`.
154167
* Added a dependency on [Bootstrap](http://getbootstrap.com) in the `bower.json` file.
155168

156169

157-
158170
# Experiments
159171

160-
* Try adding a new expression to the `index.html` that will do some math:
172+
<div></div>
161173

162-
<p>1 + 2 = {{ 1 + 2 }}</p>
174+
* Try adding a new expression to `index.html` that will do some math:
163175

176+
```html
177+
<p>1 + 2 = {{1 + 2}}</p>
178+
```
164179

165180

166181
# Summary

‎docs/content/tutorial/step_01.ngdoc

+9-5
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ dynamically display the same result with any set of data.
1212

1313
In this step you will add some basic information about two cell phones to an HTML page.
1414

15-
- The page now contains a list with information about two phones.
15+
* The page now contains a list with information about two phones.
1616

1717
<div doc-tutorial-reset="1"></div>
1818

19-
19+
<br />
2020
**`app/index.html`:**
2121

2222
```html
@@ -39,15 +39,19 @@ In this step you will add some basic information about two cell phones to an HTM
3939

4040
# Experiments
4141

42+
<div></div>
43+
4244
* Try adding more static HTML to `index.html`. For example:
4345

44-
<p>Total number of phones: 2</p>
46+
```html
47+
<p>Total number of phones: 2</p>
48+
```
4549

4650

4751
# Summary
4852

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

5256

5357
<ul doc-tutorial-nav="1"></ul>

0 commit comments

Comments
 (0)