diff --git a/public/docs/_examples/gettingstarted/ts/README.md b/public/docs/_examples/gettingstarted/ts/README.md deleted file mode 100644 index 8c381820ad..0000000000 --- a/public/docs/_examples/gettingstarted/ts/README.md +++ /dev/null @@ -1,8 +0,0 @@ -#Getting Started (TS) for the DevGuide developer - -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. - -* **tsd.json** - as the audience will see it; the example reaches up to the example level typings \ No newline at end of file diff --git a/public/docs/_examples/gettingstarted/ts/package.json b/public/docs/_examples/gettingstarted/ts/package.json index d9de287642..1a9dcbf5ea 100644 --- a/public/docs/_examples/gettingstarted/ts/package.json +++ b/public/docs/_examples/gettingstarted/ts/package.json @@ -10,7 +10,7 @@ "author": "", "license": "ISC", "dependencies": { - "angular2": "^2.0.0-alpha.37", - "systemjs": "^0.19.2" + "angular2": "2.0.0-alpha.38", + "systemjs": "0.19.2" } } diff --git a/public/docs/ts/latest/guide/gettingStarted.jade b/public/docs/ts/latest/guide/gettingStarted.jade index 4f3ac55c77..11131b2569 100644 --- a/public/docs/ts/latest/guide/gettingStarted.jade +++ b/public/docs/ts/latest/guide/gettingStarted.jade @@ -26,34 +26,27 @@ include ../../../../_includes/_util-fns :markdown ## Prerequisites - We'll need a base of tools for all of our application development. We'll only install these once starting with - [**node** and **npm**](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm"). + We'll need a base of tools for our application development throughout this guide: - Now use npm in a terminal (or Windows/Linux command line) to install the **TypeScript compiler** globally + - the **TypeScript compiler** + + - the [**tsd package manager**](https://www.npmjs.com/package/tsd "TSD Package Manager") so we can access + [TypeScript type definition files](http://definitelytyped.org/ "Definitely Typed") ("`.d.ts`" files). + + - **live-server**, a *static server* that runs our app in the browser and reloads the browser when any of the files change. + + **Open** a terminal (or Windows/Linux command line) and issue the following `npm` command to install them all: pre.prettyprint.lang-bash - code npm install -g typescript - - :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 files ("`.d.ts`" files) - from the [DefinitelyTyped](http://definitelytyped.org/) repository. - - pre.prettyprint.lang-bash - code npm install -g tsd - - :markdown - Install a node **static server** to serve our application. - We'll use **live-server** for this example because it performs a live reload by default and it's - fun to watch the browser update as we make changes. - - pre.prettyprint.lang-bash - code npm install -g live-server + code npm install -g typescript tsd 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: + We depend upon [**node** and **npm**](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm") + to install packages such as these global tools. + + We must be sure that we're installing Angular-compatible versions of these packages. + Issue the following commands in that same terminal window to confirm that we have the appropriate versions: table tr th Command @@ -118,26 +111,21 @@ include ../../../../_includes/_util-fns :markdown ## Install npm packages - Our application will need some 3rd party JavaScript files: + We need to install two JavaScript library packages: >***angular.js***, the Angular 2 library. - >***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"). + >***system.js***, an open-source library that provides module loading. We'll install these package with `npm` and create an npm **`package.json`** configuration file - that to maintain future packages as our application evolves. + to maintain them as our application evolves. In a terminal window, go to the **root** folder and type: ``` npm init -y - npm install --save angular2@2.0.0-alpha.37 systemjs@0.19.2 + npm i angular2@2.0.0-alpha.38 systemjs@0.19.2 --save --save-exact ``` - `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 '}) @@ -150,7 +138,6 @@ include ../../../../_includes/_util-fns 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`). @@ -174,16 +161,15 @@ include ../../../../_includes/_util-fns ### 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 - that we'll run very soon. + We'll add a configuration file named **`tsconfig.json`** + to tell the editor how to interpret our TypeScript code and + to simplify the TypeScript compilation command that we'll run very soon. **Change to the `src` folder and create a `tsconfig.json`** file with the following content: +makeJson('gettingstarted/ts/src/tsconfig.json', null, 'tsconfig.json') :markdown - Our project should now look like this: + Our project folder structure should now look like this: ``` angular2-getting-started ├── node_modules @@ -199,24 +185,20 @@ include ../../../../_includes/_util-fns :markdown ## Create an `index.html` - While in the **`src`** directory and - add a new `index.html` file with the following HTML + While in the **`src`** directory we + add a new `index.html` file with the following content - +makeExample('gettingstarted/ts/src/index.html', null, 'index.html', - {pnk: [/(angular2\.dev\.js)/, /(system\.src\.js)/, /(traceur-runtime\.js)/]}) + +makeExample('gettingstarted/ts/src/index.html', null, 'index.html') .l-sub-section :markdown - Notice in the `` element that we're loading the scripts we installed earlier with npm. + We're loading the library scripts in the `` element from the `node_modules` + that we installed earlier with npm. - There's an element called `` in the ``. This is a placeholder for the *root* of our - application. Angular will display our application content here. + In the `` is the app root element called `` where Angular displays our application content. - 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. + The final inline script configures the **`system.js`** module loader and tells it + to import the *application file* named `app` from within the *folder* named `app/`. **`app.ts`** is our main application file. We haven't written it yet. Let's do so now. @@ -277,6 +259,8 @@ include ../../../../_includes/_util-fns :markdown ## Confirm the final project and file structure + It should look like this + ``` angular2-getting-started ├── node_modules @@ -289,11 +273,6 @@ include ../../../../_includes/_util-fns │ ├── 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 @@ -331,7 +310,7 @@ include ../../../../_includes/_util-fns application message: figure.image-display - img(src='/resources/images/examples/setup-example1.png' alt="Example of Todo App") + img(src='/resources/images/devguide/getting-started/my-first-app.png' alt="Output of getting started app") :markdown ### Make some changes @@ -342,27 +321,35 @@ include ../../../../_includes/_util-fns The TypeScript compiler running in the first terminal window is watching our source code. It recompiles and produces the revised *app.js*. The *live-server* sees that change and reloads the browser. - Pretty nice! - .l-main-section :markdown - ## It's all a tree + ## Why so complicated? + To display a single line of text we - We can think of Angular apps as a tree of components. + * installed a bunch of unfamiliar tools + * loaded a couple of libraries + * wrote configuration files for both `npm` and TypeScript + * configured something called `system.js` in our `index.html` and + told it to import our main file + * are compiling TypeScript in one terminal window and running the server in another - The `AppComponent` that we've been talking about acts as the top - level container - the root of the tree - for the rest of our application. - There's nothing special about the `AppComponent` name and we can use whatever makes sense to us. + Perhaps we were expecting something simpler: an Angular library, + our application script, and a little HTML. This is all a bit much for a "Hello, World" app. - We've pinned the root component to an element in the `index.html` file where our application will - render its view. The element is called `` but there is nothing special about this - name either. + **We have greater ambitions.** - The *root component* loads the initial template for the application. - That template could load other components such as menu bars, views, and forms - that display information and respond to user gestures. + We won't ask Angular to build "Hello, World". + We are asking it to help us build sophisticated applications with sophisticated requirements. + We're making strategic technology investments to reach our goals - And these components could load yet more components until the browser page became a deep tree - of nested functionality. + * writing the app in TypeScript for team + productivity and maintainability. - We'll walk through examples of these scenarios in the following pages. + * designing with modules that we can load features dynamically + using the latest JavaScript `import` and `export` verbs. + + * running compiler and live-server commands that give us immediate feedback as we make changes. + + The good news is that the overhead of setup is (mostly) behind us. + We're about to build a small application that demonstrates the great things + we can build with Angular 2. Join us on the [Tour of Heroes]. diff --git a/public/resources/images/examples/setup-example1.png b/public/resources/images/devguide/getting-started/my-first-app.png similarity index 100% rename from public/resources/images/examples/setup-example1.png rename to public/resources/images/devguide/getting-started/my-first-app.png