docs: quickstart reboot for Dart (#2867)
* cache/quickstart sync before making Dart edits * quickstart updates for Dart * cache/guide/index sync before making Dart edits * guide/index updates for Dart * learning-angular for Dart * guide/setup for Dart * refresh cache/tutorial/index
This commit is contained in:
Patrice Chalin
Filipe Silva
parent
7a651ed873
commit
692d751375
1
.gitignore
vendored
1
.gitignore
vendored
@ -32,3 +32,4 @@ public/docs/*/latest/guide/cheatsheet.json
|
|||||||
protractor-results.txt
|
protractor-results.txt
|
||||||
link-checker-results.txt
|
link-checker-results.txt
|
||||||
*a2docs.css
|
*a2docs.css
|
||||||
|
/dist
|
||||||
@ -39,7 +39,10 @@
|
|||||||
- var _liveLink = 'live link';
|
- var _liveLink = 'live link';
|
||||||
- var _ngRepoURL = 'https://github.com/angular/angular';
|
- var _ngRepoURL = 'https://github.com/angular/angular';
|
||||||
- var _ngDocRepoURL = 'https://github.com/angular/angular.io';
|
- var _ngDocRepoURL = 'https://github.com/angular/angular.io';
|
||||||
- var _qsRepo = 'https://github.com/angular/quickstart/blob/master/README.md'
|
- var _qsRepo = 'https://github.com/angular/quickstart';
|
||||||
|
- var _qsRepoZip = _qsRepo + '/archive/master.zip';
|
||||||
|
|
||||||
|
- var _npm = 'npm';
|
||||||
|
|
||||||
//- NgModule related
|
//- NgModule related
|
||||||
- var _AppModuleVsAppComp = 'AppModule'
|
- var _AppModuleVsAppComp = 'AppModule'
|
||||||
|
|||||||
@ -1,11 +1,9 @@
|
|||||||
// #docregion , import
|
// #docregion
|
||||||
import 'package:angular2/core.dart';
|
import 'package:angular2/core.dart';
|
||||||
// #enddocregion import
|
|
||||||
|
|
||||||
// #docregion metadata
|
|
||||||
@Component(
|
@Component(
|
||||||
selector: 'my-app',
|
selector: 'my-app',
|
||||||
template: '<h1>Hello Angular</h1>')
|
template: '<h1>Hello {{name}}</h1>')
|
||||||
// #enddocregion metadata
|
class AppComponent {
|
||||||
// #docregion class
|
var name = 'Angular';
|
||||||
class AppComponent {}
|
}
|
||||||
|
|||||||
@ -2,7 +2,9 @@
|
|||||||
<!DOCTYPE html>
|
<!DOCTYPE html>
|
||||||
<html>
|
<html>
|
||||||
<head>
|
<head>
|
||||||
<title>Getting Started</title>
|
<title>Hello Angular</title>
|
||||||
|
<meta charset="UTF-8">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
<link rel="stylesheet" href="styles.css">
|
<link rel="stylesheet" href="styles.css">
|
||||||
|
|
||||||
<!-- #docregion loaddart -->
|
<!-- #docregion loaddart -->
|
||||||
@ -11,6 +13,8 @@
|
|||||||
<!-- #enddocregion loaddart -->
|
<!-- #enddocregion loaddart -->
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
<my-app>Loading...</my-app>
|
<!-- #docregion my-app-->
|
||||||
|
<my-app>Loading AppComponent content here ...</my-app>
|
||||||
|
<!-- #enddocregion my-app-->
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|||||||
@ -7,12 +7,19 @@
|
|||||||
"banner": "AngularDart is <b>2.0</b>. View the <a href='https://github.com/dart-lang/angular2/blob/master/CHANGELOG.md' target='_blank'>change log</a> to see enhancements, fixes, and breaking changes."
|
"banner": "AngularDart is <b>2.0</b>. View the <a href='https://github.com/dart-lang/angular2/blob/master/CHANGELOG.md' target='_blank'>change log</a> to see enhancements, fixes, and breaking changes."
|
||||||
},
|
},
|
||||||
|
|
||||||
|
"cli-quickstart": {
|
||||||
|
"icon": "query-builder",
|
||||||
|
"title": "CLI Quickstart",
|
||||||
|
"subtitle": "TypeScript",
|
||||||
|
"description": "Use the CLI tool to quickly build Angular applications",
|
||||||
|
"hide": true
|
||||||
|
},
|
||||||
|
|
||||||
"quickstart": {
|
"quickstart": {
|
||||||
"icon": "query-builder",
|
"icon": "query-builder",
|
||||||
"title": "Quickstart",
|
"title": "Quickstart",
|
||||||
"subtitle": "Dart",
|
"subtitle": "Dart",
|
||||||
"description": "Get up and running with Angular",
|
"banner": "A quick look at Angular basics"
|
||||||
"banner": "This QuickStart guide demonstrates how to build and run a simple Angular application."
|
|
||||||
},
|
},
|
||||||
|
|
||||||
"tutorial": {
|
"tutorial": {
|
||||||
|
|||||||
@ -22,7 +22,10 @@ include ../../../_includes/_util-fns
|
|||||||
- var _ngRepoURL = 'https://github.com/dart-lang/angular2';
|
- var _ngRepoURL = 'https://github.com/dart-lang/angular2';
|
||||||
//- Don't override this value quite yet:
|
//- Don't override this value quite yet:
|
||||||
//- var _ngDocRepoURL = 'https://github.com/dart-lang/site-webdev';
|
//- var _ngDocRepoURL = 'https://github.com/dart-lang/site-webdev';
|
||||||
- var _qsRepo = 'https://github.com/angular-examples/quickstart/archive/master.zip'
|
- var _qsRepo = 'https://github.com/angular-examples/quickstart'
|
||||||
|
- var _qsRepoZip = _qsRepo + '/archive/master.zip';
|
||||||
|
|
||||||
|
- var _npm = 'pub';
|
||||||
|
|
||||||
//- NgModule related
|
//- NgModule related
|
||||||
- var _AppModuleVsAppComp = 'AppComponent'
|
- var _AppModuleVsAppComp = 'AppComponent'
|
||||||
|
|||||||
@ -2,11 +2,29 @@
|
|||||||
"index": {
|
"index": {
|
||||||
"title": "Documentation Overview",
|
"title": "Documentation Overview",
|
||||||
"navTitle": "Overview",
|
"navTitle": "Overview",
|
||||||
"description": "How to read and use this documentation",
|
"intro": "How to read and use this documentation",
|
||||||
"nextable": true,
|
"nextable": true,
|
||||||
"basics": true
|
"basics": true
|
||||||
},
|
},
|
||||||
|
|
||||||
|
"setup": {
|
||||||
|
"title": "Setup for local development",
|
||||||
|
"navTitle": "Setup",
|
||||||
|
"intro": "Install the Angular QuickStart seed for faster, more efficient development on your machine",
|
||||||
|
"nextable": true,
|
||||||
|
"hideNextPage": true,
|
||||||
|
"basics": true
|
||||||
|
},
|
||||||
|
|
||||||
|
"learning-angular": {
|
||||||
|
"title": "Learning Angular",
|
||||||
|
"navTitle": "Learning Angular",
|
||||||
|
"intro": "A suggested path through the documentation for Angular newcomers",
|
||||||
|
"nextable": true,
|
||||||
|
"hideNextPage": true,
|
||||||
|
"basics": true
|
||||||
|
},
|
||||||
|
|
||||||
"architecture": {
|
"architecture": {
|
||||||
"title": "Architecture Overview",
|
"title": "Architecture Overview",
|
||||||
"navTitle": "Architecture",
|
"navTitle": "Architecture",
|
||||||
@ -17,7 +35,7 @@
|
|||||||
|
|
||||||
"displaying-data": {
|
"displaying-data": {
|
||||||
"title": "Displaying Data",
|
"title": "Displaying Data",
|
||||||
"intro": "Interpolation and other forms of property binding help us show app data in the UI.",
|
"intro": "Property binding helps show app data in the UI.",
|
||||||
"nextable": true,
|
"nextable": true,
|
||||||
"basics": true
|
"basics": true
|
||||||
},
|
},
|
||||||
@ -63,16 +81,29 @@
|
|||||||
"basics": true
|
"basics": true
|
||||||
},
|
},
|
||||||
|
|
||||||
|
"glossary": {
|
||||||
|
"title": "Glossary",
|
||||||
|
"intro": "Brief definitions of the most important words in the Angular vocabulary",
|
||||||
|
"basics": true
|
||||||
|
},
|
||||||
|
|
||||||
|
"change-log": {
|
||||||
|
"hide": true,
|
||||||
|
"title": "Change Log",
|
||||||
|
"intro": "An annotated history of recent documentation improvements.",
|
||||||
|
"basics": true
|
||||||
|
},
|
||||||
|
|
||||||
"ngmodule": {
|
"ngmodule": {
|
||||||
|
"hide": true,
|
||||||
"title": "Angular Modules (NgModule)",
|
"title": "Angular Modules (NgModule)",
|
||||||
"intro": "Define application modules with @NgModule",
|
"intro": "Define application modules with @NgModule"
|
||||||
"hide": true
|
|
||||||
},
|
},
|
||||||
|
|
||||||
"animations": {
|
"animations": {
|
||||||
|
"hide": true,
|
||||||
"title": "Animations",
|
"title": "Animations",
|
||||||
"intro": "A guide to Angular's animation system.",
|
"intro": "A guide to Angular's animation system."
|
||||||
"hide": true
|
|
||||||
},
|
},
|
||||||
|
|
||||||
"attribute-directives": {
|
"attribute-directives": {
|
||||||
@ -90,12 +121,6 @@
|
|||||||
"intro": "Learn how to apply CSS styles to components."
|
"intro": "Learn how to apply CSS styles to components."
|
||||||
},
|
},
|
||||||
|
|
||||||
"glossary": {
|
|
||||||
"title": "Glossary",
|
|
||||||
"intro": "Brief definitions of the most important words in the Angular vocabulary",
|
|
||||||
"basics": true
|
|
||||||
},
|
|
||||||
|
|
||||||
"hierarchical-dependency-injection": {
|
"hierarchical-dependency-injection": {
|
||||||
"title": "Hierarchical Dependency Injectors",
|
"title": "Hierarchical Dependency Injectors",
|
||||||
"navTitle": "Hierarchical Injectors",
|
"navTitle": "Hierarchical Injectors",
|
||||||
@ -104,7 +129,7 @@
|
|||||||
|
|
||||||
"server-communication": {
|
"server-communication": {
|
||||||
"title": "HTTP Client",
|
"title": "HTTP Client",
|
||||||
"intro": "Talk to a remote server with an HTTP Client."
|
"intro": "Use an HTTP Client to talk to a remote server."
|
||||||
},
|
},
|
||||||
|
|
||||||
"lifecycle-hooks": {
|
"lifecycle-hooks": {
|
||||||
@ -113,9 +138,9 @@
|
|||||||
},
|
},
|
||||||
|
|
||||||
"npm-packages": {
|
"npm-packages": {
|
||||||
|
"hide": true,
|
||||||
"title": "Npm Packages",
|
"title": "Npm Packages",
|
||||||
"intro": "Details of the recommended npm packages and the different kinds of package dependencies",
|
"intro": "Recommended npm packages, and how to specify package dependencies"
|
||||||
"hide": true
|
|
||||||
},
|
},
|
||||||
|
|
||||||
"pipes": {
|
"pipes": {
|
||||||
@ -125,7 +150,7 @@
|
|||||||
|
|
||||||
"router": {
|
"router": {
|
||||||
"title": "Routing & Navigation",
|
"title": "Routing & Navigation",
|
||||||
"intro": "Discover the basics of screen navigation with the Angular Component Router."
|
"intro": "Discover the basics of screen navigation with the Angular Router."
|
||||||
},
|
},
|
||||||
|
|
||||||
"security": {
|
"security": {
|
||||||
@ -133,32 +158,38 @@
|
|||||||
"intro": "Developing for content security in Angular applications"
|
"intro": "Developing for content security in Angular applications"
|
||||||
},
|
},
|
||||||
|
|
||||||
|
"setup-systemjs-anatomy": {
|
||||||
|
"hide": true,
|
||||||
|
"title": "Setup Anatomy",
|
||||||
|
"intro": "Inside the local development environment for SystemJS"
|
||||||
|
},
|
||||||
|
|
||||||
"structural-directives": {
|
"structural-directives": {
|
||||||
"title": "Structural Directives",
|
"title": "Structural Directives",
|
||||||
"intro": "Angular has a powerful template engine that lets us easily manipulate the DOM structure of our elements."
|
"intro": "Angular has a powerful template engine that lets us easily manipulate the DOM structure of our elements."
|
||||||
},
|
},
|
||||||
|
|
||||||
"testing": {
|
"testing": {
|
||||||
|
"hide": true,
|
||||||
"title": "Testing",
|
"title": "Testing",
|
||||||
"intro": "Techniques and practices for testing an Angular app",
|
"intro": "Techniques and practices for testing an Angular app"
|
||||||
"hide": true
|
|
||||||
},
|
},
|
||||||
|
|
||||||
"typescript-configuration": {
|
"typescript-configuration": {
|
||||||
|
"hide": true,
|
||||||
"title": "TypeScript Configuration",
|
"title": "TypeScript Configuration",
|
||||||
"intro": "TypeScript configuration for Angular developers",
|
"intro": "TypeScript configuration for Angular developers"
|
||||||
"hide": true
|
|
||||||
},
|
},
|
||||||
|
|
||||||
"upgrade": {
|
"upgrade": {
|
||||||
|
"hide": true,
|
||||||
"title": "Upgrading from 1.x",
|
"title": "Upgrading from 1.x",
|
||||||
"intro": "Angular 1 applications can be incrementally upgraded to Angular 2.",
|
"intro": "Incrementally upgrade an Angular 1 application to Angular 2."
|
||||||
"hide": true
|
|
||||||
},
|
},
|
||||||
|
|
||||||
"webpack": {
|
"webpack": {
|
||||||
|
"hide": true,
|
||||||
"title": "Webpack: an introduction",
|
"title": "Webpack: an introduction",
|
||||||
"intro": "Create your Angular applications with a Webpack based tooling",
|
"intro": "Create Angular applications with a Webpack based tooling"
|
||||||
"hide": true
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@ -2,3 +2,4 @@ extends ../../../ts/_cache/guide/index.jade
|
|||||||
|
|
||||||
block includes
|
block includes
|
||||||
include ../_util-fns
|
include ../_util-fns
|
||||||
|
- var _angular_io = 'website';
|
||||||
|
|||||||
4
public/docs/dart/latest/guide/learning-angular.jade
Normal file
4
public/docs/dart/latest/guide/learning-angular.jade
Normal file
@ -0,0 +1,4 @@
|
|||||||
|
extends ../../../ts/_cache/guide/learning-angular.jade
|
||||||
|
|
||||||
|
block includes
|
||||||
|
include ../_util-fns
|
||||||
58
public/docs/dart/latest/guide/setup.jade
Normal file
58
public/docs/dart/latest/guide/setup.jade
Normal file
@ -0,0 +1,58 @@
|
|||||||
|
extends ../../../ts/_cache/guide/setup.jade
|
||||||
|
|
||||||
|
block includes
|
||||||
|
include ../_util-fns
|
||||||
|
- var _prereq = 'the Dart SDK';
|
||||||
|
- var _playground = 'repository';
|
||||||
|
- var _Install = 'Get';
|
||||||
|
//- npm/pub commands
|
||||||
|
- var _install = 'get';
|
||||||
|
- var _start = 'serve';
|
||||||
|
|
||||||
|
block qs-seed
|
||||||
|
:marked
|
||||||
|
The <live-example name="quickstart">QuickStart project</live-example> can
|
||||||
|
conveniently be used to seed new projects. It contains the following core files:
|
||||||
|
|
||||||
|
block core-files
|
||||||
|
+makeTabs(`
|
||||||
|
quickstart/ts/app/app.component.ts,
|
||||||
|
quickstart/ts/app/main.ts,
|
||||||
|
quickstart/ts/index.html,
|
||||||
|
quickstart/dart/pubspec.yaml,
|
||||||
|
quickstart/ts/styles.css`,
|
||||||
|
',,,,quickstart',
|
||||||
|
`app/app.component.ts,
|
||||||
|
app/main.ts,
|
||||||
|
index.html,
|
||||||
|
pubspec.yaml,
|
||||||
|
styles.css (excerpt)`)
|
||||||
|
|
||||||
|
:marked
|
||||||
|
These files are organized as follows:
|
||||||
|
|
||||||
|
.filetree
|
||||||
|
.file angular_quickstart
|
||||||
|
.children
|
||||||
|
.file lib
|
||||||
|
.children
|
||||||
|
.file app_component.dart
|
||||||
|
.file pubspec.yaml
|
||||||
|
.file web
|
||||||
|
.children
|
||||||
|
.file index.html
|
||||||
|
.file main.dart
|
||||||
|
.file styles.css
|
||||||
|
|
||||||
|
block install-tooling
|
||||||
|
:marked
|
||||||
|
Install the **[Dart SDK](https://www.dartlang.org/downloads/)**,
|
||||||
|
if not already on your machine, and any tools you like to use with Dart.
|
||||||
|
The Dart SDK includes tools such as **[pub][pub]**, the Dart package manager.
|
||||||
|
If you don't have a favorite Dart editor already, try
|
||||||
|
[WebStorm][WS], which comes with a Dart plugin.
|
||||||
|
You can also download [Dart plugins for other IDEs and editors][DT].
|
||||||
|
|
||||||
|
[WS]: https://confluence.jetbrains.com/display/WI/Getting+started+with+Dart
|
||||||
|
[DT]: https://www.dartlang.org/tools/
|
||||||
|
[pub]: https://www.dartlang.org/tools/pub/
|
||||||
@ -2,206 +2,4 @@ extends ../../ts/_cache/quickstart.jade
|
|||||||
|
|
||||||
block includes
|
block includes
|
||||||
include _util-fns
|
include _util-fns
|
||||||
- var _Install = 'Get'
|
- var _on_Plunkr = '';
|
||||||
- var _prereq = 'the Dart SDK'
|
|
||||||
- var _angular_browser_uri = 'angular2/platform/browser.dart'
|
|
||||||
- var _angular_core_uri = 'angular2/core.dart'
|
|
||||||
- var _stepInit = 3
|
|
||||||
|
|
||||||
block setup-tooling
|
|
||||||
:marked
|
|
||||||
Install the **[Dart SDK](https://www.dartlang.org/downloads/)**,
|
|
||||||
if not already on your machine, and any tools you like to use with Dart.
|
|
||||||
The Dart SDK includes tools such as **[pub][pub]**, the Dart package manager.
|
|
||||||
If you don't have a favorite Dart editor already, try
|
|
||||||
[WebStorm][WS], which comes with a Dart plugin.
|
|
||||||
You can also download [Dart plugins for other IDEs and editors][DT].
|
|
||||||
|
|
||||||
[WS]: https://confluence.jetbrains.com/display/WI/Getting+started+with+Dart
|
|
||||||
[DT]: https://www.dartlang.org/tools/
|
|
||||||
[pub]: https://www.dartlang.org/tools/pub/
|
|
||||||
|
|
||||||
block package-and-config-files
|
|
||||||
:marked
|
|
||||||
In the project folder just created, create a file named
|
|
||||||
**[pubspec.yaml][pubspec]** with the code below.
|
|
||||||
This pubspec must specify the **angular2** and **browser**
|
|
||||||
packages as dependencies, as well as the `angular2` transformer.
|
|
||||||
It can also specify other packages and transformers for the app to use,
|
|
||||||
such as [dart_to_js_script_rewriter](https://pub.dartlang.org/packages/dart_to_js_script_rewriter).
|
|
||||||
|
|
||||||
[pubspec]: https://www.dartlang.org/tools/pub/pubspec.html
|
|
||||||
|
|
||||||
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml')
|
|
||||||
|
|
||||||
block install-packages
|
|
||||||
:marked
|
|
||||||
From the project folder, run `pub get` to install the angular2 and browser
|
|
||||||
packages (along with the packages they depend on).
|
|
||||||
|
|
||||||
code-example(language="sh" class="code-shell").
|
|
||||||
pub get
|
|
||||||
|
|
||||||
block create-your-app
|
|
||||||
:marked
|
|
||||||
Let's create a folder to hold our application and add a super-simple Angular component.
|
|
||||||
|
|
||||||
block create-main
|
|
||||||
p.
|
|
||||||
Now we need something to tell Angular to load the root component.
|
|
||||||
Create:
|
|
||||||
ul
|
|
||||||
li a #[b folder named #[code web]]
|
|
||||||
li a <b>file named #[code #[+adjExPath('app/main.ts')]]</b> with the following content:
|
|
||||||
|
|
||||||
block commentary-on-index-html
|
|
||||||
:marked
|
|
||||||
Note the `<my-app>` tag in the `<body>`, this is *where your app lives!*
|
|
||||||
|
|
||||||
block run-app
|
|
||||||
p.
|
|
||||||
We have a few options for running our app.
|
|
||||||
One is to launch a local HTTP server
|
|
||||||
and then view the app in
|
|
||||||
<a href="https://www.dartlang.org/tools/dartium/">Dartium</a>.
|
|
||||||
We can use any web server, such as WebStorm's server
|
|
||||||
or Python's SimpleHTTPServer.
|
|
||||||
p.
|
|
||||||
Another option is to build and serve the app using <code>pub serve</code>,
|
|
||||||
and then run it by visiting <b><code>http://localhost:8080</code></b> in any modern browser.
|
|
||||||
Pub serve generates JavaScript on the fly,
|
|
||||||
which can take a while when first visiting the page.
|
|
||||||
Pub serve also runs in <b><i>watch mode</i></b>, and will recompile and subsequently serve
|
|
||||||
any changed assets.
|
|
||||||
p.
|
|
||||||
Once the app is running, the browser window should show the following:
|
|
||||||
|
|
||||||
block build-app
|
|
||||||
//- Remove details of building from QS for now. (It is too early for these details.)
|
|
||||||
if false
|
|
||||||
.alert.is-important
|
|
||||||
:marked
|
|
||||||
If you don't see **Hello Angular!**, make sure you've entered all the code correctly,
|
|
||||||
in the [proper folders](#wrap-up),
|
|
||||||
and run `pub get`.
|
|
||||||
|
|
||||||
.l-verbose-section#section-angular-run-app
|
|
||||||
:marked
|
|
||||||
### Building the app (generating JavaScript)
|
|
||||||
|
|
||||||
Before deploying the app, we need to generate JavaScript files.
|
|
||||||
The `pub build` command makes that easy.
|
|
||||||
|
|
||||||
code-example(language="sh" class="code-shell").
|
|
||||||
> <span class="blk">pub build</span>
|
|
||||||
Loading source assets...
|
|
||||||
|
|
||||||
:marked
|
|
||||||
The generated JavaScript appears, along with supporting files,
|
|
||||||
under a directory named `build`.
|
|
||||||
|
|
||||||
#angular_transformer
|
|
||||||
h4 Using the Angular transformer
|
|
||||||
|
|
||||||
p.
|
|
||||||
When generating JavaScript for an Angular app,
|
|
||||||
be sure to use the Angular transformer.
|
|
||||||
It analyzes the Dart code,
|
|
||||||
converting reflection-using code to static code
|
|
||||||
that Dart's build tools can compile to faster, smaller JavaScript.
|
|
||||||
The highlighted lines in <code>pubspec.yaml</code>
|
|
||||||
configure the Angular transformer:
|
|
||||||
|
|
||||||
- var stylePattern = { otl: /(transformers:)|(- angular2:)|(entry_points.*$)/gm };
|
|
||||||
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
|
|
||||||
|
|
||||||
p.
|
|
||||||
The <code>entry_points</code> item
|
|
||||||
identifies the Dart file in our app
|
|
||||||
that has a <code>main()</code> function.
|
|
||||||
For more information, see the
|
|
||||||
<a href="https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer">Angular
|
|
||||||
transformer wiki page</a>.
|
|
||||||
|
|
||||||
.l-sub-section#performance
|
|
||||||
h3 Performance, the transformer, and Angular libraries
|
|
||||||
p.
|
|
||||||
When an app imports <code>bootstrap.dart</code>,
|
|
||||||
it also gets <code>dart:mirrors</code>,
|
|
||||||
a reflection library that
|
|
||||||
causes performance problems when compiled to JavaScript.
|
|
||||||
Don't worry,
|
|
||||||
the Angular transformer converts the app's entry points
|
|
||||||
(<code>entry_points</code> in <code>pubspec.yaml</code>)
|
|
||||||
so that they don't use mirrors.
|
|
||||||
|
|
||||||
#dart_to_js_script_rewriter
|
|
||||||
h4 Using dart_to_js_script_rewriter
|
|
||||||
|
|
||||||
:marked
|
|
||||||
To improve the app's performance, convert the
|
|
||||||
HTML file to directly include the generated JavaScript;
|
|
||||||
one way to do that is with `dart_to_js_script_rewriter`.
|
|
||||||
To use the rewriter, specify `dart_to_js_script_rewriter` in both
|
|
||||||
the `dependencies` and `transformers` sections of the pubspec.
|
|
||||||
|
|
||||||
- var stylePattern = { otl: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)|(dependencies:)|(transformers:)/gm };
|
|
||||||
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
|
|
||||||
|
|
||||||
.alert.is-important
|
|
||||||
:marked
|
|
||||||
The `dart_to_js_script_rewriter` transformer must be
|
|
||||||
**after** the `angular2` transformer in `pubspec.yaml`.
|
|
||||||
|
|
||||||
:marked
|
|
||||||
For more information, see the docs for
|
|
||||||
[dart_to_js_script_rewriter](https://pub.dartlang.org/packages/dart_to_js_script_rewriter).
|
|
||||||
|
|
||||||
block server-watching
|
|
||||||
:marked
|
|
||||||
To see the new version, just reload the page.
|
|
||||||
|
|
||||||
.alert.is-important
|
|
||||||
:marked
|
|
||||||
Be sure to terminate your local server once you stop working on this app.
|
|
||||||
|
|
||||||
block project-file-structure
|
|
||||||
.filetree
|
|
||||||
.file angular_quickstart
|
|
||||||
.children
|
|
||||||
.file lib
|
|
||||||
.children
|
|
||||||
.file app_component.dart
|
|
||||||
.file pubspec.yaml
|
|
||||||
.file web
|
|
||||||
.children
|
|
||||||
.file index.html
|
|
||||||
.file main.dart
|
|
||||||
.file styles.css
|
|
||||||
|
|
||||||
.l-verbose-section
|
|
||||||
:marked
|
|
||||||
This figure doesn't show generated files and directories.
|
|
||||||
For example, a `pubspec.lock` file
|
|
||||||
specifies versions and other identifying information for
|
|
||||||
the packages that our app depends on.
|
|
||||||
The `pub build` command creates a `build` directory
|
|
||||||
containing the JavaScript version of our app.
|
|
||||||
Pub, IDEs, and other tools often create
|
|
||||||
other directories and dotfiles.
|
|
||||||
|
|
||||||
block project-files
|
|
||||||
:marked
|
|
||||||
Try the <live-example></live-example>, or view the files here:
|
|
||||||
+makeTabs(`
|
|
||||||
quickstart/ts/app/app.component.ts,
|
|
||||||
quickstart/ts/app/main.ts,
|
|
||||||
quickstart/ts/index.html,
|
|
||||||
quickstart/dart/pubspec.yaml,
|
|
||||||
quickstart/ts/styles.css`,
|
|
||||||
',,,,quickstart',
|
|
||||||
`app/app.component.ts,
|
|
||||||
app/main.ts,
|
|
||||||
index.html,
|
|
||||||
pubspec.yaml,
|
|
||||||
styles.css (excerpt)`)
|
|
||||||
|
|||||||
@ -1,19 +1,6 @@
|
|||||||
block includes
|
block includes
|
||||||
include ../_util-fns
|
include ../_util-fns
|
||||||
|
- var _angular_io = 'angular.io';
|
||||||
figure
|
|
||||||
img(src="/resources/images/devguide/intro/people.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:10px")
|
|
||||||
|
|
||||||
:marked
|
|
||||||
This is a practical guide to Angular for experienced programmers who
|
|
||||||
are building client applications in HTML and #{_Lang}. <br class="l-clear-left">
|
|
||||||
|
|
||||||
## Organization
|
|
||||||
|
|
||||||
The documentation is divided into major thematic sections, each
|
|
||||||
a collection of pages devoted to that theme.
|
|
||||||
|
|
||||||
block js-alert
|
|
||||||
|
|
||||||
- var __lang = _docsFor || current.path[1] || 'ts';
|
- var __lang = _docsFor || current.path[1] || 'ts';
|
||||||
- var guideData = public.docs[__lang].latest.guide._data;
|
- var guideData = public.docs[__lang].latest.guide._data;
|
||||||
@ -22,6 +9,19 @@ block js-alert
|
|||||||
- if (!guideData[page].basics && !guideData[page].hide) { advancedLandingPage = page; break; }
|
- if (!guideData[page].basics && !guideData[page].hide) { advancedLandingPage = page; break; }
|
||||||
- }
|
- }
|
||||||
- var advancedUrl = './' + advancedLandingPage + '.html'
|
- var advancedUrl = './' + advancedLandingPage + '.html'
|
||||||
|
|
||||||
|
|
||||||
|
:marked
|
||||||
|
This page describes the Angular documentation at a high level.
|
||||||
|
If you're new to Angular, you may want to visit "[Learning Angular](learning-angular.html)" first.
|
||||||
|
|
||||||
|
## Themes
|
||||||
|
|
||||||
|
The documentation is divided into major thematic sections, each
|
||||||
|
a collection of pages devoted to that theme.
|
||||||
|
|
||||||
|
block js-alert
|
||||||
|
|
||||||
- var top="vertical-align:top"
|
- var top="vertical-align:top"
|
||||||
table(width="100%")
|
table(width="100%")
|
||||||
col(width="15%")
|
col(width="15%")
|
||||||
@ -30,19 +30,22 @@ table(width="100%")
|
|||||||
td <b><a href="../quickstart.html">QuickStart</a></b>
|
td <b><a href="../quickstart.html">QuickStart</a></b>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
The foundation for every page and sample in this documentation.
|
A first taste of Angular<span if-docs="ts"> with zero installation.
|
||||||
|
Run "Hello World" in an online code editor and start playing with live code</span>.
|
||||||
tr(style=top)
|
tr(style=top)
|
||||||
td <b><a href="./">Guide</a></b>
|
td <b>Guide</b>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
The essential ingredients of Angular development.
|
Learn the Angular basics (you're already here!) like the setup for local development,
|
||||||
|
displaying data and accepting user input, injecting application services into components,
|
||||||
|
and building simple forms.
|
||||||
tr(style=top)
|
tr(style=top)
|
||||||
td <b><a href="../api">API Reference</a></b>
|
td <b><a href="../api/">API Reference</a></b>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
Authoritative details about each member of the Angular libraries.
|
Authoritative details about each of the Angular libraries.
|
||||||
tr(style=top)
|
tr(style=top)
|
||||||
td <b><a href="../tutorial">Tutorial</a></b>
|
td <b><a href="../tutorial/">Tutorial</a></b>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
A step-by-step, immersive approach to learning Angular that
|
A step-by-step, immersive approach to learning Angular that
|
||||||
@ -53,62 +56,37 @@ table(width="100%")
|
|||||||
:marked
|
:marked
|
||||||
In-depth analysis of Angular features and development practices.
|
In-depth analysis of Angular features and development practices.
|
||||||
tr(style=top)
|
tr(style=top)
|
||||||
td <b><a href="../cookbook">Cookbook</a></b>
|
td <b><a href="../cookbook/">Cookbook</a></b>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
Recipes for specific application challenges, mostly code snippets with a minimum of exposition.
|
Recipes for specific application challenges, mostly code snippets with a minimum of exposition.
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
## Learning path
|
A few early pages are written as tutorials and are clearly marked as such.
|
||||||
|
The rest of the pages highlight key points in code rather than explain each step necessary to build the sample.
|
||||||
You don't have to read the guide straight through. Most pages stand on their own.
|
You can always get the full source through the #{_liveLink}s.
|
||||||
|
|
||||||
For those new to Angular, the recommended learning path runs through the *Guide* section:
|
|
||||||
|
|
||||||
1. For the big picture, read the [Architecture](architecture.html) overview.
|
|
||||||
|
|
||||||
1. Try [QuickStart](../quickstart.html). QuickStart is the "Hello, World" of Angular.
|
|
||||||
It shows you how to set up the libraries and tools you'll need to write *any* Angular app.
|
|
||||||
|
|
||||||
1. Take the *Tour of Heroes* [tutorial](../tutorial), which picks up where QuickStart leaves off,
|
|
||||||
and builds a simple data-driven app. The app demonstrates the essential characteristics of a professional application:
|
|
||||||
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
|
|
||||||
|
|
||||||
1. [Displaying Data](displaying-data.html) explains how to display information on the screen.
|
|
||||||
|
|
||||||
1. [User Input](user-input.html) covers how Angular responds to user behavior.
|
|
||||||
|
|
||||||
1. [Forms](forms.html) handles user data entry and validation within the UI.
|
|
||||||
|
|
||||||
1. [Dependency Injection](dependency-injection.html) is the way to build large, maintainable applications
|
|
||||||
from small, single-purpose parts.
|
|
||||||
|
|
||||||
1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
|
|
||||||
|
|
||||||
After reading the above sections, you can skip to any other pages on this site.
|
|
||||||
|
|
||||||
## Code samples
|
## Code samples
|
||||||
|
|
||||||
Each page includes code snippets that you can reuse in your applications.
|
Each page includes code snippets from a sample application that accompanies the page.
|
||||||
These snippets are excerpts from a sample application that accompanies the page.
|
You can reuse these snippets in your applications.
|
||||||
|
|
||||||
Look for a link to a running version of that sample near the top of each page,
|
Look for a link to a running version of that sample, often near the top of the page,
|
||||||
such as this <live-example name="architecture"></live-example> from the [Architecture](architecture.html) page.
|
such as this <live-example name="architecture"></live-example> from the [Architecture](architecture.html) page.
|
||||||
<p if-docs="ts">
|
<span if-docs="ts">
|
||||||
The link launches a browser-based code editor where you can inspect, modify, save, and download the code.
|
The link launches a browser-based, code editor where you can inspect, modify, save, and download the code.
|
||||||
</p>
|
</span>
|
||||||
|
|
||||||
A few early pages are written as tutorials and are clearly marked as such.
|
|
||||||
The rest of the pages highlight key points in code rather than explain each step necessary to build the sample.
|
|
||||||
You can always get the full source through the #{_liveLink}.
|
|
||||||
|
|
||||||
## Reference pages
|
## Reference pages
|
||||||
|
|
||||||
- The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
|
* The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
|
||||||
- The [Glossary](glossary.html) defines terms that Angular developers should know.
|
* The [Glossary](glossary.html) defines terms that Angular developers should know.
|
||||||
- The [API Reference](../api/) is the authority on every public-facing member of the Angular libraries.
|
<li if-docs="ts">The [Change Log](change-log.html) announces what's new and changed in the documentation.</li>
|
||||||
|
* The [API Reference](../api/) is the authority on every public-facing member of the Angular libraries.
|
||||||
|
|
||||||
## We welcome feedback!
|
## Feedback
|
||||||
|
|
||||||
- Use the [website GitHub repo](!{_ngDocRepoURL}) for **documentation** issues and pull requests.
|
We welcome feedback!
|
||||||
- Use the [Angular GitHub repo](!{_ngRepoURL}) to report issues with **Angular** itself.
|
|
||||||
|
* Use the <a href="!{_ngDocRepoURL}" target="_blank" title="angular docs on github">!{_angular_io} Github repository</a> for **documentation** issues and pull requests.
|
||||||
|
* Use the <a href="!{_ngRepoURL}" target="_blank" title="angular source on github">Angular Github repository</a> to report issues with **Angular** itself.
|
||||||
|
|||||||
44
public/docs/ts/_cache/guide/learning-angular.jade
Normal file
44
public/docs/ts/_cache/guide/learning-angular.jade
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
block includes
|
||||||
|
include ../_util-fns
|
||||||
|
|
||||||
|
figure
|
||||||
|
img(src="/resources/images/devguide/intro/people.png" width="200px" height="152px" alt="Us" align="left" style="margin-left:-40px;margin-right:10px" )
|
||||||
|
:marked
|
||||||
|
Everyone learns differently.
|
||||||
|
You don't have to read the documentation straight through. Most pages stand on their own.
|
||||||
|
Those new to Angular may wish to follow this popular learning path.
|
||||||
|
<br class="l-clear-left">
|
||||||
|
|
||||||
|
:marked
|
||||||
|
1. [Setup](setup.html "Setup locally withe Quickstart seed") for local Angular development, if you haven't already done so.
|
||||||
|
|
||||||
|
1. Take the [*Tour of Heroes* tutorial](../tutorial "Tour of Heroes").
|
||||||
|
|
||||||
|
The *Tour of Heroes* takes you step-by-step from [setup](setup.html)
|
||||||
|
to a full-featured example that demonstrates the essential characteristics of a professional application:
|
||||||
|
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
|
||||||
|
|
||||||
|
1. <a id="architecture"></a>Read the [Architecture](architecture.html) overview for the big picture.
|
||||||
|
<li if-docs="ts"><p>
|
||||||
|
[The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application.
|
||||||
|
</p></li>
|
||||||
|
|
||||||
|
1. [Displaying Data](displaying-data.html) shows how data binding puts component property values on screen.
|
||||||
|
|
||||||
|
1. [User Input](user-input.html) explains how to respond to user-initiated DOM events.
|
||||||
|
|
||||||
|
1. [Forms](forms.html) covers data entry and validation within the UI.
|
||||||
|
|
||||||
|
1. [Dependency Injection](dependency-injection.html) is the way to build large, maintainable applications
|
||||||
|
from small, single-purpose parts.
|
||||||
|
|
||||||
|
1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
|
||||||
|
|
||||||
|
After reading the above sections, feel free to skip around among the other pages on this site.
|
||||||
|
|
||||||
|
.l-sub-section
|
||||||
|
:marked
|
||||||
|
### Next Step
|
||||||
|
|
||||||
|
Try the [tutorial](../tutorial "Tour of Heroes") if you're ready to start coding or
|
||||||
|
visit the [Architecture](architecture.html "Basic Concepts") guide if you prefer to learn the basic concepts first.
|
||||||
180
public/docs/ts/_cache/guide/setup.jade
Normal file
180
public/docs/ts/_cache/guide/setup.jade
Normal file
@ -0,0 +1,180 @@
|
|||||||
|
block includes
|
||||||
|
include ../_util-fns
|
||||||
|
- var _prereq = 'node and npm';
|
||||||
|
- var _playground = 'playground';
|
||||||
|
- var _Install = 'Install';
|
||||||
|
//- npm commands
|
||||||
|
- var _install = 'install';
|
||||||
|
- var _start = 'start';
|
||||||
|
|
||||||
|
a#develop-locally
|
||||||
|
:marked
|
||||||
|
## Setup a local development environment
|
||||||
|
|
||||||
|
<span if-docs="ts">
|
||||||
|
The <live-example name=quickstart>QuickStart live-coding</live-example> example is an Angular _playground_.
|
||||||
|
It's not where you'd develop a real application.
|
||||||
|
You [should develop locally](#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular.
|
||||||
|
</span>
|
||||||
|
|
||||||
|
Setting up a new project on your machine is quick and easy with the **QuickStart seed**,
|
||||||
|
maintained [on github](!{_qsRepo} "Install the github QuickStart repo").
|
||||||
|
|
||||||
|
Make sure you have [!{_prereq} installed](#install-prerequisites "What if you don't have !{_prereq}?").
|
||||||
|
Then ...
|
||||||
|
1. Create a project folder (you can call it `quickstart` and rename it later).
|
||||||
|
1. [Clone](#clone "Clone it from github") or [download](#download "download it from github") the **QuickStart seed** into your project folder.
|
||||||
|
1. !{_Install} [!{_npm}](#install-prerequisites "What if you don't have !{_prereq}?") packages.
|
||||||
|
1. Run `!{_npm} !{_start}` to launch the sample application.
|
||||||
|
|
||||||
|
a#clone
|
||||||
|
:marked
|
||||||
|
### Clone
|
||||||
|
|
||||||
|
Perform the _clone-to-launch_ steps with these terminal commands.
|
||||||
|
|
||||||
|
code-example(language="sh" class="code-shell").
|
||||||
|
git clone !{_qsRepo}.git quickstart
|
||||||
|
cd quickstart
|
||||||
|
!{_npm} !{_install}
|
||||||
|
!{_npm} !{_start}
|
||||||
|
|
||||||
|
a#download
|
||||||
|
:marked
|
||||||
|
### Download
|
||||||
|
<a href="!{_qsRepoZip}" title="Download the QuickStart seed repository">Download the QuickStart seed</a>
|
||||||
|
and unzip it into your project folder. Then perform the remaining steps with these terminal commands.
|
||||||
|
|
||||||
|
code-example(language="sh" class="code-shell").
|
||||||
|
cd quickstart
|
||||||
|
!{_npm} !{_install}
|
||||||
|
!{_npm} !{_start}
|
||||||
|
|
||||||
|
.l-main-section#seed
|
||||||
|
:marked
|
||||||
|
## What's in the QuickStart seed?
|
||||||
|
|
||||||
|
block qs-seed
|
||||||
|
:marked
|
||||||
|
The **QuickStart seed** contains the same application as the QuickStart playground
|
||||||
|
and even has <live-example>its own _playground_</live-example>
|
||||||
|
that accomodates development of richer examples in a live coding environment.
|
||||||
|
|
||||||
|
But it's true purpose is to provide a solid foundation for _local_ development.
|
||||||
|
Consequently, there are _many more files_ in the project folder on your machine,
|
||||||
|
most of which you can [learn about later](setup-systemjs-anatomy.html "Setup Anatomy").
|
||||||
|
|
||||||
|
block core-files
|
||||||
|
:marked
|
||||||
|
Focus on the following three TypeScript (`.ts`) files in the **`/app`** folder.
|
||||||
|
|
||||||
|
.filetree
|
||||||
|
.file app
|
||||||
|
.children
|
||||||
|
.file app.component.ts
|
||||||
|
.file app.module.ts
|
||||||
|
.file main.ts
|
||||||
|
|
||||||
|
+makeTabs(`
|
||||||
|
setup/ts/app/app.component.ts,
|
||||||
|
setup/ts/app/app.module.ts,
|
||||||
|
setup/ts/app/main.ts
|
||||||
|
`, '', `
|
||||||
|
app/app.component.ts,
|
||||||
|
app/app.module.ts,
|
||||||
|
app/main.ts
|
||||||
|
`)(format='.')
|
||||||
|
|
||||||
|
:marked
|
||||||
|
All guides and cookbooks have _at least these core files_. Each file has a distinct purpose and evolves independently as the application grows.
|
||||||
|
|
||||||
|
style td, th {vertical-align: top}
|
||||||
|
table(width="100%")
|
||||||
|
col(width="20%")
|
||||||
|
col(width="80%")
|
||||||
|
tr
|
||||||
|
th File
|
||||||
|
th Purpose
|
||||||
|
tr
|
||||||
|
td <ngio-ex>app.component.ts</ngio-ex>
|
||||||
|
td
|
||||||
|
:marked
|
||||||
|
Defines the same `AppComponent` as the one in the QuickStart !{_playground}.
|
||||||
|
It is the **root** component of what will become a tree of nested components
|
||||||
|
as the application evolves.
|
||||||
|
tr(if-docs="ts")
|
||||||
|
td <code>app.module.ts</code>
|
||||||
|
td
|
||||||
|
:marked
|
||||||
|
Defines `AppModule`, the [root module](appmodule.html "AppModule: the root module") that tells Angular how to assemble the application.
|
||||||
|
Right now it declares only the `AppComponent`.
|
||||||
|
Soon there will be more components to declare.
|
||||||
|
tr
|
||||||
|
td <ngio-ex>main.ts</ngio-ex>
|
||||||
|
td
|
||||||
|
:marked
|
||||||
|
Compiles the application with the [JiT compiler](../glossary.html#jit)
|
||||||
|
and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser.
|
||||||
|
That's a reasonable choice for the development of most projects and
|
||||||
|
it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
|
||||||
|
You'll learn about alternative compiling and deployment options later in the documentation.
|
||||||
|
|
||||||
|
.l-sub-section
|
||||||
|
:marked
|
||||||
|
### Next Step
|
||||||
|
|
||||||
|
If you're new to Angular, we recommend staying on the [learning path](learning-angular.html).
|
||||||
|
|
||||||
|
br
|
||||||
|
br
|
||||||
|
|
||||||
|
a#install-prerequisites
|
||||||
|
.l-main-section
|
||||||
|
:marked
|
||||||
|
## Appendix: !{_prereq}
|
||||||
|
block install-tooling
|
||||||
|
:marked
|
||||||
|
Node.js and npm are essential to modern web development with Angular and other platforms.
|
||||||
|
Node powers client development and build tools.
|
||||||
|
The _npm_ package manager, itself a _node_ application, installs JavaScript libraries.
|
||||||
|
|
||||||
|
<a href="https://docs.npmjs.com/getting-started/installing-node" target="_blank" title="Installing Node.js and updating npm">
|
||||||
|
Get them now</a> if they're not already installed on your machine.
|
||||||
|
|
||||||
|
**Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher**
|
||||||
|
by running the commands `node -v` and `npm -v` in a terminal/console window.
|
||||||
|
Older versions produce errors.
|
||||||
|
|
||||||
|
We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm.
|
||||||
|
You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that
|
||||||
|
use other versions of node and npm.
|
||||||
|
|
||||||
|
+ifDocsFor('ts')
|
||||||
|
a#why-locally
|
||||||
|
.l-main-section
|
||||||
|
:marked
|
||||||
|
## Appendix: Why develop locally
|
||||||
|
|
||||||
|
<live-example>Live coding</live-example> in the browser is a great way to explore Angular.
|
||||||
|
|
||||||
|
Links on almost every documentation page open completed samples in the browser.
|
||||||
|
You can play with the sample code, share your changes with friends, and download and run the code on your own machine.
|
||||||
|
|
||||||
|
The [QuickStart](../quickstart.html "Angular QuickStart Playground") shows just the `AppComponent` file.
|
||||||
|
It creates the equivalent of `app.module.ts` and `main.ts` internally _for the playground only_.
|
||||||
|
so the reader can discover Angular without distraction.
|
||||||
|
The other samples are based on the QuickStart seed.
|
||||||
|
|
||||||
|
As much fun as this is ...
|
||||||
|
* you can't ship your app in plunker
|
||||||
|
* you aren't always online when writing code
|
||||||
|
* transpiling TypeScript in the browser is slow
|
||||||
|
* the type support, refactoring, and code completion only work in your local IDE
|
||||||
|
|
||||||
|
Use the <live-example><i>live coding</i></live-example> environment as a _playground_,
|
||||||
|
a place to try the documentation samples and experiment on your own.
|
||||||
|
It's the perfect place to reproduce a bug when you want to
|
||||||
|
<a href="https://github.com/angular/angular.io/issues/new" target="_blank" title="File a documentation issue">file a documentation issue</a> or
|
||||||
|
<a href="https://github.com/angular/angular/issues/new" target="_blank" title="File an Angular issue">file an issue with Angular itself</a>.
|
||||||
|
|
||||||
|
For real development, we strongly recommend [developing locally](#develop-locally).
|
||||||
@ -1,384 +1,45 @@
|
|||||||
block includes
|
block includes
|
||||||
include _util-fns
|
include _util-fns
|
||||||
- var _Install = 'Install'
|
- var _on_Plunkr = 'on Plunkr';
|
||||||
- var _prereq = 'Node.js and npm'
|
|
||||||
- var _angular_browser_uri = '@angular/platform-browser-dynamic'
|
|
||||||
- var _angular_core_uri = '@angular/core'
|
|
||||||
- var _stepInit = 4 // Step # after NgModule step
|
|
||||||
- var _quickstartSrcURL='https://github.com/angular/quickstart/blob/master/README.md'
|
|
||||||
|
|
||||||
//- TS/Dart shared step counter
|
:marked
|
||||||
- var step = _stepInit
|
Angular applications are made of _components_.
|
||||||
|
A _component_ is the combination of an HTML template and a component class that controls a portion of the screen. Here is an example of a component that displays a simple string:
|
||||||
|
|
||||||
|
+makeExample('app/app.component.ts')(format='.')
|
||||||
|
|
||||||
|
:marked
|
||||||
|
You can try this out without installing anything. Open the <live-example>QuickStart example !{_on_Plunkr}</live-example> in another tab
|
||||||
|
and follow along.
|
||||||
|
|
||||||
|
Every component begins with an `@Component` [!{_decorator}](glossary.html#!{_decorator} '"!{_decorator}" explained')
|
||||||
|
<span if-docs="ts">function</span> that
|
||||||
|
<span if-docs="ts">takes a _metadata_ object. The metadata object</span> describes how the HTML template and component class work together.
|
||||||
|
|
||||||
|
The `selector` property tells Angular to display the component inside a custom `<my-app>` tag in the `index.html`.
|
||||||
|
+makeExample('index.html','my-app','index.html (inside <body>)')(format='.')
|
||||||
|
:marked
|
||||||
|
The `template` property defines a message inside an `<h1>` header.
|
||||||
|
The message starts with "Hello" and ends with `{{name}}`
|
||||||
|
which is an Angular [interpolation binding](guide/displaying-data.html) expression.
|
||||||
|
At runtime, Angular replaces `{{name}}` with the value of the component's `name` property.
|
||||||
|
|
||||||
|
In the example, change the component class's `name` property from `'Angular'` to `'World'` and see what happens.
|
||||||
|
|
||||||
|
Interpolation binding is one of many Angular features you'll discover in this documentation.
|
||||||
|
|
||||||
+ifDocsFor('ts')
|
+ifDocsFor('ts')
|
||||||
aside.is-right
|
|
||||||
:marked
|
|
||||||
The live example link opens the finished application in
|
|
||||||
<a href="http://plnkr.co/" title="Plunker" target="_blank">Plunker</a> so that you can interact
|
|
||||||
with the code. You'll find live examples at the start of most sections.
|
|
||||||
|
|
||||||
:marked
|
|
||||||
The QuickStart application has the structure of a real-world Angular application and
|
|
||||||
displays the simple message:
|
|
||||||
|
|
||||||
figure.image-display
|
|
||||||
img(src='/resources/images/devguide/quickstart/hello-angular.png' alt="Output of QuickStart app")
|
|
||||||
|
|
||||||
:marked
|
|
||||||
**Try it out**. Here's a link to a <live-example></live-example>.
|
|
||||||
|
|
||||||
+ifDocsFor('ts')
|
|
||||||
:marked
|
|
||||||
You can also <a href="!{_quickstartSrcURL}" target="_blank">
|
|
||||||
clone the entire QuickStart application</a> from GitHub.
|
|
||||||
|
|
||||||
h1 Build this application!
|
|
||||||
|
|
||||||
:marked
|
|
||||||
- [Prerequisite](#prereq): Install #{_prereq}.
|
|
||||||
- [Step 1](#create-and-configure): Create and configure the project.
|
|
||||||
- [Step 2](#ngmodule): Create your application.
|
|
||||||
<li if-docs="ts">[Step 3](#root-component): Create a component and add it to your application.</li>
|
|
||||||
- [Step !{step++}](#main): Start up your application.
|
|
||||||
- [Step !{step++}](#index): Define the web page that hosts the application.
|
|
||||||
- [Step !{step++}](#build-and-run): Build and run the application.
|
|
||||||
- [Step !{step++}](#make-changes): Make some live changes.
|
|
||||||
- [Wrap up and next steps](#wrap-up)
|
|
||||||
|
|
||||||
- var step = _stepInit // reinitialize step counter for headers to come
|
|
||||||
|
|
||||||
.l-main-section#prereq
|
|
||||||
h2 Prerequisite: Install #{_prereq}
|
|
||||||
|
|
||||||
block setup-tooling
|
|
||||||
:marked
|
|
||||||
If Node.js and npm aren't already on your machine, <a href="http://blog.npmjs.org/post/85484771375/how-to-install-npm"
|
|
||||||
target="_blank">install them</a>. Our examples require node **v4.x.x** or higher and
|
|
||||||
npm **3.x.x** or higher. To check which version you are using, run `node -v` and `npm -v`
|
|
||||||
in a terminal window.
|
|
||||||
|
|
||||||
.l-main-section
|
|
||||||
h2#create-and-configure Step 1: Create and configure the project
|
|
||||||
|
|
||||||
- var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'configuration files'
|
|
||||||
|
|
||||||
:marked
|
|
||||||
In this step you will:
|
|
||||||
* [Create the project folder](#create-the-project-folder)
|
|
||||||
* [Create #{_package_and_config_files}](#add-config-files)
|
|
||||||
* [#{_Install} packages](#install-packages)
|
|
||||||
|
|
||||||
h3 Create the project folder
|
|
||||||
:marked
|
|
||||||
Using a terminal window, create a directory for the project, and change into this
|
|
||||||
directory.
|
|
||||||
|
|
||||||
- var _ = _docsFor == 'dart' ? '_' : '-';
|
|
||||||
code-example(language="sh" class="code-shell").
|
|
||||||
mkdir angular!{_}quickstart
|
|
||||||
cd angular!{_}quickstart
|
|
||||||
|
|
||||||
h3#add-config-files Create #{_package_and_config_files}
|
|
||||||
block package-and-config-files
|
|
||||||
- var _tsconfigUri = 'guide/typescript-configuration.html#tsconfig'
|
|
||||||
|
|
||||||
p Our typical Angular project needs several configuration files:
|
|
||||||
ul
|
|
||||||
li.
|
|
||||||
#[b package.json] identifies npm package dependencies for the project.
|
|
||||||
li.
|
|
||||||
#[b tsconfig.json] defines how the TypeScript compiler generates JavaScript from the project's
|
|
||||||
files.
|
|
||||||
li.
|
|
||||||
#[b systemjs.config.js] provides information to a module loader about where to find
|
|
||||||
application modules, and registers all the necessary packages. It also
|
|
||||||
contains other packages that will be needed by later documentation examples.
|
|
||||||
|
|
||||||
p.
|
|
||||||
Create each of these files in your project directory. Populate them by pasting in text from
|
|
||||||
the tabs in the example box below.
|
|
||||||
|
|
||||||
a#config-files
|
|
||||||
+makeTabs(`
|
|
||||||
quickstart/ts/package.1.json,
|
|
||||||
quickstart/ts/tsconfig.1.json,
|
|
||||||
quickstart/ts/systemjs.config.1.js
|
|
||||||
`, '', `
|
|
||||||
package.json,
|
|
||||||
tsconfig.json,
|
|
||||||
systemjs.config.js
|
|
||||||
`)
|
|
||||||
|
|
||||||
p.
|
|
||||||
Learn more about these configuration files in the
|
|
||||||
#[a(href="guide/npm-packages.html") Npm Package Configuration] guide and the
|
|
||||||
#[a(href="#{_tsconfigUri}") TypeScript Configuration] guide.
|
|
||||||
A detailed discussion of module loading is beyond the scope of this guide.
|
|
||||||
|
|
||||||
.callout.is-helpful
|
.callout.is-helpful
|
||||||
header SystemJS or Webpack?
|
header A word about TypeScript
|
||||||
p.
|
p.
|
||||||
Although we use SystemJS for illustrative purposes here, it's only one option for loading
|
This example is written in <a href="http://www.typescriptlang.org/" target="_blank" title="TypeScript">TypeScript</a>, a superset of JavaScript. Angular
|
||||||
modules. Use the module loader that you prefer. For Webpack and Angular, see <a
|
uses TypeScript because its types make it easy to support developer productivity with tooling. You can also write Angular code in JavaScript; <a href="cookbook/ts-to-js.html">this guide</a> explains how.
|
||||||
href="guide/webpack.html" >
|
|
||||||
Webpack: an Introduction</a>. Or, learn more about SystemJS configuration in general <a href="https://github.com/systemjs/systemjs/blob/master/docs/config-api.md" target="_blank">here</a>.
|
|
||||||
|
|
||||||
|
.l-sub-section
|
||||||
h3#install-packages #{_Install} packages
|
|
||||||
block install-packages
|
|
||||||
:marked
|
|
||||||
Using npm from the command line, install the packages listed in `package.json` with the command:
|
|
||||||
|
|
||||||
code-example(language="sh" class="code-shell").
|
|
||||||
npm install
|
|
||||||
|
|
||||||
:marked
|
|
||||||
Error messages—in red—might appear during the install, and you might see `npm WARN` messages. As long as there are no `npm ERR!` messages at the end, you can assume success.
|
|
||||||
|
|
||||||
:marked
|
|
||||||
You should now have the following structure:
|
|
||||||
|
|
||||||
.filetree
|
|
||||||
.file angular-quickstart
|
|
||||||
.children
|
|
||||||
.file node_modules ...
|
|
||||||
.file package.json
|
|
||||||
.file systemjs.config.js
|
|
||||||
.file tsconfig.json
|
|
||||||
|
|
||||||
:marked
|
|
||||||
You're now ready to write some code!
|
|
||||||
|
|
||||||
.l-main-section
|
|
||||||
h2#ngmodule Step 2: Create your application
|
|
||||||
|
|
||||||
block create-your-app
|
|
||||||
:marked
|
|
||||||
You compose Angular applications into closely related blocks of functionality with
|
|
||||||
[NgModules](guide/ngmodule.html). Angular itself is split into separate Angular Modules. This
|
|
||||||
makes it possible for you to keep payload size small by only importing the parts of Angular
|
|
||||||
that your application needs.
|
|
||||||
|
|
||||||
Every Angular application has at least one module: the _root module_, named `AppModule` here.
|
|
||||||
:marked
|
|
||||||
**Create #{_an} #{_appDir} subfolder** off the project root directory:
|
|
||||||
|
|
||||||
code-example.code-shell.
|
|
||||||
mkdir #{_appDir}
|
|
||||||
|
|
||||||
+ifDocsFor('ts')
|
|
||||||
:marked
|
|
||||||
Create the file `app/app.module.ts` with the following content:
|
|
||||||
|
|
||||||
+makeExample('app/app.module.1.ts')(format='.')
|
|
||||||
|
|
||||||
:marked
|
|
||||||
This is the entry point to your application.
|
|
||||||
|
|
||||||
Since the QuickStart application is a web application that runs in a browser, your root module
|
|
||||||
needs to import the
|
|
||||||
[`BrowserModule`](../latest/api/platform-browser/index/BrowserModule-class.html)
|
|
||||||
from `@angular/platform-browser` to the `imports` array.
|
|
||||||
|
|
||||||
This is the smallest amount of Angular that is needed for a minimal application to run in the
|
|
||||||
browser.
|
|
||||||
|
|
||||||
The QuickStart application doesn't do anything else, so you don't need any other modules. In a real
|
|
||||||
application, you'd likely import [`FormsModule`](../latest/api/forms/index/FormsModule-class.html)
|
|
||||||
as well as [`RouterModule`](../latest/api/router/index/RouterModule-class.html) and
|
|
||||||
[`HttpModule`](../latest/api/http/index/HttpModule-class.html). These are introduced in the
|
|
||||||
[Tour of Heroes Tutorial](./tutorial/).
|
|
||||||
|
|
||||||
.l-main-section
|
|
||||||
h2#root-component Step 3: Create a component and add it to your application
|
|
||||||
|
|
||||||
:marked
|
|
||||||
Every Angular application has at least one component: the _root component_, named `AppComponent`
|
|
||||||
here.
|
|
||||||
|
|
||||||
Components are the basic building blocks of Angular applications. A component controls a portion
|
|
||||||
of the screen—a *view*—through its associated template.
|
|
||||||
|
|
||||||
#app-component
|
|
||||||
:marked
|
|
||||||
**Create the component file** <span ngio-ex>app/app.component.ts</span> with the following content:
|
|
||||||
|
|
||||||
+makeExample('app/app.component.ts')
|
|
||||||
|
|
||||||
- var _decorator_function = _docsFor == 'dart' ? 'annotation' : 'decorator function';
|
|
||||||
:marked
|
|
||||||
The QuickStart application has the same essential structure as any other Angular component:
|
|
||||||
|
|
||||||
* **An import statement**. Importing gives your component access to
|
|
||||||
Angular's core [`@Component` !{_decorator_function}](./api/core/index/Component-decorator.html).
|
|
||||||
* **A @Component #{_decorator}** that associates *metadata* with the
|
|
||||||
`AppComponent` component class:
|
|
||||||
|
|
||||||
- a *selector* that specifies a simple CSS selector for an HTML element that represents
|
|
||||||
the component.
|
|
||||||
- a *template* that tells Angular how to render the component's view.
|
|
||||||
* **A component class** that controls the appearance and behavior of a view
|
|
||||||
through its template. Here, you only have the root component, `AppComponent`. Since you don't
|
|
||||||
need any application logic in the simple QuickStart example, it's empty.
|
|
||||||
+ifDocsFor('ts')
|
|
||||||
:marked
|
|
||||||
You *export* the `AppComponent` class so that you can *import* it into the application that you
|
|
||||||
just created.
|
|
||||||
|
|
||||||
Edit the file `app/app.module.ts` to import your new `AppComponent` and add it in the
|
|
||||||
declarations and bootstrap fields in the `NgModule` decorator:
|
|
||||||
|
|
||||||
+makeExample('app/app.module.ts')
|
|
||||||
|
|
||||||
.l-main-section
|
|
||||||
h2#main Step !{step++}: Start up your application
|
|
||||||
|
|
||||||
block create-main
|
|
||||||
:marked
|
|
||||||
Now you need to tell Angular to start up your application.
|
|
||||||
|
|
||||||
Create the file `app/main.ts` with the following content:
|
|
||||||
|
|
||||||
+makeExample('app/main.ts')
|
|
||||||
|
|
||||||
|
|
||||||
- var _pBD_bootstrapModule = _docsFor == 'dart' ? _bootstrapModule : 'platformBrowserDynamic().bootstrapModule'
|
|
||||||
|
|
||||||
:marked
|
|
||||||
This code initializes the platform that your application runs in, then uses the platform to
|
|
||||||
bootstrap your `!{_AppModuleVsAppComp}`.
|
|
||||||
|
|
||||||
### Why create separate *<span ngio-ex>main.ts</span>*<span if-docs="ts">, app module</span> and app component files?
|
|
||||||
|
|
||||||
App bootstrapping is a separate concern from<span if-docs="ts"> creating a module or</span>
|
|
||||||
presenting a view. Testing the component is much easier if it doesn't also try to run the entire application.
|
|
||||||
|
|
||||||
|
|
||||||
.callout.is-helpful
|
|
||||||
header Bootstrapping is platform-specific
|
|
||||||
|
|
||||||
:marked
|
|
||||||
Because the QuickStart application runs directly in the browser, `main.ts` imports the
|
|
||||||
`!{_platformBrowserDynamicVsBootStrap}` function from `#{_angular_browser_uri}`, not
|
|
||||||
`#{_angular_core_uri}`. On a mobile device, you might load a !{_moduleVsComp} with
|
|
||||||
[Apache Cordova](https://cordova.apache.org/) or
|
|
||||||
[NativeScript](https://www.nativescript.org/), using a bootstrap function that's specific
|
|
||||||
to that platform.
|
|
||||||
|
|
||||||
.l-main-section
|
|
||||||
h2#index Step !{step++}: Define the web page that hosts the application
|
|
||||||
:marked
|
|
||||||
In the *#{_indexHtmlDir}* folder,
|
|
||||||
create an `index.html` file and paste the following lines into it:
|
|
||||||
|
|
||||||
+makeExample('index.html')
|
|
||||||
|
|
||||||
|
|
||||||
block commentary-on-index-html
|
|
||||||
:marked
|
|
||||||
The noteworthy sections here are:
|
|
||||||
|
|
||||||
* JavaScript libraries: `core-js` polyfills for older browsers, the `zone.js` and
|
|
||||||
`reflect-metadata` libraries needed by Angular, and the `SystemJS` library for module loading.
|
|
||||||
* Configuration file for `SystemJS`, and a script
|
|
||||||
where you import and run the `app` module which refers to the `main` file that you just
|
|
||||||
wrote.
|
|
||||||
* The `<my-app>` tag in the `<body>` which is *where your app lives!*
|
|
||||||
|
|
||||||
|
|
||||||
:marked
|
|
||||||
### Add some style
|
|
||||||
|
|
||||||
Styles aren't essential, but they're nice, and `index.html` assumes that you have
|
|
||||||
a stylesheet called `styles.css`.
|
|
||||||
|
|
||||||
Create a `styles.css` file in the *#{_indexHtmlDir}* folder, and start styling,
|
|
||||||
perhaps with the minimal styles shown below.
|
|
||||||
|
|
||||||
+makeExcerpt('styles.css (excerpt)', 'quickstart')
|
|
||||||
|
|
||||||
.callout.is-helpful
|
|
||||||
:marked
|
|
||||||
For the full set of master styles used by the documentation samples,
|
|
||||||
see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/_boilerplate/styles.css).
|
|
||||||
|
|
||||||
.l-main-section#build-and-run
|
|
||||||
h2 Step !{step++}: Build and run the application
|
|
||||||
block run-app
|
|
||||||
:marked
|
|
||||||
Open a terminal window and enter this command:
|
|
||||||
code-example.code-shell.
|
|
||||||
npm start
|
|
||||||
aside.is-right
|
|
||||||
:marked
|
:marked
|
||||||
[Read more](https://github.com/angular/quickstart/blob/master/README.md#npm-scripts) about
|
### Next step
|
||||||
other useful npm scripts included in this example's `package.json`.
|
|
||||||
|
|
||||||
:marked
|
To learn how to write a real application, your next step is to set up a local development
|
||||||
That command runs the following two parallel node processes:
|
environment and begin exploring with code. The [**Developer Guide**](guide/index.html)
|
||||||
* The TypeScript compiler in watch mode.
|
shows you how.
|
||||||
* A static file server called _lite-server_ that loads `index.html` in a browser
|
|
||||||
and refreshes the browser when application files change.
|
|
||||||
|
|
||||||
In a few moments, a browser tab should open and display the following:
|
|
||||||
|
|
||||||
figure.image-display
|
|
||||||
img(src='/resources/images/devguide/quickstart/hello-angular.png' alt="Output of QuickStart app")
|
|
||||||
|
|
||||||
|
|
||||||
block build-app
|
|
||||||
//- Nothing for ts.
|
|
||||||
|
|
||||||
.l-main-section#make-changes
|
|
||||||
h2 Step !{step++}: Make some live changes
|
|
||||||
:marked
|
|
||||||
Try changing the message in <span ngio-ex>app/app.component.ts</span> to "Hello Again Angular!".
|
|
||||||
|
|
||||||
block server-watching
|
|
||||||
:marked
|
|
||||||
The TypeScript compiler and `lite-server` will detect your change, recompile the TypeScript into JavaScript,
|
|
||||||
refresh the browser, and display your revised message.
|
|
||||||
|
|
||||||
Close the terminal window when you're done to terminate both the compiler and the server.
|
|
||||||
|
|
||||||
.l-main-section
|
|
||||||
h2#wrap-up Wrap up and next steps
|
|
||||||
:marked
|
|
||||||
The final project folder structure looks like this:
|
|
||||||
block project-file-structure
|
|
||||||
.filetree
|
|
||||||
.file angular-quickstart
|
|
||||||
.children
|
|
||||||
.file app
|
|
||||||
.children
|
|
||||||
.file app.component.ts
|
|
||||||
.file app.module.ts
|
|
||||||
.file main.ts
|
|
||||||
.file node_modules ...
|
|
||||||
.file index.html
|
|
||||||
.file package.json
|
|
||||||
.file styles.css
|
|
||||||
.file systemjs.config.js
|
|
||||||
.file tsconfig.json
|
|
||||||
|
|
||||||
block project-files
|
|
||||||
:marked
|
|
||||||
To see the file contents, open the <live-example></live-example>.
|
|
||||||
|
|
||||||
.l-main-section
|
|
||||||
:marked
|
|
||||||
## What next?
|
|
||||||
This first application doesn't do much. It's basically "Hello, World" for Angular.
|
|
||||||
|
|
||||||
You wrote a little Angular component, created a simple `index.html`, and launched with a
|
|
||||||
static file server.
|
|
||||||
|
|
||||||
+ifDocsFor('ts')
|
|
||||||
:marked
|
|
||||||
You also created the basic application setup that you'll re-use for other
|
|
||||||
sections in this guide. From here, the changes you'll make in the
|
|
||||||
`package.json` or `index.html` files are only minor updates to add libraries or some css
|
|
||||||
stylesheets. You also won't need to revisit module loading again.
|
|
||||||
:marked
|
|
||||||
To take the next step and build a small application that demonstrates real features that you can
|
|
||||||
build with Angular, carry on to the [Tour of Heroes tutorial](./tutorial)!
|
|
||||||
|
|||||||
@ -79,5 +79,3 @@ figure.image-display
|
|||||||
met in countless applications. Everything has a reason.
|
met in countless applications. Everything has a reason.
|
||||||
|
|
||||||
And we’ll meet many of the core fundamentals of Angular along the way.
|
And we’ll meet many of the core fundamentals of Angular along the way.
|
||||||
|
|
||||||
[Let's get started!](./toh-pt1.html)
|
|
||||||
|
|||||||
@ -19,7 +19,6 @@
|
|||||||
"icon": "query-builder",
|
"icon": "query-builder",
|
||||||
"title": "Quickstart",
|
"title": "Quickstart",
|
||||||
"subtitle": "TypeScript",
|
"subtitle": "TypeScript",
|
||||||
"description": "A quick look at Angular basics",
|
|
||||||
"banner": "A quick look at Angular basics"
|
"banner": "A quick look at Angular basics"
|
||||||
},
|
},
|
||||||
|
|
||||||
|
|||||||
@ -1,5 +1,6 @@
|
|||||||
block includes
|
block includes
|
||||||
include ../_util-fns
|
include ../_util-fns
|
||||||
|
- var _angular_io = 'angular.io';
|
||||||
|
|
||||||
- var __lang = _docsFor || current.path[1] || 'ts';
|
- var __lang = _docsFor || current.path[1] || 'ts';
|
||||||
- var guideData = public.docs[__lang].latest.guide._data;
|
- var guideData = public.docs[__lang].latest.guide._data;
|
||||||
@ -29,8 +30,8 @@ table(width="100%")
|
|||||||
td <b><a href="../quickstart.html">QuickStart</a></b>
|
td <b><a href="../quickstart.html">QuickStart</a></b>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
A first taste of Angular with zero installation.
|
A first taste of Angular<span if-docs="ts"> with zero installation.
|
||||||
Run "Hello World" in an online code editor and start playing with live code.
|
Run "Hello World" in an online code editor and start playing with live code</span>.
|
||||||
tr(style=top)
|
tr(style=top)
|
||||||
td <b>Guide</b>
|
td <b>Guide</b>
|
||||||
td
|
td
|
||||||
@ -72,18 +73,20 @@ table(width="100%")
|
|||||||
|
|
||||||
Look for a link to a running version of that sample, often near the top of the page,
|
Look for a link to a running version of that sample, often near the top of the page,
|
||||||
such as this <live-example name="architecture"></live-example> from the [Architecture](architecture.html) page.
|
such as this <live-example name="architecture"></live-example> from the [Architecture](architecture.html) page.
|
||||||
|
<span if-docs="ts">
|
||||||
The link launches a browser-based, code editor where you can inspect, modify, save, and download the code.
|
The link launches a browser-based, code editor where you can inspect, modify, save, and download the code.
|
||||||
|
</span>
|
||||||
|
|
||||||
## Reference pages
|
## Reference pages
|
||||||
|
|
||||||
* The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
|
* The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
|
||||||
* The [Glossary](glossary.html) defines terms that Angular developers should know.
|
* The [Glossary](glossary.html) defines terms that Angular developers should know.
|
||||||
* The [Change Log](change-log.html) announces what's new and changed in the documentation.
|
<li if-docs="ts">The [Change Log](change-log.html) announces what's new and changed in the documentation.</li>
|
||||||
* The [API Reference](../api/) is the authority on every public-facing member of the Angular libraries.
|
* The [API Reference](../api/) is the authority on every public-facing member of the Angular libraries.
|
||||||
|
|
||||||
## Feedback
|
## Feedback
|
||||||
|
|
||||||
We welcome feedback!
|
We welcome feedback!
|
||||||
|
|
||||||
* Use the <a href="!{_ngDocRepoURL}" target="_blank" title="angular docs on github">angular.io Github repository</a> for **documentation** issues and pull requests.
|
* Use the <a href="!{_ngDocRepoURL}" target="_blank" title="angular docs on github">!{_angular_io} Github repository</a> for **documentation** issues and pull requests.
|
||||||
* Use the <a href="!{_ngRepoURL}" target="_blank" title="angular source on github">Angular Github repository</a> to report issues with **Angular** itself.
|
* Use the <a href="!{_ngRepoURL}" target="_blank" title="angular source on github">Angular Github repository</a> to report issues with **Angular** itself.
|
||||||
|
|||||||
@ -9,7 +9,6 @@ figure
|
|||||||
Those new to Angular may wish to follow this popular learning path.
|
Those new to Angular may wish to follow this popular learning path.
|
||||||
<br class="l-clear-left">
|
<br class="l-clear-left">
|
||||||
|
|
||||||
:marked
|
|
||||||
1. [Setup](setup.html "Setup locally withe Quickstart seed") for local Angular development, if you haven't already done so.
|
1. [Setup](setup.html "Setup locally withe Quickstart seed") for local Angular development, if you haven't already done so.
|
||||||
|
|
||||||
1. Take the [*Tour of Heroes* tutorial](../tutorial "Tour of Heroes").
|
1. Take the [*Tour of Heroes* tutorial](../tutorial "Tour of Heroes").
|
||||||
@ -19,8 +18,9 @@ figure
|
|||||||
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
|
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
|
||||||
|
|
||||||
1. <a id="architecture"></a>Read the [Architecture](architecture.html) overview for the big picture.
|
1. <a id="architecture"></a>Read the [Architecture](architecture.html) overview for the big picture.
|
||||||
|
<li if-docs="ts"><p>
|
||||||
1. [The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application.
|
[The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application.
|
||||||
|
</p></li>
|
||||||
|
|
||||||
1. [Displaying Data](displaying-data.html) shows how data binding puts component property values on screen.
|
1. [Displaying Data](displaying-data.html) shows how data binding puts component property values on screen.
|
||||||
|
|
||||||
@ -40,4 +40,4 @@ figure
|
|||||||
### Next Step
|
### Next Step
|
||||||
|
|
||||||
Try the [tutorial](../tutorial "Tour of Heroes") if you're ready to start coding or
|
Try the [tutorial](../tutorial "Tour of Heroes") if you're ready to start coding or
|
||||||
visit the [Architecture](architecture.html "Basic Concepts") guide if you prefer to learn the basic concepts first.
|
visit the [Architecture](architecture.html "Basic Concepts") page if you prefer to learn the basic concepts first.
|
||||||
|
|||||||
@ -1,22 +1,31 @@
|
|||||||
block includes
|
block includes
|
||||||
include ../_util-fns
|
include ../_util-fns
|
||||||
|
- var _prereq = 'node and npm';
|
||||||
|
- var _playground = 'playground';
|
||||||
|
- var _Install = 'Install';
|
||||||
|
//- npm commands
|
||||||
|
- var _install = 'install';
|
||||||
|
- var _start = 'start';
|
||||||
|
|
||||||
a#develop-locally
|
a#develop-locally
|
||||||
:marked
|
:marked
|
||||||
## Setup a local development environment
|
## Setup a local development environment
|
||||||
|
|
||||||
|
<span if-docs="ts">
|
||||||
The <live-example name=quickstart>QuickStart live-coding</live-example> example is an Angular _playground_.
|
The <live-example name=quickstart>QuickStart live-coding</live-example> example is an Angular _playground_.
|
||||||
It's not where you'd develop a real application.
|
It's not where you'd develop a real application.
|
||||||
You [should develop locally](#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular.
|
You [should develop locally](#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular.
|
||||||
|
</span>
|
||||||
|
|
||||||
Setting up a new project on your machine is quick and easy with the **QuickStart seed**,
|
Setting up a new project on your machine is quick and easy with the **QuickStart seed**,
|
||||||
maintained [on github](https://github.com/angular/quickstart "Install the github QuickStart repo").
|
maintained [on github](!{_qsRepo} "Install the github QuickStart repo").
|
||||||
|
|
||||||
Make sure you have [node and npm installed](#install-node "What if you don't have node?").
|
Make sure you have [!{_prereq} installed](#install-prerequisites "What if you don't have !{_prereq}?").
|
||||||
Then ...
|
Then ...
|
||||||
1. Create a project folder (you can call it <span ngio-ex>quickstart</span> and rename it later).
|
1. Create a project folder (you can call it `quickstart` and rename it later).
|
||||||
1. [Clone](#clone "Clone it from github") or [download](#download "download it from github") the **QuickStart seed** into your project folder.
|
1. [Clone](#clone "Clone it from github") or [download](#download "download it from github") the **QuickStart seed** into your project folder.
|
||||||
1. [Install the _npm_ packages](#install-node "What if you don't have node?").
|
1. !{_Install} [!{_npm}](#install-prerequisites "What if you don't have !{_prereq}?") packages.
|
||||||
1. Run `npm start` to launch the sample application.
|
1. Run `!{_npm} !{_start}` to launch the sample application.
|
||||||
|
|
||||||
a#clone
|
a#clone
|
||||||
:marked
|
:marked
|
||||||
@ -25,54 +34,59 @@ a#clone
|
|||||||
Perform the _clone-to-launch_ steps with these terminal commands.
|
Perform the _clone-to-launch_ steps with these terminal commands.
|
||||||
|
|
||||||
code-example(language="sh" class="code-shell").
|
code-example(language="sh" class="code-shell").
|
||||||
git clone https://github.com/angular/quickstart.git quickstart
|
git clone !{_qsRepo}.git quickstart
|
||||||
cd quickstart
|
cd quickstart
|
||||||
npm install
|
!{_npm} !{_install}
|
||||||
npm start
|
!{_npm} !{_start}
|
||||||
|
|
||||||
a#download
|
a#download
|
||||||
:marked
|
:marked
|
||||||
### Download
|
### Download
|
||||||
<a href="https://github.com/angular/quickstart/archive/master.zip" title="Download the QuickStart seed repository">Download the QuickStart seed</a>
|
<a href="!{_qsRepoZip}" title="Download the QuickStart seed repository">Download the QuickStart seed</a>
|
||||||
and unzip it into your project folder. Then perform the remaining steps with these terminal commands.
|
and unzip it into your project folder. Then perform the remaining steps with these terminal commands.
|
||||||
|
|
||||||
code-example(language="sh" class="code-shell").
|
code-example(language="sh" class="code-shell").
|
||||||
cd quickstart
|
cd quickstart
|
||||||
npm install
|
!{_npm} !{_install}
|
||||||
npm start
|
!{_npm} !{_start}
|
||||||
|
|
||||||
.l-main-section
|
.l-main-section#seed
|
||||||
:marked
|
:marked
|
||||||
## What's in the QuickStart seed?
|
## What's in the QuickStart seed?
|
||||||
|
|
||||||
The **QuickStart seed** contains the same application as the QuickStart playground
|
block qs-seed
|
||||||
and even has <live-example>its own _playground_</live-example>
|
:marked
|
||||||
that accomodates development of richer examples in a live coding environment.
|
The **QuickStart seed** contains the same application as the QuickStart playground
|
||||||
|
and even has <live-example>its own _playground_</live-example>
|
||||||
But it's true purpose is to provide a solid foundation for _local_ development.
|
that accomodates development of richer examples in a live coding environment.
|
||||||
Consequently, there are _many more files_ in the project folder on your machine,
|
|
||||||
most of which you can [learn about later](setup-systemjs-anatomy.html "Setup Anatomy").
|
But it's true purpose is to provide a solid foundation for _local_ development.
|
||||||
|
Consequently, there are _many more files_ in the project folder on your machine,
|
||||||
Focus on the following three TypeScript (`.ts`) files in the **`/app`** folder.
|
most of which you can [learn about later](setup-systemjs-anatomy.html "Setup Anatomy").
|
||||||
|
|
||||||
.filetree
|
block core-files
|
||||||
.file app
|
:marked
|
||||||
.children
|
Focus on the following three TypeScript (`.ts`) files in the **`/app`** folder.
|
||||||
.file app.component.ts
|
|
||||||
.file app.module.ts
|
.filetree
|
||||||
.file main.ts
|
.file app
|
||||||
|
.children
|
||||||
|
.file app.component.ts
|
||||||
|
.file app.module.ts
|
||||||
|
.file main.ts
|
||||||
|
|
||||||
|
+makeTabs(`
|
||||||
|
setup/ts/app/app.component.ts,
|
||||||
|
setup/ts/app/app.module.ts,
|
||||||
|
setup/ts/app/main.ts
|
||||||
|
`, '', `
|
||||||
|
app/app.component.ts,
|
||||||
|
app/app.module.ts,
|
||||||
|
app/main.ts
|
||||||
|
`)(format='.')
|
||||||
|
|
||||||
+makeTabs(`
|
|
||||||
setup/ts/app/app.component.ts,
|
|
||||||
setup/ts/app/app.module.ts,
|
|
||||||
setup/ts/app/main.ts
|
|
||||||
`, '', `
|
|
||||||
app/app.component.ts,
|
|
||||||
app/app.module.ts,
|
|
||||||
app/main.ts
|
|
||||||
`)(format='.')
|
|
||||||
:marked
|
:marked
|
||||||
All guides and cookbooks have _at least these three files_. Each file has a distinct purpose and evolves independently as the application grows.
|
All guides and cookbooks have _at least these core files_. Each file has a distinct purpose and evolves independently as the application grows.
|
||||||
|
|
||||||
style td, th {vertical-align: top}
|
style td, th {vertical-align: top}
|
||||||
table(width="100%")
|
table(width="100%")
|
||||||
@ -82,13 +96,13 @@ table(width="100%")
|
|||||||
th File
|
th File
|
||||||
th Purpose
|
th Purpose
|
||||||
tr
|
tr
|
||||||
td <code>app.component.ts</code>
|
td <ngio-ex>app.component.ts</ngio-ex>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
Defines the same `AppComponent` as the one in the QuickStart playground.
|
Defines the same `AppComponent` as the one in the QuickStart !{_playground}.
|
||||||
It is the **root** component of what will become a tree of nested components
|
It is the **root** component of what will become a tree of nested components
|
||||||
as the application evolves.
|
as the application evolves.
|
||||||
tr
|
tr(if-docs="ts")
|
||||||
td <code>app.module.ts</code>
|
td <code>app.module.ts</code>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
@ -96,7 +110,7 @@ table(width="100%")
|
|||||||
Right now it declares only the `AppComponent`.
|
Right now it declares only the `AppComponent`.
|
||||||
Soon there will be more components to declare.
|
Soon there will be more components to declare.
|
||||||
tr
|
tr
|
||||||
td <code>main.ts</code>
|
td <ngio-ex>main.ts</ngio-ex>
|
||||||
td
|
td
|
||||||
:marked
|
:marked
|
||||||
Compiles the application with the [JiT compiler](../glossary.html#jit)
|
Compiles the application with the [JiT compiler](../glossary.html#jit)
|
||||||
@ -114,11 +128,12 @@ table(width="100%")
|
|||||||
br
|
br
|
||||||
br
|
br
|
||||||
|
|
||||||
a#install-node
|
a#install-prerequisites
|
||||||
.l-main-section
|
.l-main-section
|
||||||
:marked
|
:marked
|
||||||
## Appendix: _node_ and _npm_
|
## Appendix: !{_prereq}
|
||||||
|
block install-tooling
|
||||||
|
:marked
|
||||||
Node.js and npm are essential to modern web development with Angular and other platforms.
|
Node.js and npm are essential to modern web development with Angular and other platforms.
|
||||||
Node powers client development and build tools.
|
Node powers client development and build tools.
|
||||||
The _npm_ package manager, itself a _node_ application, installs JavaScript libraries.
|
The _npm_ package manager, itself a _node_ application, installs JavaScript libraries.
|
||||||
@ -134,31 +149,32 @@ a#install-node
|
|||||||
You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that
|
You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that
|
||||||
use other versions of node and npm.
|
use other versions of node and npm.
|
||||||
|
|
||||||
a#why-locally
|
+ifDocsFor('ts')
|
||||||
.l-main-section
|
a#why-locally
|
||||||
:marked
|
.l-main-section
|
||||||
## Appendix: Why develop locally
|
:marked
|
||||||
|
## Appendix: Why develop locally
|
||||||
|
|
||||||
<live-example>Live coding</live-example> in the browser is a great way to explore Angular.
|
<live-example>Live coding</live-example> in the browser is a great way to explore Angular.
|
||||||
|
|
||||||
Links on almost every documentation page open completed samples in the browser.
|
Links on almost every documentation page open completed samples in the browser.
|
||||||
You can play with the sample code, share your changes with friends, and download and run the code on your own machine.
|
You can play with the sample code, share your changes with friends, and download and run the code on your own machine.
|
||||||
|
|
||||||
The [QuickStart](../quickstart.html "Angular QuickStart Playground") shows just the `AppComponent` file.
|
The [QuickStart](../quickstart.html "Angular QuickStart Playground") shows just the `AppComponent` file.
|
||||||
It creates the equivalent of `app.module.ts` and `main.ts` internally _for the playground only_.
|
It creates the equivalent of `app.module.ts` and `main.ts` internally _for the playground only_.
|
||||||
so the reader can discover Angular without distraction.
|
so the reader can discover Angular without distraction.
|
||||||
The other samples are based on the QuickStart seed.
|
The other samples are based on the QuickStart seed.
|
||||||
|
|
||||||
As much fun as this is ...
|
As much fun as this is ...
|
||||||
* you can't ship your app in plunker
|
* you can't ship your app in plunker
|
||||||
* you aren't always online when writing code
|
* you aren't always online when writing code
|
||||||
* transpiling TypeScript in the browser is slow
|
* transpiling TypeScript in the browser is slow
|
||||||
* the type support, refactoring, and code completion only work in your local IDE
|
* the type support, refactoring, and code completion only work in your local IDE
|
||||||
|
|
||||||
Use the <live-example><i>live coding</i></live-example> environment as a _playground_,
|
Use the <live-example><i>live coding</i></live-example> environment as a _playground_,
|
||||||
a place to try the documentation samples and experiment on your own.
|
a place to try the documentation samples and experiment on your own.
|
||||||
It's the perfect place to reproduce a bug when you want to
|
It's the perfect place to reproduce a bug when you want to
|
||||||
<a href="https://github.com/angular/angular.io/issues/new" target="_blank" title="File a documentation issue">file a documentation issue</a> or
|
<a href="https://github.com/angular/angular.io/issues/new" target="_blank" title="File a documentation issue">file a documentation issue</a> or
|
||||||
<a href="https://github.com/angular/angular/issues/new" target="_blank" title="File an Angular issue">file an issue with Angular itself</a>.
|
<a href="https://github.com/angular/angular/issues/new" target="_blank" title="File an Angular issue">file an issue with Angular itself</a>.
|
||||||
|
|
||||||
For real development, we strongly recommend [developing locally](#develop-locally).
|
For real development, we strongly recommend [developing locally](#develop-locally).
|
||||||
|
|||||||
@ -1,17 +1,20 @@
|
|||||||
include _util-fns
|
block includes
|
||||||
|
include _util-fns
|
||||||
|
- var _on_Plunkr = 'on Plunkr';
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
Angular applications are made of _components_.
|
Angular applications are made of _components_.
|
||||||
A _component_ is the combination of an HTML template and a component class that controls a portion of the screen. Here is an example of a component that displays a simple string:
|
A _component_ is the combination of an HTML template and a component class that controls a portion of the screen. Here is an example of a component that displays a simple string:
|
||||||
|
|
||||||
+makeExample('app/app.component.ts','','app/app.component.ts')(format='.')
|
+makeExample('app/app.component.ts')(format='.')
|
||||||
|
|
||||||
:marked
|
:marked
|
||||||
You can try this out without installing anything. Open the <a href="/resources/live-examples/quickstart/ts/plnkr.html" target="_blank">QuickStart example on Plunkr</a> in another tab
|
You can try this out without installing anything. Open the <live-example>QuickStart example !{_on_Plunkr}</live-example> in another tab
|
||||||
and follow along.
|
and follow along.
|
||||||
|
|
||||||
Every component begins with a `@Component` [_decorator_](glossary.html#decorator '"Decorator" explained') function
|
Every component begins with an `@Component` [!{_decorator}](glossary.html#!{_decorator} '"!{_decorator}" explained')
|
||||||
that takes a _metadata_ object. The metadata object describes how the HTML template and component class work together.
|
<span if-docs="ts">function</span> that
|
||||||
|
<span if-docs="ts">takes a _metadata_ object. The metadata object</span> describes how the HTML template and component class work together.
|
||||||
|
|
||||||
The `selector` property tells Angular to display the component inside a custom `<my-app>` tag in the `index.html`.
|
The `selector` property tells Angular to display the component inside a custom `<my-app>` tag in the `index.html`.
|
||||||
+makeExample('index.html','my-app','index.html (inside <body>)')(format='.')
|
+makeExample('index.html','my-app','index.html (inside <body>)')(format='.')
|
||||||
@ -25,11 +28,12 @@ include _util-fns
|
|||||||
|
|
||||||
Interpolation binding is one of many Angular features you'll discover in this documentation.
|
Interpolation binding is one of many Angular features you'll discover in this documentation.
|
||||||
|
|
||||||
.callout.is-helpful
|
+ifDocsFor('ts')
|
||||||
header A word about TypeScript
|
.callout.is-helpful
|
||||||
p.
|
header A word about TypeScript
|
||||||
This example is written in <a href="http://www.typescriptlang.org/" target="_blank" title="TypeScript">TypeScript</a>, a superset of JavaScript. Angular
|
p.
|
||||||
uses TypeScript because its types make it easy to support developer productivity with tooling. You can also write Angular code in JavaScript; <a href="cookbook/ts-to-js.html">this guide</a> explains how.
|
This example is written in <a href="http://www.typescriptlang.org/" target="_blank" title="TypeScript">TypeScript</a>, a superset of JavaScript. Angular
|
||||||
|
uses TypeScript because its types make it easy to support developer productivity with tooling. You can also write Angular code in JavaScript; <a href="cookbook/ts-to-js.html">this guide</a> explains how.
|
||||||
|
|
||||||
.l-sub-section
|
.l-sub-section
|
||||||
:marked
|
:marked
|
||||||
|
|||||||
@ -8,6 +8,7 @@ BASE="public/docs/ts"
|
|||||||
LATEST="$BASE/latest"
|
LATEST="$BASE/latest"
|
||||||
CACHE="$BASE/_cache"
|
CACHE="$BASE/_cache"
|
||||||
|
|
||||||
|
# setup-systemjs-anatomy.jade?
|
||||||
FILES="
|
FILES="
|
||||||
guide/architecture.jade
|
guide/architecture.jade
|
||||||
guide/attribute-directives.jade
|
guide/attribute-directives.jade
|
||||||
@ -16,10 +17,12 @@ guide/dependency-injection.jade
|
|||||||
guide/displaying-data.jade
|
guide/displaying-data.jade
|
||||||
guide/hierarchical-dependency-injection.jade
|
guide/hierarchical-dependency-injection.jade
|
||||||
guide/index.jade
|
guide/index.jade
|
||||||
|
guide/learning-angular.jade
|
||||||
guide/lifecycle-hooks.jade
|
guide/lifecycle-hooks.jade
|
||||||
guide/pipes.jade
|
guide/pipes.jade
|
||||||
guide/security.jade
|
guide/security.jade
|
||||||
guide/server-communication.jade
|
guide/server-communication.jade
|
||||||
|
guide/setup.jade
|
||||||
guide/structural-directives.jade
|
guide/structural-directives.jade
|
||||||
guide/template-syntax.jade
|
guide/template-syntax.jade
|
||||||
glossary.jade
|
glossary.jade
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user