(docs) gettingstarted: Update to alpha-37 and latest guidance
-- squashed commits -- (examples) gettingstarted: Update to alpha-37 (fix) gettingstarted: remove id=output from template; e2e spec looks for h1 instead (fix) gettingstarted: simplified tsd commands (fix) gettingstarted: simplified tsd commands gettingStarted.jade updated for tooling-4 (docs) gettingstarted example revised for system 0.19, tsd 0.6.5, and as preface to ToH (docs) update gettingstarted to our current recommendation (still needs to be vetted) (docs) fix:gettingStarted.jade - small clarification after following instructions on clean directory. (docs) gettingstarted jade updated w/ tool version advice and John's suggestions
This commit is contained in:
Ward Bell
Naomi Black
parent
4565918f57
commit
b7ee016000
|
|
@ -11,7 +11,7 @@ describe('Getting Started E2E Tests', function () {
|
|||
});
|
||||
|
||||
it('should display: ' + expectedMsg, function () {
|
||||
expect(element(by.id('output')).getText()).toEqual(expectedMsg);
|
||||
expect(element(by.css('h1')).getText()).toEqual(expectedMsg);
|
||||
});
|
||||
}
|
||||
// #enddocregion
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ var AppComponent = ng
|
|||
// #enddocregion
|
||||
// #docregion view
|
||||
.View({
|
||||
template: '<h1 id="output">My First Angular 2 App</h1>'
|
||||
template: '<h1>My First Angular 2 App</h1>'
|
||||
})
|
||||
// #enddocregion
|
||||
// #docregion class
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
#Getting Started (TS) for the DevGuide developer
|
||||
|
||||
This is the source code for the "Getting Started" Typescrip example code.
|
||||
|
||||
There are files here that are *for the audience* and **not to be executed during example development**!
|
||||
This is the source code for the "Getting Started" Typescript example code.
|
||||
|
||||
* **package.json** - as the audience will see it; the example reaches up to the site level **node_modules**
|
||||
and the scripts are not supposed to work here.
|
||||
|
|
|
|||
|
|
@ -1,15 +1,16 @@
|
|||
{
|
||||
"name": "ng2-getting-started",
|
||||
"version": "0.0.1",
|
||||
"dependencies": {
|
||||
"angular2": "2.0.0-alpha.35",
|
||||
"es6-module-loader": "^0.16",
|
||||
"systemjs": "^0.16",
|
||||
"traceur": "0.0.91"
|
||||
},
|
||||
"name": "angular2-getting-started",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"main": "index.js",
|
||||
"scripts": {
|
||||
"postinstall": "cd src && tsd reinstall -r -o && cd ..",
|
||||
"tsc": "tsc -p src -w",
|
||||
"start": "live-server --open=src"
|
||||
"test": "echo \"Error: no test specified\" && exit 1"
|
||||
},
|
||||
"keywords": [],
|
||||
"author": "",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"angular2": "^2.0.0-alpha.37",
|
||||
"systemjs": "^0.19.2"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,21 +1,19 @@
|
|||
// #docregion
|
||||
// #docregion import
|
||||
import {Component, View, bootstrap} from 'angular2/angular2';
|
||||
// #enddocregion
|
||||
|
||||
// #enddocregion import
|
||||
// #docregion class-w-annotations
|
||||
@Component({
|
||||
selector: 'my-app'
|
||||
})
|
||||
@View({
|
||||
template: '<h1 id="output">My First Angular 2 App</h1>'
|
||||
template: '<h1>My First Angular 2 App</h1>'
|
||||
})
|
||||
// #docregion class
|
||||
class AppComponent { }
|
||||
// #enddocregion
|
||||
// #enddocregion
|
||||
// #enddocregion class
|
||||
// #enddocregion class-w-annotations
|
||||
|
||||
// #docregion bootstrap
|
||||
bootstrap(AppComponent);
|
||||
// #enddocregion
|
||||
// #enddocregion
|
||||
// #enddocregion bootstrap
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
describe("Jasmine sample test", function() {
|
||||
|
||||
it("1+1 should be 2", function() {
|
||||
|
||||
var result = 1 + 1;
|
||||
|
||||
expect(result).toBe(2);
|
||||
});
|
||||
});
|
||||
|
|
@ -1,16 +1,20 @@
|
|||
<!-- #docregion -->
|
||||
<!DOCTYPE html>
|
||||
<!-- #docregion -->
|
||||
<html>
|
||||
<head>
|
||||
<script src="../node_modules/traceur/bin/traceur-runtime.js"></script>
|
||||
<script src="../node_modules/es6-module-loader/dist/es6-module-loader.js"></script>
|
||||
<script src="../node_modules/systemjs/dist/system.src.js"></script>
|
||||
<script src="../node_modules/angular2/bundles/angular2.dev.js"></script>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<my-app></my-app>
|
||||
<my-app>Loading...</my-app>
|
||||
<script>
|
||||
System.import('app');
|
||||
System.config({
|
||||
packages: {'app': {defaultExtension: 'js'}}
|
||||
});
|
||||
System.import('app/app');
|
||||
</script>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
|
|
@ -4,6 +4,8 @@
|
|||
"module": "commonjs",
|
||||
"sourceMap": true,
|
||||
"emitDecoratorMetadata": true,
|
||||
"experimentalDecorators": true
|
||||
"experimentalDecorators": true,
|
||||
"removeComments": false,
|
||||
"noImplicitAny": true
|
||||
}
|
||||
}
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
{
|
||||
"version": "v4",
|
||||
"repo": "borisyankov/DefinitelyTyped",
|
||||
"ref": "master",
|
||||
"path": "typings",
|
||||
"bundle": "typings/tsd.d.ts",
|
||||
"installed": {
|
||||
"angular2/angular2.d.ts": {
|
||||
"commit": "cd2e71bb1f0459197e733be66fdeafaec600514d"
|
||||
},
|
||||
"es6-promise/es6-promise.d.ts": {
|
||||
"commit": "71d072b7354936b88d57c2029042d2da7c6ec0e7"
|
||||
},
|
||||
"jasmine/jasmine.d.ts": {
|
||||
"commit": "71d072b7354936b88d57c2029042d2da7c6ec0e7"
|
||||
},
|
||||
"rx/rx.d.ts": {
|
||||
"commit": "71d072b7354936b88d57c2029042d2da7c6ec0e7"
|
||||
},
|
||||
"rx/rx-lite.d.ts": {
|
||||
"commit": "71d072b7354936b88d57c2029042d2da7c6ec0e7"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -1,10 +1,9 @@
|
|||
{
|
||||
"name": "ng2-getting-started",
|
||||
"name": "getting-started",
|
||||
"version": "0.0.1",
|
||||
"dependencies": {
|
||||
"angular2": "2.0.0-alpha.35",
|
||||
"es6-module-loader": "^0.16",
|
||||
"systemjs": "^0.16",
|
||||
"angular2": "2.0.0-alpha.37",
|
||||
"systemjs": "^0.18.17",
|
||||
"traceur": "0.0.91"
|
||||
},
|
||||
"scripts": {
|
||||
|
|
|
|||
|
|
@ -165,7 +165,7 @@ include ../../../../_includes/_util-fns
|
|||
in the root directory of our application.
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code tsd query angular2 es6-promise rx rx-lite jasmine --action install --save
|
||||
code tsd install angular2 --save
|
||||
|
||||
:markdown
|
||||
We'll find a ***typings*** folder in the root directory
|
||||
|
|
|
|||
|
|
@ -12,11 +12,11 @@ include ../../../../_includes/_util-fns
|
|||
:markdown
|
||||
We'll do it in short steps
|
||||
1. Install the prerequisites for Angular TypeScript development
|
||||
1. Create an application folder
|
||||
1. Create the application project structure
|
||||
1. Install the npm packages our app needs
|
||||
1. Prepare for TypeScript compilation
|
||||
1. Create an *index.html*
|
||||
1. Write the root component for our application in *app.ts*
|
||||
1. Create an **`index.html`**
|
||||
1. Write the root component for our application in **`app.ts`**
|
||||
1. Bootstrap the app
|
||||
1. Compile the TypeScript to JavaScript
|
||||
1. Run it
|
||||
|
|
@ -36,7 +36,7 @@ include ../../../../_includes/_util-fns
|
|||
|
||||
:markdown
|
||||
Use npm again to install the [**tsd package manager**](https://www.npmjs.com/package/tsd "TSD Package Manager")
|
||||
so we can download TypeScript type definitions ("d.ts" files)
|
||||
so we can download TypeScript type definitions files ("`.d.ts`" files)
|
||||
from the [DefinitelyTyped](http://definitelytyped.org/) repository.
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
|
|
@ -50,18 +50,70 @@ include ../../../../_includes/_util-fns
|
|||
pre.prettyprint.lang-bash
|
||||
code npm install -g live-server
|
||||
|
||||
.l-sub-section
|
||||
:markdown
|
||||
Our success depends upon installing compatible versions of these tools.
|
||||
Confirm your version numbers in a terminal window with these commands:
|
||||
table
|
||||
tr
|
||||
th Command
|
||||
th Versions
|
||||
tr
|
||||
td
|
||||
code node -v
|
||||
td 0.10.* - 0.12.*   But not 4.0.0 !!!
|
||||
tr
|
||||
td
|
||||
code npm -v
|
||||
td 2.11+ (3.* is fine)
|
||||
tr
|
||||
td
|
||||
code tsc -v
|
||||
td 1.6+
|
||||
tr
|
||||
td
|
||||
code tsd --version
|
||||
td 0.6.5+
|
||||
tr
|
||||
td
|
||||
code live-server -v
|
||||
td 0.8+
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Create the application folder
|
||||
## Create the application project structure
|
||||
|
||||
Create a new folder to hold our application project, perhaps like this:
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code mkdir firstNgApp && cd firstNgApp
|
||||
```
|
||||
mkdir angular2-getting-started
|
||||
cd angular2-getting-started
|
||||
```
|
||||
|
||||
:markdown
|
||||
We'll refer to this as our application's **root folder**.
|
||||
|
||||
Now add a sub-folder - `src` - to hold project source code and a sub-sub-folder - `src/app` -
|
||||
to hold to hold the application source code.
|
||||
|
||||
In OS/X and Linux:
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code mkdir src/app
|
||||
|
||||
:markdown
|
||||
In Windows:
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code mkdir src\app
|
||||
|
||||
:markdown
|
||||
Our project folders should look like this.
|
||||
```
|
||||
angular2-getting-started
|
||||
├── src
|
||||
└──── app
|
||||
|
||||
```
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Install npm packages
|
||||
|
|
@ -70,114 +122,127 @@ include ../../../../_includes/_util-fns
|
|||
|
||||
>***angular.js***, the Angular 2 library.
|
||||
|
||||
>***es6-module-loader***, a "shim" that enables today's browsers load files
|
||||
using the latest "ES6" JavaScript syntax.
|
||||
|
||||
>***system.js***, a third-party open-source library that adds module loading functionality to our browser.
|
||||
|
||||
>***traceur-runtime.js*** to transpile the TypeScript-generated JavaScript into the version of Javascript
|
||||
our browser understands (the version known as "ES5").
|
||||
|
||||
For our little "GettingStarted" app, we could just install these packages
|
||||
with four npm commands.
|
||||
|
||||
In our real apps, we'd take an extra minute to create a *package.json* configuration file.
|
||||
This is a more robust, less error-prone approach, that we can maintain as our application evolves.
|
||||
|
||||
Create this **package.json** file in the root folder:
|
||||
We'll install these package with `npm` and create an npm **`package.json`** configuration file
|
||||
that to maintain future packages as our application evolves.
|
||||
|
||||
In a terminal window, go to the **root** folder and type:
|
||||
```
|
||||
{
|
||||
"name": "getting-started",
|
||||
"version": "0.0.1",
|
||||
"dependencies": {
|
||||
"angular2": "2.0.0-alpha.35",
|
||||
"es6-module-loader": "^0.16",
|
||||
"systemjs": "^0.16",
|
||||
"traceur": "0.0.91"
|
||||
}
|
||||
}
|
||||
npm init -y
|
||||
npm install --save angular2@2.0.0-alpha.37 systemjs@0.19.2
|
||||
```
|
||||
Now we install our script packages with one command
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code npm install
|
||||
`npm` produced a `node_modules` folder that holds these packages and other packages that *they* require.
|
||||
|
||||
The essence of our `package.json` should look like this:
|
||||
+makeJson('gettingstarted/ts/package.json', { paths: 'name, version, dependencies '})
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Prepare for TypeScript Compilation
|
||||
|
||||
We're done at the root level of our application.
|
||||
We'll build the rest of the application in a subfolder called *src*.
|
||||
Let's make that folder and go there.
|
||||
### Add links to TypeScript definition files
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code mkdir src && cd src
|
||||
|
||||
:markdown
|
||||
We have one last preparation step before we start coding.
|
||||
|
||||
We prefer writing TypeScript apps in an editor that understands TypeScript,
|
||||
an editor such as [Visual Studio Code](https://code.visualstudio.com/) or
|
||||
We prefer writing TypeScript apps in editors that understand TypeScript,
|
||||
such as [Visual Studio Code](https://code.visualstudio.com/) and
|
||||
[Web Storm](https://www.jetbrains.com/webstorm/features/).
|
||||
|
||||
Such editors improve the development experience by checking type information and
|
||||
displaying API documentation ("intellisense") based on TypeScript definition files (`.d.ts`).
|
||||
|
||||
The definition files we need are included in the npm packages we just installed.
|
||||
We'll use the
|
||||
[**tsd package manager**](https://www.npmjs.com/package/tsd "TSD Package Manager")
|
||||
to generate an *aggregate TypeScript definition file*, **`tsd.d.ts`**,
|
||||
that holds links to the type definition files in those packages.
|
||||
|
||||
In the ***root* folder** enter the following command
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code tsd link --config src/tsd.json
|
||||
|
||||
:markdown
|
||||
That produces a new **`src/typings`** folder with the **`tsd.d.ts`** file.
|
||||
|
||||
Now Angular type checking and intellisense lights up automatically as we write our app
|
||||
in the Visual Studio Code and Web Storm editors. Check your editor's documentation for
|
||||
instructions on using the `tsd.d.ts` file.
|
||||
|
||||
### Add the TypeScript configuration file
|
||||
|
||||
We need to tell that editor how to interpret our TypeScript
|
||||
which we do with a configuration file named **tsconfig.json**.
|
||||
This configuration file also simplifies the TypeScript compilation command we'll run later in this story.
|
||||
which we do with a configuration file named **`tsconfig.json`**.
|
||||
This configuration file also simplifies the TypeScript compilation command
|
||||
that we'll run very soon.
|
||||
|
||||
Create *tsconfig.json* now with the following JSON content:
|
||||
**Change to the `src` folder and create a `tsconfig.json`** file with the following content:
|
||||
+makeJson('gettingstarted/ts/src/tsconfig.json', null, 'tsconfig.json')
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES5",
|
||||
"module": "commonjs",
|
||||
"sourceMap": true,
|
||||
"emitDecoratorMetadata": true,
|
||||
"experimentalDecorators": true
|
||||
}
|
||||
}
|
||||
:markdown
|
||||
Our project should now look like this:
|
||||
```
|
||||
angular2-getting-started
|
||||
├── node_modules
|
||||
├── src
|
||||
│ ├── app
|
||||
│ ├── typings
|
||||
│ │ ├── tsd.d.ts
|
||||
│ ├── tsconfig.json
|
||||
└── package.json
|
||||
```
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Create an *index.html*
|
||||
## Create an `index.html`
|
||||
|
||||
Add a new `index.html` file to the project folder and enter the following HTML
|
||||
While in the **`src`** directory and
|
||||
add a new `index.html` file with the following HTML
|
||||
|
||||
+makeExample('gettingstarted/ts/src/index.html', null, 'index.html')
|
||||
+makeExample('gettingstarted/ts/src/index.html', null, 'index.html',
|
||||
{pnk: [/(angular2\.dev\.js)/, /(system\.src\.js)/, /(traceur-runtime\.js)/]})
|
||||
|
||||
.l-sub-section
|
||||
:markdown
|
||||
Notice in the `<head>` element that we're loading the scripts we installed earlier with npm.
|
||||
|
||||
There's an element called `<app>` in the `<body>`. This is a placeholder for the *root* of our
|
||||
There's an element called `<my-app>` in the `<body>`. This is a placeholder for the *root* of our
|
||||
application. Angular will display our application content here.
|
||||
|
||||
The final inline script tells *system.js* to load another JavaScript file named "app".
|
||||
We haven't written that file yet; let's do so now.
|
||||
The final inline script first configures the **`system.js`** module loader and then tells it
|
||||
to import the JavaScript file named `app` in the `app/` folder.
|
||||
|
||||
Subsequent module imports are triggered by a cascade of `import` statements
|
||||
beginning within `app.ts` itself.
|
||||
|
||||
**`app.ts`** is our main application file. We haven't written it yet. Let's do so now.
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Write the *app* component
|
||||
## Write the main application file, `app.ts`
|
||||
|
||||
Create an *app.ts* file and add an empty class called `AppComponent` as follows:
|
||||
**Change to the `src/app`** directory and **create an `app.ts` file**.
|
||||
|
||||
+makeExample('gettingstarted/ts/src/app.ts', 'class')
|
||||
Add an empty class to it called `AppComponent` as follows:
|
||||
|
||||
+makeExample('gettingstarted/ts/src/app/app.ts', 'class')(format=".")
|
||||
|
||||
:markdown
|
||||
We won't ask this class to do anything. It's just an empty, meaningless class until we tell
|
||||
Angular about it by decorating it with some *annotations*.
|
||||
|
||||
We import the `component` and `view` *annotations* that we need from the Angular library at the top of the file:
|
||||
Import the `component` and `view` *annotations* that we need from the Angular library at the top of the file:
|
||||
|
||||
+makeExample('gettingstarted/ts/src/app.ts', 'import')
|
||||
+makeExample('gettingstarted/ts/src/app/app.ts', 'import')(format=".")
|
||||
|
||||
:markdown
|
||||
Then we apply those annotations to the `AppComponent` class by writing the following lines
|
||||
Apply those annotations to the `AppComponent` class by writing the following lines
|
||||
just above the class definition:
|
||||
|
||||
+makeExample('gettingstarted/ts/src/app.ts', 'class-w-annotations')
|
||||
+makeExample('gettingstarted/ts/src/app/app.ts', 'class-w-annotations')
|
||||
|
||||
.l-sub-section
|
||||
:markdown
|
||||
|
|
@ -201,13 +266,34 @@ include ../../../../_includes/_util-fns
|
|||
with an instance of the `AppComponent` class as the root component.
|
||||
We call this "bootstrapping the app".
|
||||
|
||||
+makeExample('gettingstarted/ts/src/app.ts', 'bootstrap')
|
||||
+makeExample('gettingstarted/ts/src/app/app.ts', 'bootstrap')(format=".")
|
||||
|
||||
:markdown
|
||||
Here is the complete *app.ts*
|
||||
Here is the complete `app.ts`
|
||||
|
||||
+makeExample('gettingstarted/ts/src/app.ts', null, 'app.ts')
|
||||
+makeExample('gettingstarted/ts/src/app/app.ts', null, 'app.ts')
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Confirm the final project and file structure
|
||||
|
||||
```
|
||||
angular2-getting-started
|
||||
├── node_modules
|
||||
├── src
|
||||
│ ├── app
|
||||
│ │ ├── app.ts
|
||||
│ ├── typings
|
||||
│ │ ├── tsd.d.ts
|
||||
│ ├── index.html
|
||||
│ ├── tsconfig.json
|
||||
└── package.json
|
||||
```
|
||||
Seems like overkill for such a trivial application.
|
||||
|
||||
We have ambitions. We aren't learning Angular to build "Hello, World". We intend
|
||||
to build great apps and we anticipate adding meat to these bones
|
||||
in the "Tour of Heroes" tutorial coming up very soon.
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
|
|
@ -238,7 +324,7 @@ include ../../../../_includes/_util-fns
|
|||
launch a node static server such as the *live-server* we recommended earlier:
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code live-server --open src
|
||||
code live-server --open=src
|
||||
|
||||
:markdown
|
||||
**live-server** loads the browser for us, serves the HTML and JavaScript files, and we should see it display our
|
||||
|
|
@ -258,35 +344,6 @@ include ../../../../_includes/_util-fns
|
|||
|
||||
Pretty nice!
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Add Type Definition Files (optional)
|
||||
|
||||
Code editors (such as [Visual Studio Code](https://code.visualstudio.com/) and
|
||||
[Web Storm](https://www.jetbrains.com/webstorm/features/))
|
||||
improve the development experience by checking type information and
|
||||
displaying API documentation ("intellisense") based on TypeScript type definition files.
|
||||
|
||||
We can download type definitions files for third-party libraries such as Angular
|
||||
from the [DefinitelyTyped](http://definitelytyped.org/) repository using the
|
||||
[**tsd package manager**](https://www.npmjs.com/package/tsd "TSD Package Manager")
|
||||
that we installed earlier.
|
||||
|
||||
Let's download and install the core set of type definitions files for Angular development
|
||||
in the ***src* folder** of our application.
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code tsd install angular2 es6-promise rx rx-lite --save
|
||||
|
||||
:markdown
|
||||
We'll find a new ***typings*** folder
|
||||
with subfolders for each of the downloaded type definition files (angular, es6-promise, rx, and rx-lite).
|
||||
Type definition files have names ending in ***d.ts***.
|
||||
There's also a summary ***tsd.d.ts*** file containing references to each of them.
|
||||
|
||||
Check your editor's documentation for instructions on using the *tsd.d.ts* file to
|
||||
light up type checking and intellisense for these libraries.
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## It's all a tree
|
||||
|
|
|
|||
Loading…
Reference in New Issue