From b7ee01600059769cffd7d4de1ec726db3f92c7bf Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Tue, 15 Sep 2015 01:28:29 -0700 Subject: [PATCH] (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 --- .../docs/_examples/gettingstarted/e2e-spec.js | 2 +- .../docs/_examples/gettingstarted/js/app.js | 2 +- .../_examples/gettingstarted/ts/README.md | 4 +- .../_examples/gettingstarted/ts/package.json | 23 +- .../gettingstarted/ts/src/{ => app}/app.ts | 12 +- .../gettingstarted/ts/src/dummy.spec.ts | 9 - .../gettingstarted/ts/src/index.html | 14 +- .../gettingstarted/ts/src/tsconfig.json | 4 +- .../_examples/gettingstarted/ts/src/tsd.json | 24 -- public/docs/_examples/styleguide/package.json | 7 +- .../docs/js/latest/guide/gettingStarted.jade | 2 +- .../docs/ts/latest/guide/gettingStarted.jade | 259 +++++++++++------- 12 files changed, 194 insertions(+), 168 deletions(-) rename public/docs/_examples/gettingstarted/ts/src/{ => app}/app.ts (63%) delete mode 100644 public/docs/_examples/gettingstarted/ts/src/dummy.spec.ts delete mode 100644 public/docs/_examples/gettingstarted/ts/src/tsd.json diff --git a/public/docs/_examples/gettingstarted/e2e-spec.js b/public/docs/_examples/gettingstarted/e2e-spec.js index bbb8089d9f..e479cea085 100644 --- a/public/docs/_examples/gettingstarted/e2e-spec.js +++ b/public/docs/_examples/gettingstarted/e2e-spec.js @@ -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 diff --git a/public/docs/_examples/gettingstarted/js/app.js b/public/docs/_examples/gettingstarted/js/app.js index a590cd7ed7..13c1bad380 100644 --- a/public/docs/_examples/gettingstarted/js/app.js +++ b/public/docs/_examples/gettingstarted/js/app.js @@ -9,7 +9,7 @@ var AppComponent = ng // #enddocregion // #docregion view .View({ - template: '

My First Angular 2 App

' + template: '

My First Angular 2 App

' }) // #enddocregion // #docregion class diff --git a/public/docs/_examples/gettingstarted/ts/README.md b/public/docs/_examples/gettingstarted/ts/README.md index e11db48702..8c381820ad 100644 --- a/public/docs/_examples/gettingstarted/ts/README.md +++ b/public/docs/_examples/gettingstarted/ts/README.md @@ -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. diff --git a/public/docs/_examples/gettingstarted/ts/package.json b/public/docs/_examples/gettingstarted/ts/package.json index 353c02007e..d9de287642 100644 --- a/public/docs/_examples/gettingstarted/ts/package.json +++ b/public/docs/_examples/gettingstarted/ts/package.json @@ -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" } } diff --git a/public/docs/_examples/gettingstarted/ts/src/app.ts b/public/docs/_examples/gettingstarted/ts/src/app/app.ts similarity index 63% rename from public/docs/_examples/gettingstarted/ts/src/app.ts rename to public/docs/_examples/gettingstarted/ts/src/app/app.ts index 1e6cd84e77..330cebdbd2 100644 --- a/public/docs/_examples/gettingstarted/ts/src/app.ts +++ b/public/docs/_examples/gettingstarted/ts/src/app/app.ts @@ -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: '

My First Angular 2 App

' + template: '

My First Angular 2 App

' }) // #docregion class class AppComponent { } -// #enddocregion -// #enddocregion +// #enddocregion class +// #enddocregion class-w-annotations // #docregion bootstrap bootstrap(AppComponent); -// #enddocregion -// #enddocregion \ No newline at end of file +// #enddocregion bootstrap diff --git a/public/docs/_examples/gettingstarted/ts/src/dummy.spec.ts b/public/docs/_examples/gettingstarted/ts/src/dummy.spec.ts deleted file mode 100644 index fdf13c8cfc..0000000000 --- a/public/docs/_examples/gettingstarted/ts/src/dummy.spec.ts +++ /dev/null @@ -1,9 +0,0 @@ -describe("Jasmine sample test", function() { - - it("1+1 should be 2", function() { - - var result = 1 + 1; - - expect(result).toBe(2); - }); -}); \ No newline at end of file diff --git a/public/docs/_examples/gettingstarted/ts/src/index.html b/public/docs/_examples/gettingstarted/ts/src/index.html index fbd6880194..7c6a89ccc4 100644 --- a/public/docs/_examples/gettingstarted/ts/src/index.html +++ b/public/docs/_examples/gettingstarted/ts/src/index.html @@ -1,16 +1,20 @@ - + - + - + Loading... - + + \ No newline at end of file diff --git a/public/docs/_examples/gettingstarted/ts/src/tsconfig.json b/public/docs/_examples/gettingstarted/ts/src/tsconfig.json index 24f8573a6f..1074588bb8 100644 --- a/public/docs/_examples/gettingstarted/ts/src/tsconfig.json +++ b/public/docs/_examples/gettingstarted/ts/src/tsconfig.json @@ -4,6 +4,8 @@ "module": "commonjs", "sourceMap": true, "emitDecoratorMetadata": true, - "experimentalDecorators": true + "experimentalDecorators": true, + "removeComments": false, + "noImplicitAny": true } } \ No newline at end of file diff --git a/public/docs/_examples/gettingstarted/ts/src/tsd.json b/public/docs/_examples/gettingstarted/ts/src/tsd.json deleted file mode 100644 index 0bed83f7e6..0000000000 --- a/public/docs/_examples/gettingstarted/ts/src/tsd.json +++ /dev/null @@ -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" - } - } -} diff --git a/public/docs/_examples/styleguide/package.json b/public/docs/_examples/styleguide/package.json index 9360e0ecaf..a1cf0d7df3 100644 --- a/public/docs/_examples/styleguide/package.json +++ b/public/docs/_examples/styleguide/package.json @@ -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": { diff --git a/public/docs/js/latest/guide/gettingStarted.jade b/public/docs/js/latest/guide/gettingStarted.jade index e23d9e3bb8..76d97efad0 100644 --- a/public/docs/js/latest/guide/gettingStarted.jade +++ b/public/docs/js/latest/guide/gettingStarted.jade @@ -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 diff --git a/public/docs/ts/latest/guide/gettingStarted.jade b/public/docs/ts/latest/guide/gettingStarted.jade index 3e2b3eec24..4f3ac55c77 100644 --- a/public/docs/ts/latest/guide/gettingStarted.jade +++ b/public/docs/ts/latest/guide/gettingStarted.jade @@ -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 `` element that we're loading the scripts we installed earlier with npm. - There's an element called `` in the ``. This is a placeholder for the *root* of our + There's an element called `` in the ``. 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