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

docs(tutorial): update to use v1.5.x and best practices #14416

Closed
wants to merge 6 commits into from
Closed

docs(tutorial): update to use v1.5.x and best practices #14416

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5050dd5
docs(tutorial): update to use `v1.5.x` and best practices
gkalpak Mar 27, 2016
2944392
docs(tutorial): update images to match new content
gkalpak Apr 27, 2016
2549951
fixup 1
gkalpak Apr 27, 2016
26d3abe
fixup 2
gkalpak May 19, 2016
b555f2c
fixup 3
gkalpak May 21, 2016
d7be60f
fixup 4
gkalpak May 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/app/assets/css/docs.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -647,6 +647,11 @@ ul.events > li {
padding-top: 50px;
}

.diagram {
margin-bottom: 10px;
margin-top: 30px;
}

@media only screen and (min-width: 769px) and (max-width: 991px) {
.main-body-grid {
margin-top: 160px;
Expand Down
7 changes: 4 additions & 3 deletions docs/app/src/tutorials.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ angular.module('tutorials', [])
'',
'step_00', 'step_01', 'step_02', 'step_03', 'step_04',
'step_05', 'step_06', 'step_07', 'step_08', 'step_09',
'step_10', 'step_11', 'step_12', 'the_end'
'step_10', 'step_11', 'step_12', 'step_13', 'step_14',
'the_end'
];
return {
scope: {},
Expand Down Expand Up @@ -43,7 +44,7 @@ angular.module('tutorials', [])
'<a href="http://angular.github.io/angular-phonecat/step-{{step}}/app">Step {{step}} Live Demo</a>.</p>\n' +
'</div>\n' +
'<p>The most important changes are listed below. You can see the full diff on ' +
'<a ng-href="https://github.com/angular/angular-phonecat/compare/step-{{step ? (step - 1): \'0~1\'}}...step-{{step}}" title="See diff on Github">GitHub</a>\n' +
'<a ng-href="https://github.com/angular/angular-phonecat/compare/step-{{step ? (step - 1): \'0~1\'}}...step-{{step}}" title="See diff on Github">GitHub</a>.\n' +
'</p>'
};
});
});
8 changes: 4 additions & 4 deletions docs/config/templates/indexPage.template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,10 +228,10 @@ <h4 class="search-results-group-heading">{{ key }}</h4>
)
</p>
<p>
Code licensed under the
<a href="https://github.com/angular/angular.js/blob/master/LICENSE" target="_blank">The
MIT License</a>. Documentation licensed under <a
href="http://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>.
Code licensed under
<a href="https://github.com/angular/angular.js/blob/master/LICENSE" target="_blank">The MIT License</a>.
Documentation licensed under
<a href="http://creativecommons.org/licenses/by/3.0/" target="_blank">CC BY 3.0</a>.
</p>
</div>
</footer>
Expand Down
237 changes: 141 additions & 96 deletions docs/content/tutorial/index.ngdoc
View file
Open in desktop

Large diffs are not rendered by default.

163 changes: 89 additions & 74 deletions docs/content/tutorial/step_00.ngdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,130 +7,143 @@


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

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

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

```
git checkout -f step-0
```


This resets your workspace to step 0 of the tutorial app.

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

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

```
npm install
```

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we consider using lite-server instead of http-server since it has a couple of nice features like automatic rewriting to index.html (to support HTML5 mode) and also it starts up the browser when you start the server.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The version of http-server we are using now also supports opening the browser.
Since we are not using HTML5 mode in the tutorial (I would rather keep it that way, in order to avoid discussing one more concept (server-side configuration for HTML5 mode)), I don't think lite-server offers any advantage over http-server. We could switch, but we need to also update angular-phonecat and angular-seed, so I would avoid it if there is no compelling reason.

How about we do it in a subsequent PR ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK stick with http-server

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although lite-server also offers live-reloading :-)

Copy link
Member Author

@gkalpak gkalpak May 19, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have already added this to my post-merge tasks :)


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

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

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 as we progress.

__`app/index.html`:__
**`app/index.html`:**

