267 lines
9.8 KiB
Plaintext
267 lines
9.8 KiB
Plaintext
|
include ../../../../_includes/_util-fns
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
Let's start from zero and build a simple Angular 2 application in TypeScript.
|
||
|
|
|
||
|
|
.callout.is-helpful
|
||
|
|
header Don't want TypeScript?
|
||
|
|
:markdown
|
||
|
|
Although we're getting started in TypeScript, you can also write Angular 2 apps
|
||
|
|
in JavaScript and Dart by selecting either of those languages from the combo-box in the banner.
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
We'll do it in seven short steps
|
||
|
|
1. Install the prerequisites for Angular TypeScript development
|
||
|
|
1. Create a new project folder and configure TypeScript
|
||
|
|
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
|
||
|
|
|
||
|
|
.l-main-section
|
||
|
|
|
||
|
|
: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").
|
||
|
|
|
||
|
|
Now use npm in a terminal (or Windows/Linux command line) to install the **TypeScript compiler** globally
|
||
|
|
|
||
|
|
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 ("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 the static files of our application.
|
||
|
|
|
||
|
|
.alert.is-helpful
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
You can skip this step if you've got python on your machine because python ships with a static server.
|
||
|
|
Or you can install one of the many node-based static servers such as
|
||
|
|
[http-server](https:/github.com/nodeapps/http-server "http-server"),
|
||
|
|
[superstatic](https://www.npmjs.com/package/superstatic "superstatic"), or
|
||
|
|
[live-server](https://www.npmjs.com/package/live-server "live-server").
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
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
|
||
|
|
|
||
|
|
.l-main-section
|
||
|
|
:markdown
|
||
|
|
## Create a project folder and configure TypeScript
|
||
|
|
|
||
|
|
Create a new folder to hold our application project, perhaps like this:
|
||
|
|
|
||
|
|
pre.prettyprint.lang-bash
|
||
|
|
code mkdir firstNgApp && cd firstNgApp
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
We prefer writing TypeScript apps in an editor that understands TypeScript,
|
||
|
|
an editor such as [Visual Studio Code](https://code.visualstudio.com/) or
|
||
|
|
[Web Storm](https://www.jetbrains.com/webstorm/features/).
|
||
|
|
|
||
|
|
We should tell that editor how to compile TypeScript to JavaScript
|
||
|
|
with a configuration file named **tsconfig.json**.
|
||
|
|
This configuration file also simplifies the TypeScript compilation command we'll run later in this story.
|
||
|
|
|
||
|
|
Create *tsconfig.json* now with the following JSON content:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"compilerOptions": {
|
||
|
|
"target": "ES5",
|
||
|
|
"module": "commonjs",
|
||
|
|
"sourceMap": true,
|
||
|
|
"emitDecoratorMetadata": true,
|
||
|
|
"experimentalDecorators": true
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
.l-main-section
|
||
|
|
:markdown
|
||
|
|
## Create an *index.html*
|
||
|
|
|
||
|
|
Add a new `index.html` file to the project folder and enter the following HTML
|
||
|
|
|
||
|
|
+makeExample('gettingstarted', 'ts/index.html', 'index.html')
|
||
|
|
|
||
|
|
.l-sub-section
|
||
|
|
:markdown
|
||
|
|
Our app loads three script files in the `<head>` element:
|
||
|
|
|
||
|
|
>***traceur-runtime.js*** to transpile the TypeScript-generated JavaScript into the version of Javascript
|
||
|
|
our browser understands (the version known as "ES5").
|
||
|
|
|
||
|
|
>***system.js***, a third-party open-source library that adds module loading functionality to our browser.
|
||
|
|
|
||
|
|
>***angular.js***, the Angular 2 library.
|
||
|
|
|
||
|
|
In the `<body>`, there's an element called `<my-app>`. 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.
|
||
|
|
|
||
|
|
.l-main-section
|
||
|
|
:markdown
|
||
|
|
## Write the *app* component
|
||
|
|
|
||
|
|
Create an *app.ts* file and add an empty class called `AppComponent` as follows:
|
||
|
|
|
||
|
|
+makeExample('gettingstarted', 'ts/app-class.ts')
|
||
|
|
|
||
|
|
: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:
|
||
|
|
|
||
|
|
+makeExample('gettingstarted', 'ts/app-import.ts')
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
Then we apply those annotations to the `AppComponent` class by writing the following lines
|
||
|
|
just above the class definition:
|
||
|
|
|
||
|
|
+makeExample('gettingstarted', 'ts/app-class-w-annotations.ts')
|
||
|
|
|
||
|
|
.l-sub-section
|
||
|
|
:markdown
|
||
|
|
TypeScript recognizes the `@` symbol as a prefix for a class annotation.
|
||
|
|
|
||
|
|
The **`@Component`** annotation tells Angular this class is a component
|
||
|
|
that controls the element named "my-app".
|
||
|
|
You may remember we added such an element to our *index.html* above.
|
||
|
|
|
||
|
|
The **`@View`** annotation identifies the "view" - the HTML template -
|
||
|
|
that defines the visual appearance of this component. We're writing the HTML template inline
|
||
|
|
in this example. Later we'll move the HTML to a view template file and
|
||
|
|
assign the template's filename to the `templateUrl`.
|
||
|
|
We'll prefer that practice for all but the most trivial templates.
|
||
|
|
|
||
|
|
.l-main-section
|
||
|
|
:markdown
|
||
|
|
## Bootstrap the app
|
||
|
|
|
||
|
|
Finally, we tell Angular to start running our app
|
||
|
|
with an instance of the `AppComponent` class as the root component.
|
||
|
|
We call this "bootstrapping the app".
|
||
|
|
|
||
|
|
+makeExample('gettingstarted', 'ts/app-bootstrap.ts')
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
Here is the complete *app.ts*
|
||
|
|
|
||
|
|
+makeExample('gettingstarted', 'ts/app.ts', 'app.ts')
|
||
|
|
|
||
|
|
|
||
|
|
.l-main-section
|
||
|
|
:markdown
|
||
|
|
## Compile the TypeScript to JavaScript
|
||
|
|
|
||
|
|
We've written our app in TypeScript but the browser only understands JavaScript.
|
||
|
|
We must run the TypeScript compiler to produce JavaScript for the browser.
|
||
|
|
|
||
|
|
Open a terminal window in the root of the code director and enter:
|
||
|
|
|
||
|
|
pre.prettyprint.lang-bash
|
||
|
|
code tsc
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
After it runs we should find the generated *app.js* file in the project folder and also an *app.map.js* file that
|
||
|
|
helps debuggers navigate between the JavaScript and the TypeScript source.
|
||
|
|
|
||
|
|
.l-main-section
|
||
|
|
:markdown
|
||
|
|
## Run it!
|
||
|
|
|
||
|
|
Now we can see this app in action by serving the files we created with a local web server.
|
||
|
|
|
||
|
|
Open a another terminal window in the root of the code directory and launch the server.
|
||
|
|
|
||
|
|
If we have python installed on our machine, we can run a basic HTTP server:
|
||
|
|
|
||
|
|
pre.prettyprint.lang-bash
|
||
|
|
code python -m SimpleHTTPServer 8000
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
then point a browser to http://localhost:8000 which should display our simple text message:
|
||
|
|
|
||
|
|
figure.image-display
|
||
|
|
img(src='/resources/images/examples/setup-example1.png' alt="Example of Todo App")
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
Alternatively, we might run with a node server such as the *live-server* we recommended earlier:
|
||
|
|
|
||
|
|
pre.prettyprint.lang-bash
|
||
|
|
code live-server --port=8000
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
**live-server** loads the browser for us and refreshes the page as we make
|
||
|
|
changes to the application. *Check it out!*
|
||
|
|
|
||
|
|
.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 root directory of our application.
|
||
|
|
|
||
|
|
pre.prettyprint.lang-bash
|
||
|
|
code tsd query angular2 es6-promise rx rx-lite jasmine --action install --save
|
||
|
|
|
||
|
|
:markdown
|
||
|
|
We'll find a ***typings*** folder in the root directory
|
||
|
|
with subfolders for each of the five downloaded type definition files (angular, es6-promise, rx, rx-lite, jasmine).
|
||
|
|
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
|
||
|
|
|
||
|
|
We can think of Angular apps as a tree of components.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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 `<my-app>` but there is nothing special about this
|
||
|
|
name either.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
And these components could load yet more components until the browser page became a deep tree
|
||
|
|
of nested functionality.
|
||
|
|
|
||
|
|
We'll walk through examples of these scenarios in the following pages.
|