invisi/angular.js
1
0
Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity

docs(tutorial): switch from bower to npm and upgrade AngularJS to 1.7.x

Browse Source 
Related: angular/angular-phonecat#430
This commit is contained in:
George Kalpakas
2018-11-02 16:41:12 +02:00
parent 1a14b58c6e
commit b77f058505
9 changed files with 119 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/tutorial/index.ngdoc
+21 -18
View File
@@ -99,8 +99,8 @@ The tutorial instructions, from now on, assume you are running all commands from
### Install Node.js
If you want to run the preconfigured local web server and the test tools then you will also need
[Node.js v4+][node].
In order to install dependencies (such as the test tools and AngularJS itself) and run the
preconfigured local web server, you will also need [Node.js v6+][node].
You can download a Node.js installer for your operating system from https://nodejs.org/en/download/.
@@ -125,22 +125,25 @@ npm --version
[Node Version Manager (nvm)][nvm] or [Node Version Manager (nvm) for Windows][nvm-windows].
</div>
Once you have Node.js installed on your machine, you can download the tool dependencies by running:
By installing Node.js, you also get [npm][npm], which is a command line executable for downloading
and managing Node.js packages. We use it to download the AngularJS framework as well as development
and testing tools.
Once you have Node.js installed on your machine, you can download these dependencies by running:
```
npm install
```
This command reads angular-phonecat's `package.json` file and downloads the following tools into the
`node_modules` directory:
This command reads angular-phonecat's `package.json` file and downloads the following dependencies
into the `node_modules` directory:
* [Bower][bower] - client-side code package manager
* [Http-Server][http-server] - simple local static web server
* [Karma][karma] - unit test runner
* [Protractor][protractor] - end-to-end (E2E) test runner
Running `npm install` will also automatically use bower to download the AngularJS framework into the
`app/bower_components` directory.
Running `npm install` will also automatically copy the AngularJS framework and other dependencies
necessary for our app to work into the `app/lib/` directory.
<div class="alert alert-info">
Note the angular-phonecat project is setup to install and run these utilities via npm scripts.
@@ -160,23 +163,23 @@ tasks that you will need while developing:
### Install Helper Tools (optional)
The Bower, Http-Server, Karma and Protractor modules are also executables, which can be installed
globally and run directly from a terminal/command prompt. You don't need to do this to follow the
tutorial, but if you decide you do want to run them directly, you can install these modules globally
using, `sudo npm install -g ...`.
The Http-Server, Karma and Protractor modules are also executables, which can be installed globally
and run directly from a terminal/command prompt. You don't need to do this to follow the tutorial,
but if you decide you do want to run them directly, you can install these modules globally using,
`sudo npm install --global ...`.
For instance, to install the Bower command line executable you would do:
For instance, to install the `http-server` command line executable you would do:
```
sudo npm install -g bower
sudo npm install --global http-server
```
_(Omit the sudo if running on Windows)_
_(Omit the sudo if running on Windows.)_
Then you can run the bower tool directly, such as:
Then you can run the `http-server` tool directly, such as:
```
bower install
http-server ./app
```
@@ -324,13 +327,13 @@ Now that you have set up your local machine, let's get started with the tutorial
[angular-phonecat]: https://github.com/angular/angular-phonecat
[bower]: https://bower.io/
[git]: https://git-scm.com/
[http-server]: https://github.com/nodeapps/http-server
[jdk]: https://en.wikipedia.org/wiki/Java_Development_Kit
[jdk-download]: https://www.oracle.com/technetwork/java/javase/downloads/index.html
[karma]: https://karma-runner.github.io/
[node]: https://nodejs.org/
[npm]: https://www.npmjs.com/
[nvm]: https://github.com/creationix/nvm
[nvm-windows]: https://github.com/coreybutler/nvm-windows
[protractor]: https://github.com/angular/protractor
docs/content/tutorial/step_00.ngdoc
+6 -6
View File
@@ -51,8 +51,8 @@ The code contains some key AngularJS elements that we will need as we progress.
<head>
<meta charset="utf-8">
<title>My HTML File</title>
<link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap.css" />
<script src="bower_components/angular/angular.js"></script>
<link rel="stylesheet" href="lib/bootstrap/dist/css/bootstrap.css" />
<script src="lib/angular/angular.js"></script>
</head>
<body>
@@ -84,7 +84,7 @@ For more info on `ngApp`, check out the {@link ngApp API Reference}.
**`angular.js` script tag:**
```html
<script src="bower_components/angular/angular.js"></script>
<script src="lib/angular/angular.js"></script>
```
This code downloads the `angular.js` script which registers a callback that will be executed by the
@@ -154,8 +154,8 @@ and one static binding, and our model is empty. That will soon change!
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`).
install the AngularJS framework (via `npm` into the `app/lib/` 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:
@@ -163,7 +163,7 @@ For the purposes of this tutorial, we modified the angular-seed with the followi
* Removed unused dependencies.
* Added phone images to `app/img/phones/`.
* Added phone data files (JSON) to `app/phones/`.
* Added a dependency on [Bootstrap][bootstrap-3.3] in the `bower.json` file.
* Added a dependency on [Bootstrap][bootstrap-3.3] in the `package.json` file.
## Experiments
docs/content/tutorial/step_02.ngdoc
+2 -2
View File
@@ -33,7 +33,7 @@ The view is constructed by AngularJS from this template.
<html ng-app="phonecatApp">
<head>
...
<script src="bower_components/angular/angular.js"></script>
<script src="lib/angular/angular.js"></script>
<script src="app.js"></script>
</head>
<body ng-controller="PhoneListController">
@@ -317,7 +317,7 @@ by utilizing components.
<ul doc-tutorial-nav="2"></ul>
[jasmine-docs]: https://jasmine.github.io/2.4/introduction.html
[jasmine-docs]: https://jasmine.github.io/api/3.3/global
[jasmine-home]: https://jasmine.github.io/
[karma]: https://karma-runner.github.io/
[mvc-pattern]: https://en.wikipedia.org/wiki/Model–View–Controller
docs/content/tutorial/step_03.ngdoc
+1 -1
View File
@@ -120,7 +120,7 @@ acquired skill.
<html ng-app="phonecatApp">
<head>
...
<script src="bower_components/angular/angular.js"></script>
<script src="lib/angular/angular.js"></script>
<script src="app.js"></script>
<script src="phone-list.component.js"></script>
</head>
docs/content/tutorial/step_07.ngdoc
+2 -2
View File
@@ -8,8 +8,8 @@
Enough of building an app with three phones in a hard-coded dataset! Let's fetch a larger dataset
from our server using one of AngularJS's built-in {@link guide/services services} called
{@link ng.$http $http}. We will use AngularJS's {@link guide/di dependency injection (DI)} to provide
the service to the `phoneList` component's controller.
{@link ng.$http $http}. We will use AngularJS's {@link guide/di dependency injection (DI)} to
provide the service to the `phoneList` component's controller.
* There is now a list of 20 phones, loaded from the server.
docs/content/tutorial/step_08.ngdoc
+5 -4
View File
@@ -47,10 +47,10 @@ URLs point to the `app/img/phones/` directory.
...
<ul class="phones">
<li ng-repeat="phone in $ctrl.phones | filter:$ctrl.query | orderBy:$ctrl.orderProp" class="thumbnail">
<a href="#/phones/{{phone.id}}" class="thumb">
<a href="#!/phones/{{phone.id}}" class="thumb">
<img ng-src="{{phone.imageUrl}}" alt="{{phone.name}}" />
</a>
<a href="#/phones/{{phone.id}}">{{phone.name}}</a>
<a href="#!/phones/{{phone.id}}">{{phone.name}}</a>
<p>{{phone.snippet}}</p>
</li>
</ul>
@@ -110,8 +110,9 @@ You can now rerun `npm run protractor` to see the tests run.
## Summary
Now that you have added phone images and links, go to {@link step_09 step 9} to learn about AngularJS
layout templates and how AngularJS makes it easy to create applications that have multiple views.
Now that you have added phone images and links, go to {@link step_09 step 9} to learn about
AngularJS layout templates and how AngularJS makes it easy to create applications that have
multiple views.
<ul doc-tutorial-nav="8"></ul>
docs/content/tutorial/step_09.ngdoc
+38 -49
View File
@@ -23,49 +23,33 @@ has multiple views by adding routing, using an AngularJS module called {@link ng
The routing functionality added in this step is provided by AngularJS in the `ngRoute` module, which
is distributed separately from the core AngularJS framework.
Since we are using [Bower][bower] to install client-side dependencies, this step updates the
`bower.json` configuration file to include the new dependency:
Since we are using [npm][npm] to install client-side dependencies, this step updates the
`package.json` configuration file to include the new dependency:
<br />
**`bower.json`:**
**`package.json`:**
```json
{
"name": "angular-phonecat",
"description": "A starter project for AngularJS",
"version": "0.0.0",
"homepage": "https://github.com/angular/angular-phonecat",
"license": "MIT",
"private": true,
...
"dependencies": {
"angular": "1.5.x",
"angular-mocks": "1.5.x",
"angular-route": "1.5.x",
"angular": "1.7.x",
"angular-route": "1.7.x",
"bootstrap": "3.3.x"
}
},
...
}
```
The new dependency `"angular-route": "1.5.x"` tells bower to install a version of the angular-route
module that is compatible with version 1.5.x of AngularJS. We must tell bower to download and install
The new dependency `"angular-route": "1.7.x"` tells npm to install a version of the angular-route
module that is compatible with version 1.7.x of AngularJS. We must tell npm to download and install
this dependency.
```
npm install
```
<div class="alert alert-info">
**Note:** If you have bower installed globally, you can run `bower install`, but for this project
we have preconfigured `npm install` to run bower for us.
</div>
<div class="alert alert-warning">
**Warning:** If a new version of AngularJS has been released since you last ran `npm install`, then
you may have a problem with the `bower install` due to a conflict between the versions of
angular.js that need to be installed. If you run into this issue, simply delete your
`app/bower_components` directory and then run `npm install`.
</div>
## Multiple Views, Routing and Layout Templates
@@ -127,8 +111,8 @@ service, the `$routeProvider` exposes APIs that allow you to define routes for y
</div>
AngularJS modules solve the problem of removing global variables from the application and provide a
way of configuring the injector. As opposed to AMD or require.js modules, AngularJS modules don't try
to solve the problem of script load ordering or lazy script fetching. These goals are totally
way of configuring the injector. As opposed to AMD or require.js modules, AngularJS modules don't
try to solve the problem of script load ordering or lazy script fetching. These goals are totally
independent and both module systems can live side-by-side and fulfill their goals.
To deepen your understanding on AngularJS's DI, see [Understanding Dependency Injection][wiki-di].
@@ -146,8 +130,8 @@ into the layout template. This makes it a perfect fit for our `index.html` templ
```html
<head>
...
<script src="bower_components/angular/angular.js"></script>
<script src="bower_components/angular-route/angular-route.js"></script>
<script src="lib/angular/angular.js"></script>
<script src="lib/angular-route/angular-route.js"></script>
<script src="app.module.js"></script>
<script src="app.config.js"></script>
...
@@ -203,10 +187,8 @@ code, we put it into a separate file and used the `.config` suffix.
```js
angular.
module('phonecatApp').
config(['$locationProvider', '$routeProvider',
function config($locationProvider, $routeProvider) {
$locationProvider.hashPrefix('!');
config(['$routeProvider',
function config($routeProvider) {
$routeProvider.
when('/phones', {
template: '<phone-list></phone-list>'
@@ -226,18 +208,6 @@ the corresponding services. Here, we use the
{@link ngRoute.$routeProvider#otherwise $routeProvider.otherwise()} methods to define our
application routes.
<div class="alert alert-success">
<p>
We also used {@link $locationProvider#hashPrefix $locationProvider.hashPrefix()} to set the
hash-prefix to `!`. This prefix will appear in the links to our client-side routes, right after
the hash (`#`) symbol and before the actual path (e.g. `index.html#!/some/path`).
</p>
<p>
Setting a prefix is not necessary, but it is considered a good practice (for reasons that are
outside the scope of this tutorial). `!` is the most commonly used prefix.
</p>
</div>
Our routes are defined as follows:
* `when('/phones')`: Determines the view that will be shown, when the URL hash fragment is
@@ -261,6 +231,25 @@ the route declaration — `'/phones/:phoneId'` — as a template that is matched
URL. All variables defined with the `:` prefix are extracted into the (injectable)
{@link ngRoute.$routeParams $routeParams} object.
<div class="alert alert-info">
<p>
You may have noticed, that &mdash; while the configured route paths start with `/` (e.g.
`/phones`) &mdash; the URLs used in templates start with `#!/` (e.g. `#!/phones`).
</p>
<p>
Without getting into much detail, AngularJS (by default) uses the hash part of the URL (i.e.
what comes after the hash (`#`) symbol) to determine the current route. In addition to that, you
can also specify a {@link $locationProvider#hashPrefix hash-prefix} (`!` by default) that needs
to appear after the hash symbol in order for AngularJS to consider the value an "AngularJS path"
and process it (for example, try to match it to a route).
</p>
<p>
You can find out more about how all this works in the [Using $location](guide/$location) section
of the Developer Guide. But all you need to know for now, is that the URLs to our various routes
should be prefixed with `#!`.
</p>
</div>
## The `phoneDetail` Component
@@ -345,8 +334,8 @@ any modification.
```js
files: [
'bower_components/angular/angular.js',
'bower_components/angular-route/angular-route.js',
'lib/angular/angular.js',
'lib/angular-route/angular-route.js',
...
],
```
@@ -424,6 +413,6 @@ With the routing set up and the phone list view implemented, we are ready to go
<ul doc-tutorial-nav="9"></ul>
[bower]: https://bower.io/
[deep-linking]: https://en.wikipedia.org/wiki/Deep_linking
[npm]: https://www.npmjs.com/
[wiki-di]: https://github.com/angular/angular.js/wiki/Understanding-Dependency-Injection
docs/content/tutorial/step_13.ngdoc
+20 -35
View File
@@ -21,50 +21,34 @@ In this step, we will change the way our application fetches data.
The RESTful functionality is provided by AngularJS in the {@link ngResource ngResource} module, which
is distributed separately from the core AngularJS framework.
Since we are using [Bower][bower] to install client-side dependencies, this step updates the
`bower.json` configuration file to include the new dependency:
Since we are using [npm][npm] to install client-side dependencies, this step updates the
`package.json` configuration file to include the new dependency:
<br />
**`bower.json`:**
**`package.json`:**
```
```json
{
"name": "angular-phonecat",
"description": "A starter project for AngularJS",
"version": "0.0.0",
"homepage": "https://github.com/angular/angular-phonecat",
"license": "MIT",
"private": true,
...
"dependencies": {
"angular": "1.5.x",
"angular-mocks": "1.5.x",
"angular-resource": "1.5.x",
"angular-route": "1.5.x",
"angular": "1.7.x",
"angular-resource": "1.7.x",
"angular-route": "1.7.x",
"bootstrap": "3.3.x"
}
},
...
}
```
The new dependency `"angular-resource": "1.5.x"` tells bower to install a version of the
angular-resource module that is compatible with version 1.5.x of AngularJS. We must tell bower to
The new dependency `"angular-resource": "1.7.x"` tells npm to install a version of the
angular-resource module that is compatible with version 1.7.x of AngularJS. We must tell npm to
download and install this dependency.
```
npm install
```
<div class="alert alert-info">
**Note:** If you have bower installed globally, you can run `bower install`, but for this project
we have preconfigured `npm install` to run bower for us.
</div>
<div class="alert alert-warning">
**Warning:** If a new version of AngularJS has been released since you last ran `npm install`, then
you may have a problem with the `bower install` due to a conflict between the versions of
angular.js that need to be installed. If you run into this issue, simply delete your
`app/bower_components` directory and then run `npm install`.
</div>
## Service
@@ -129,7 +113,7 @@ need to load the `angular-resource.js` file, which contains the `ngResource` mod
```html
<head>
...
<script src="bower_components/angular-resource/angular-resource.js"></script>
<script src="lib/angular-resource/angular-resource.js"></script>
...
<script src="core/phone/phone.module.js"></script>
<script src="core/phone/phone.service.js"></script>
@@ -141,9 +125,10 @@ need to load the `angular-resource.js` file, which contains the `ngResource` mod
## Component Controllers
We can now simplify our component controllers (`PhoneListController` and `PhoneDetailController`) by
factoring out the lower-level `$http` service, replacing it with the new `Phone` service. AngularJS's
`$resource` service is easier to use than `$http` for interacting with data sources exposed as
RESTful resources. It is also easier now to understand what the code in our controllers is doing.
factoring out the lower-level `$http` service, replacing it with the new `Phone` service.
AngularJS's `$resource` service is easier to use than `$http` for interacting with data sources
exposed as RESTful resources. It is also easier now to understand what the code in our controllers
is doing.
<br />
**`app/phone-list/phone-list.module.js`:**
@@ -240,8 +225,8 @@ Karma configuration file with angular-resource.
```js
files: [
'bower_components/angular/angular.js',
'bower_components/angular-resource/angular-resource.js',
'lib/angular/angular.js',
'lib/angular-resource/angular-resource.js',
...
],
```
@@ -319,6 +304,6 @@ Now that we have seen how to build a custom service as a RESTful client, we are
<ul doc-tutorial-nav="13"></ul>
[bower]: https://bower.io/
[jasmine-equality]: https://jasmine.github.io/2.4/custom_equality.html
[npm]: https://www.npmjs.com/
[restful]: https://en.wikipedia.org/wiki/Representational_State_Transfer
docs/content/tutorial/step_14.ngdoc
+24 -40
View File
@@ -22,59 +22,43 @@ the template code we created earlier.
## Dependencies
The animation functionality is provided by AngularJS in the `ngAnimate` module, which is distributed
separately from the core AngularJS framework. In addition we will use [jQuery][jquery] in this project
to do extra JavaScript animations.
separately from the core AngularJS framework. In addition we will use [jQuery][jquery] in this
project to do extra JavaScript animations.
Since we are using [Bower][bower] to install client-side dependencies, this step updates the
`bower.json` configuration file to include the new dependencies:
Since we are using [npm][npm] to install client-side dependencies, this step updates the
`package.json` configuration file to include the new dependencies:
<br />
**`bower.json`:**
**`package.json`:**
```
```json
{
"name": "angular-phonecat",
"description": "A starter project for AngularJS",
"version": "0.0.0",
"homepage": "https://github.com/angular/angular-phonecat",
"license": "MIT",
"private": true,
...
"dependencies": {
"angular": "1.5.x",
"angular-animate": "1.5.x",
"angular-mocks": "1.5.x",
"angular-resource": "1.5.x",
"angular-route": "1.5.x",
"angular": "1.7.x",
"angular-animate": "1.7.x",
"angular-resource": "1.7.x",
"angular-route": "1.7.x",
"bootstrap": "3.3.x",
"jquery": "3.2.x"
}
"jquery": "3.3.x"
},
...
}
```
* `"angular-animate": "1.5.x"` tells bower to install a version of the angular-animate module that
is compatible with version 1.5.x of AngularJS.
* `"jquery": "3.2.x"` tells bower to install the latest patch release of the 3.2 version of jQuery.
Note that this is not an AngularJS library; it is the standard jQuery library. We can use bower to
* `"angular-animate": "1.7.x"` tells npm to install a version of the angular-animate module that
is compatible with version 1.7.x of AngularJS.
* `"jquery": "3.3.x"` tells npm to install the latest patch release of the 3.3 version of jQuery.
Note that this is not an AngularJS library; it is the standard jQuery library. We can use npm to
install a wide range of 3rd party libraries.
Now, we must tell bower to download and install these dependencies.
Now, we must tell npm to download and install these dependencies.
```
npm install
```
<div class="alert alert-info">
**Note:** If you have bower installed globally, you can run `bower install`, but for this project
we have preconfigured `npm install` to run bower for us.
</div>
<div class="alert alert-warning">
**Warning:** If a new version of AngularJS has been released since you last ran `npm install`, then
you may have a problem with the `bower install` due to a conflict between the versions of
angular.js that need to be installed. If you run into this issue, simply delete your
`app/bower_components` directory and then run `npm install`.
</div>
## How Animations work with `ngAnimate`
@@ -101,12 +85,12 @@ code necessary to make your application "animation aware".
...
<!-- Used for JavaScript animations (include this before angular.js) -->
<script src="bower_components/jquery/dist/jquery.js"></script>
<script src="lib/jquery/dist/jquery.js"></script>
...
<!-- Adds animation support in AngularJS -->
<script src="bower_components/angular-animate/angular-animate.js"></script>
<script src="lib/angular-animate/angular-animate.js"></script>
<!-- Defines JavaScript animations -->
<script src="app.animations.js"></script>
@@ -115,8 +99,8 @@ code necessary to make your application "animation aware".
```
<div class="alert alert-error">
**Important:** Be sure to use jQuery version 2.1 or newer, when using AngularJS 1.5 or newer; jQuery 1.x is
not officially supported.
**Important:** Be sure to use jQuery version 2.1 or newer, when using AngularJS 1.5 or newer;
jQuery 1.x is not officially supported.
In order for AngularJS to detect jQuery and take advantage of it, make sure to include `jquery.js`
before `angular.js`.
</div>
@@ -556,9 +540,9 @@ There you have it! We have created a web application in a relatively short amoun
<ul doc-tutorial-nav="14"></ul>
[bower]: https://bower.io/
[caniuse-css-animation]: https://caniuse.com/#feat=css-animation
[caniuse-css-transitions]: https://caniuse.com/#feat=css-transitions
[jquery]: https://jquery.com/
[jquery-animate]: https://api.jquery.com/animate
[mdn-animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations
[npm]: https://www.npmjs.com/