```html
<!doctype html>
<html lang="en" ng-app>
<head>
<meta charset="utf-8">
<title>My HTML File</title>
<link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap.css">
<link rel="stylesheet" href="css/app.css">
<script src="bower_components/angular/angular.js"></script>
</head>
<body>

<p>Nothing here {{'yet' + '!'}}</p>

</body>
<head>
<meta charset="utf-8">
<title>My HTML File</title>
<link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap.css" />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<link> tags are empty, we should not use a self-closing tag

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<link> (and <img>) are void elements, which according to the spec are allowed to have a / (it's optional for HTML 5). I guess it's a remnant from my XHTML days, but I find it more readable with the slash, so I always use it.

I'm fine removing it, if you feel strongly about it.

<script src="bower_components/angular/angular.js"></script>
</head>
<body>

<p>Nothing here {{'yet' + '!'}}</p>

</body>
</html>
```



## What is the code doing?

**`ng-app` directive:**
<br />
**`ng-app` attribute:**

<html ng-app>
```html
<html ng-app>
```

The `ng-app` attribute represents an Angular directive, named `ngApp` (Angular uses `kebab-case` for
its custom attributes and `camelCase` for the corresponding directives which implement them). This
directive is used to flag the HTML element that 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 AngularJS application.

The `ng-app` attribute represents an Angular directive named `ngApp` (Angular uses
`spinal-case` for its custom attributes and `camelCase` for the corresponding directives
which implement them).
This directive is used to flag the html element that 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.
For more info on `ngApp`, check out the {@link ngApp API Reference}.

**AngularJS script tag:**
<br />
**`angular.js` script tag:**

<script src="bower_components/angular/angular.js">
```html
<script src="bower_components/angular/angular.js"></script>
```

This code downloads the `angular.js` script which registers a callback that will be executed by the
This code downloads the `angular.js` script which 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 ng.directive:ngApp ngApp} directive. If
Angular finds the directive, it will bootstrap the application with the root of the application DOM
being the element on which the `ngApp` directive was defined.
looks for the {@link ngApp ngApp} directive. If Angular finds the directive, it will bootstrap the
application with the root of the application DOM being the element on which the `ngApp` directive
was defined.

For more info on bootstrapping your app, checkout the [Bootstrap](guide/bootstrap) section of the
Developer Guide.

<br />
**Double-curly binding with an expression:**

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

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

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

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.
The binding tells Angular that it should evaluate an expression and insert the result into the DOM
in place of the binding. As we will see in the next steps, rather than a one-time insert, a binding
will result in efficient continuous updates whenever the result of the expression evaluation
changes.

{@link guide/expression 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`).
{@link guide/expression Angular expressions} are JavaScript-like code snippets that are 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 contains the text:
"Nothing here yet!".
As expected, once this template is processed by Angular, the HTML page contains the text:

## Bootstrapping AngularJS apps
```
Nothing here yet!
```

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

There are 3 important things that happen during the app bootstrap:
Bootstrapping Angular applications automatically using the `ngApp` directive is very easy and
suitable for most cases. In advanced cases, such as when using script loaders, you can use the
{@link guide/bootstrap#manual-initialization imperative/manual way} to bootstrap the application.

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

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

2. The injector will then create the {@link ng.$rootScope root scope} that will
become the context for the model of our application.
2. The injector will then create the {@link ng.$rootScope root scope} that will become the context
for the model of our application.

3. Angular will then "compile" the DOM starting at the `ngApp` 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 an 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.
clicks, key presses or incoming HTTP responses) that might change the model. Once such an 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!
Expand All @@ -140,27 +153,29 @@ and one static binding, and our model is empty. That will soon change!

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


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

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

* Removed the example app
* Added phone images to `app/img/phones/`
* Added phone data files (JSON) to `app/phones/`
* Removed the example app.
* Removed unused dependencies.
* Added phone images to `app/img/phones/`.
* Added phone data files (JSON) to `app/phones/`.
* Added a dependency on [Bootstrap](http://getbootstrap.com) in the `bower.json` file.



# Experiments

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

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

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


# Summary
Expand Down
14 changes: 9 additions & 5 deletions docs/content/tutorial/step_01.ngdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ dynamically display the same result with any set of data.

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

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

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


<br />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<br> tags are also empty

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above.

**`app/index.html`:**

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

# Experiments

<div></div>

* Try adding more static HTML to `index.html`. For example:

<p>Total number of phones: 2</p>
```html
<p>Total number of phones: 2</p>
```


# 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 AngularJS to dynamically generate the same list.
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.


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