iSharkFly-Docs/angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[WIP] docs(quickstart): QuickStart reboot (#2762)

Browse Source
This commit is contained in:
Ward Bell 2016-11-21 17:13:21 -08:00
parent a7525721c0
commit ec2e6cb2c7
58 changed files with 859 additions and 568 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
public/_includes/_next-item.jade
View File

@ -1,5 +1,7 @@
- var currentPage = false
- var nextPage = false
- var hideNextPage = false;
- var data = public.docs[current.path[1]][current.path[2]][current.path[3]]._data
for page, slug in data
@ -7,13 +9,16 @@ for page, slug in data
// CHECK IF CURRENT PAGE IS SET, THEN SET NEXT PAGE
if currentPage
if !nextPage && page.nextable && !page.hide
.l-sub-section
h3 Next Step
a(href="/docs/#{current.path[1]}/#{current.path[2]}/#{current.path[3]}/#{slug}.html") #{page.title}
if !hideNextPage
.l-sub-section
h3 Next Step
a(href="/docs/#{current.path[1]}/#{current.path[2]}/#{current.path[3]}/#{slug}.html") #{page.title}
//NEXT PAGE HAS NOW BEEN SET
- var nextPage = true
- hideNextPage = page.hideNextPage
// SET CURRENT PAGE FLAG WHEN YOU PASS IT
if current.path[4] == slug
- var currentPage = true

1
public/docs/_examples/_boilerplate/package.json
View File

@ -1,6 +1,7 @@
{
"name": "angular-examples",
"version": "1.0.0",
"private": true,
"description": "Example package.json, only contains needed scripts for examples. See _examples/package.json for master package.json.",
"scripts": {
"start": "tsc && concurrently \"tsc -w\" \"lite-server\" ",

4
public/docs/_examples/cb-aot-compiler/e2e-spec.ts
View File

@ -1,4 +1,4 @@
'use strict'; // necessary for es6 output in node
'use strict'; // necessary for es6 output in node
import { browser, element, by } from 'protractor';
@ -11,7 +11,7 @@ describe('AOT Compilation', function () {
it('should load page and click button', function (done) {
let headingSelector = element.all(by.css('h1')).get(0);
expect(headingSelector.getText()).toEqual('My First Angular App');
expect(headingSelector.getText()).toEqual('Hello Angular');
expect(element.all(by.xpath('//div[text()="Magneta"]')).get(0).isPresent()).toBe(true);
expect(element.all(by.xpath('//div[text()="Bombasto"]')).get(0).isPresent()).toBe(true);

2
public/docs/_examples/cb-aot-compiler/ts/app/app.component.html
View File

@ -1,6 +1,6 @@
<!-- #docregion -->
<button (click)="toggleHeading()">Toggle Heading</button>
<h1 *ngIf="showHeading">My First Angular App</h1>
<h1 *ngIf="showHeading">Hello Angular</h1>
<h3>List of Heroes</h3>
<div *ngFor="let hero of heroes">{{hero}}</div>

1
public/docs/_examples/package.json
View File

@ -1,6 +1,7 @@
{
"name": "angular-examples-master",
"version": "1.0.0",
"private": true,
"description": "Master package.json, the superset of all dependencies for all of the _example package.json files. See _boilerplate/package.json for example npm scripts.",
"scripts": {
"protractor": "protractor",

2
public/docs/_examples/quickstart/dart/lib/app_component.dart
View File

@ -5,7 +5,7 @@ import 'package:angular2/core.dart';
// #docregion metadata
@Component(
selector: 'my-app',
template: '<h1>Hello Angular!</h1>')
template: '<h1>Hello Angular</h1>')
// #enddocregion metadata
// #docregion class
class AppComponent {}

2
public/docs/_examples/quickstart/e2e-spec.ts
View File

@ -4,7 +4,7 @@ import { browser, element, by } from 'protractor';
describe('QuickStart E2E Tests', function () {
let expectedMsg = 'Hello Angular!';
let expectedMsg = 'Hello Angular';
beforeEach(function () {
browser.get('');

2
public/docs/_examples/quickstart/js/app/app.component.js
View File

@ -10,7 +10,7 @@
ng.core.Component({
// #enddocregion ng-namespace-funcs
selector: 'my-app',
template: '<h1>Hello Angular!</h1>'
template: '<h1>Hello Angular</h1>'
// #docregion ng-namespace-funcs
})
// #enddocregion component

1
public/docs/_examples/quickstart/ts/.gitignore vendored
View File

@ -1 +0,0 @@
!systemjs.config.1.js

10
public/docs/_examples/quickstart/ts/app/app.component.ts
View File

@ -1,14 +1,8 @@
// #docregion
// #docregion import
import { Component } from '@angular/core';
// #enddocregion import
// #docregion metadata
@Component({
selector: 'my-app',
template: '<h1>Hello Angular!</h1>'
template: `<h1>Hello {{name}}</h1>`
})
// #enddocregion metadata
// #docregion class
export class AppComponent { }
// #enddocregion class
export class AppComponent { name = 'Angular'; }

4
public/docs/_examples/quickstart/ts/app/app.module.ts
View File

@ -1,13 +1,11 @@
// #docregion
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { AppComponent } from './app.component';
@NgModule({
imports: [ BrowserModule ],
declarations: [ AppComponent ],
bootstrap: [ AppComponent ]
})
export class AppModule { }

6
public/docs/_examples/quickstart/ts/app/main.ts
View File

@ -1,9 +1,5 @@
// #docregion
// #docregion import
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app.module';
// #enddocregion import
const platform = platformBrowserDynamic();
platform.bootstrapModule(AppModule);
platformBrowserDynamic().bootstrapModule(AppModule);

27
public/docs/_examples/quickstart/ts/index.html
View File

@ -1,37 +1,36 @@
<!DOCTYPE html>
<!-- #docregion -->
<html>
<head>
<title>Angular QuickStart</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">
<style>
body {color:#369;font-family: Arial,Helvetica,sans-serif;}
</style>
<!-- 1. Load libraries -->
<!-- #docregion libraries -->
<!-- Polyfills for older browsers -->
<!-- #docregion polyfills -->
<!-- Polyfill for older browsers -->
<script src="node_modules/core-js/client/shim.min.js"></script>
<!-- #enddocregion polyfills -->
<script src="node_modules/zone.js/dist/zone.js"></script>
<script src="node_modules/reflect-metadata/Reflect.js"></script>
<script src="node_modules/systemjs/dist/system.src.js"></script>
<!-- #enddocregion libraries -->
<!-- 2. Configure SystemJS -->
<!-- #docregion systemjs -->
<!-- #docregion autobootstrap-->
<script> window.autoBootstrap = true; </script>
<!-- #enddocregion autobootstrap-->
<script src="systemjs.config.js"></script>
<script>
System.import('app').catch(function(err){ console.error(err); });
</script>
<!-- #enddocregion systemjs -->
</head>
<!-- 3. Display the application -->
<!-- #docregion my-app -->
<body>
<my-app>Loading...</my-app>
<!-- #docregion my-app-->
<my-app>Loading AppComponent content here ...</my-app>
<!-- #enddocregion my-app-->
</body>
<!-- #enddocregion my-app -->
</html>

8
public/docs/_examples/quickstart/ts/plnkr.json
View File

@ -1,9 +1,9 @@
{
"description": "QuickStart",
"files": [
"!**/*.d.ts",
"!**/*.js",
"!**/*.[1].*"
"app/app.component.ts",
"index.html"
],
"open": "app/app.component.ts",
"tags": ["quickstart"]
}
}

17
public/docs/_examples/setup/e2e-spec.ts Normal file
View File

@ -0,0 +1,17 @@
'use strict'; // necessary for es6 output in node
import { browser, element, by } from 'protractor';
describe('QuickStart E2E Tests', function () {
let expectedMsg = 'Hello Angular';
beforeEach(function () {
browser.get('');
});
it(`should display: ${expectedMsg}`, function () {
expect(element(by.css('h1')).getText()).toEqual(expectedMsg);
});
});

35
public/docs/_examples/setup/ts/app/app.component.spec.ts Normal file
View File

@ -0,0 +1,35 @@
/* tslint:disable:no-unused-variable */
import { AppComponent } from './app.component';
import { async, ComponentFixture, TestBed } from '@angular/core/testing';
import { By } from '@angular/platform-browser';
import { DebugElement } from '@angular/core';
//////// SPECS /////////////
describe('AppComponent', function () {
let de: DebugElement;
let comp: AppComponent;
let fixture: ComponentFixture<AppComponent>;
beforeEach(async(() => {
TestBed.configureTestingModule({
declarations: [ AppComponent ]
})
.compileComponents();
}));
beforeEach(() => {
fixture = TestBed.createComponent(AppComponent);
comp = fixture.componentInstance;
de = fixture.debugElement.query(By.css('h1'));
});
it('should create component', () => expect(comp).toBeDefined() );
it('should have expected <h1> text', () => {
fixture.detectChanges();
const h1 = de.nativeElement;
expect(h1.innerText).toMatch(/angular/i,
'<h1> should say something about "Angular"');
});
});

8
public/docs/_examples/setup/ts/app/app.component.ts Normal file
View File

@ -0,0 +1,8 @@
// #docregion
import { Component } from '@angular/core';
@Component({
selector: 'my-app',
template: `<h1>Hello {{name}}</h1>`
})
export class AppComponent { name = 'Angular'; }

5
public/docs/_examples/quickstart/ts/app/app.module.1.ts → public/docs/_examples/setup/ts/app/app.module.ts
View File

@ -1,8 +1,11 @@
// #docregion
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
@NgModule({
imports: [ BrowserModule ]
imports: [ BrowserModule ],
declarations: [ AppComponent ],
bootstrap: [ AppComponent ]
})
export class AppModule { }

5
public/docs/_examples/setup/ts/app/main.ts Normal file
View File

@ -0,0 +1,5 @@
// #docregion
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app.module';
platformBrowserDynamic().bootstrapModule(AppModule);

0
public/docs/_examples/setup/ts/example-config.json Normal file
View File

31
public/docs/_examples/setup/ts/index.html Normal file
View File

@ -0,0 +1,31 @@
<!DOCTYPE html>
<!-- #docregion -->
<html>
<head>
<title>Hello Angular</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="styles.css">
<style>
body {color:#369;font-family: Arial,Helvetica,sans-serif;}
</style>
<!-- Polyfills for older browsers -->
<script src="node_modules/core-js/client/shim.min.js"></script>
<script src="node_modules/zone.js/dist/zone.js"></script>
<script src="node_modules/reflect-metadata/Reflect.js"></script>
<script src="node_modules/systemjs/dist/system.src.js"></script>
<script src="systemjs.config.js"></script>
<script>
System.import('app').catch(function(err){ console.error(err); });
</script>
</head>
<body>
<!-- #docregion my-app-->
<my-app><!-- content managed by Angular --></my-app>
<!-- #enddocregion my-app-->
</body>
</html>

11
public/docs/_examples/setup/ts/plnkr.json Normal file
View File

@ -0,0 +1,11 @@
{
"description": "QuickStart Setup",
"files": [
"app/app.component.ts",
"app/app.module.ts",
"app/main.ts",
"index.html"
],
"open": "app/app.component.ts",
"tags": ["quickstart setup"]
}

2
public/docs/js/latest/quickstart.jade
View File

@ -208,7 +208,7 @@ code-example(format="").
:marked
The `template` property holds the component's companion template.
A template is a form of HTML that tells Angular how to render a view.
Our template is a single line of HTML announcing "Hello Angular!".
Our template is a single line of HTML announcing "Hello Angular".
Now we need something to tell Angular to load this component.

4
public/docs/ts/latest/_data.json
View File

@ -19,8 +19,8 @@
"icon": "query-builder",
"title": "Quickstart",
"subtitle": "TypeScript",
"description": "Get up and running with Angular",
"banner": "This QuickStart guide demonstrates how to build and run a simple Angular application."
"description": "Discover Angular",
"banner": "Discover Angular in a live-coding environment."
},
"tutorial": {

2
public/docs/ts/latest/cli-quickstart.jade
View File

@ -199,7 +199,7 @@ h3#component-decorator @Component decorator
+makeExample('src/app/cli-quickstart.component.html', null, 'src/app/cli-quickstart.component.html')(format='.')
:marked
The `{{title}}` is an _interpolation_ binding that causes Angular to display the component's
`title` property. After out edit, Angular displays "Hello Angular!".
`title` property. After out edit, Angular displays "Hello Angular".
We'll learn more about data binding as we read through the documentation.
The **styleUrls** array specifies the location(s) of the component's private CSS style file(s).

2
public/docs/ts/latest/cookbook/_data.json
View File

@ -2,7 +2,7 @@
"index": {
"title": "Cookbook",
"navTitle": "Overview",
"description": "A collection of recipes for common Angular application scenarios"
"intro": "A collection of recipes for common Angular application scenarios"
},
"aot-compiler": {

2
public/docs/ts/latest/cookbook/a1-a2-quick-reference.jade
View File

@ -137,7 +137,7 @@ table(width="100%")
in `main.ts`
and the application's root component (`AppComponent`) in `app.module.ts`.
For more information see [Quick Start](../quickstart.html).
For more information see the [Setup](../guide/setup.html) page.
tr(style=top)
td
:marked

3
public/docs/ts/latest/cookbook/aot-compiler.jade
View File

@ -91,8 +91,7 @@ a#compile
## Compile with AoT
### Prepare for offline compilation
Take the <a href='/docs/ts/latest/quickstart.html'>QuickStart</a> as a starting point.
Take the <a href='../guide/setup.html'>Setup</a> as a starting point.
A few minor changes to the lone `app.component` lead to these two class and html files:
+makeTabs(

7
public/docs/ts/latest/glossary.jade
View File

@ -103,10 +103,6 @@ block includes
:marked
The Angular [scoped packages](#scoped-package) each have a barrel named `index`.
That's why we can write this:
+makeExcerpt('quickstart/ts/app/app.component.ts', 'import', '')
.alert.is-important
:marked
Note that you can often achieve this using [Angular modules](#angular-module) instead.
@ -127,7 +123,8 @@ block includes
.l-sub-section
block bootstrap-defn-top
:marked
You launch an Angular application by "bootstrapping" it using the application root Angular module (`AppModule`). Bootstrapping identifies an application's top level "root" [component](#component), which is the first component that is loaded for the application. For more information, see [QuickStart](!{docsLatest}/quickstart.html).
You launch an Angular application by "bootstrapping" it using the application root Angular module (`AppModule`). Bootstrapping identifies an application's top level "root" [component](#component), which is the first component that is loaded for the application.
For more information, see the [Setup](!{docsLatest}/guide/setup.html).
:marked
You can bootstrap multiple apps in the same `index.html`, each with its own top level root.

34
public/docs/ts/latest/guide/_data.json
View File

@ -2,11 +2,29 @@
"index": {
"title": "Documentation Overview",
"navTitle": "Overview",
"description": "How to read and use this documentation",
"intro": "How to read and use this documentation",
"nextable": 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": {
"title": "Architecture Overview",
"navTitle": "Architecture",
@ -15,6 +33,15 @@
"basics": true
},
"appmodule": {
"title": "AppModule: the root module",
"navTitle": "The Root Module",
"intro": "Tell Angular how to construct and bootstrap the app in the root \"AppModule\".",
"nextable": true,
"basics": true
},
"displaying-data": {
"title": "Displaying Data",
"intro": "Property binding helps show app data in the UI.",
@ -136,6 +163,11 @@
"intro": "Developing for content security in Angular applications"
},
"setup-systemjs-anatomy": {
"title": "Setup Anatomy",
"intro": "Inside the local development environment for SystemJS"
},
"structural-directives": {
"title": "Structural Directives",
"intro": "Angular has a powerful template engine that lets us easily manipulate the DOM structure of our elements."

138
public/docs/ts/latest/guide/appmodule.jade Normal file
View File

@ -0,0 +1,138 @@
include ../_util-fns
:marked
An Angular module class describes how the application parts fit together.
Every application has at least one Angular module, the _root_ module
that you [bootstrap](#main) to launch the application.
You can call it anything you want. The conventional name is `AppModule`.
The [setup](setup.html) instructions produce a new project with the following minimal `AppModule`.
You'll evolve this module as your application grows.
+makeExample('setup/ts/app/app.module.ts','', 'app/app.module.ts')(format='.')
:marked
After the `import` statements, you come to a class adorned with the
**`@NgModule`** [_decorator_](glossary.html#decorator '"Decorator" explained').
The `@NgModule` decorator identifies `AppModule` as an Angular module class (also called an `NgModule` class).
`@NgModule` takes a _metadata_ object that tells Angular how to compile and launch the application.
* **_imports_** &mdash; the `BrowserModule` that this and every application needs to run in a browser.
* **_declarations_** &mdash; the application's lone component, which is also ...
* **_bootstrap_** &mdash; the _root_ component that Angular creates and inserts into the `index.html` host web page.
The [Angular Modules (NgModules)](ngmodule.html) guide dives deeply into the details of Angular modules.
All you need to know at the moment is a few basics about these three properties.
a#imports
:marked
### The _imports_ array
Angular modules are a way to consolidate features that belong together into discrete units.
Many features of Angular itself are organized as Angular modules.
HTTP services are in the `HttpModule`. The router is in the `RouterModule`.
Eventually you may create a feature module.
Add a module to the `imports` array when the application requires its features.
_This_ application, like most applications, executes in a browser.
Every application that executes in a browser needs the `BrowserModule` from `@angular/platform-browser`.
So every such application includes the `BrowserModule` in its _root_ `AppModule`'s `imports` array.
Other guide and cookbook pages will tell you when you need to add additional modules to this array.
.alert.is-important
:marked
**Only `NgModule` classes** go in the `imports` array. Don't put any other kind of class in `imports`.
.l-sub-section
:marked
Don't confuse the `import` statements at the top of the file with the Angular module's `imports` array.
They have different jobs.
The _JavaScript_ `import` statements give you access to symbols _exported_ by other files
so you can reference them within _this_ file.
They have nothing to do with Angular and Angular knows nothing about them.
The _module's_ `imports` array tells Angular about specific Angular modules &mdash; classes decorated with `@NgModule` &mdash;
that the application needs to function properly.
a#declarations
:marked
### The _declarations_ array
You must declare _every_ component in one (and _only one_) `NgModule` class.
You tell Angular which components belong to the `AppModule` by listing it in the module's `declarations` array.
As you create more components, you'll add them to `declarations`.
You'll learn to create two other kinds of classes &mdash;
[directives](attribute-directives.html) and [pipes](pipes.html) &mdash;
that you must also add to the `declarations` array.
.alert.is-important
:marked
**Only _declarables_** &mdash; _components_, _directives_ and _pipes_ &mdash; belong in the `declarations` array. &nbsp;
Don't put any other kind of class in `declarations`; _not_ `NgModule` classes, _not_ service classes, _not_ model classes.
a#bootstrap-array
:marked
### The _bootstrap_ array
You launch the application by [_bootstrapping_](#main) the root `AppModule`.
Among other things, the _bootstrapping_ process creates the component(s) listed in the `bootstrap` array
and inserts each one into the browser DOM.
Each bootstrapped component is the base of its own tree of components.
Inserting a bootstrapped component usually triggers a cascade of component creations that fill out that tree.
While you can put more than one component tree on a host web page, that's not typical.
Most applications have only one component tree and they bootstrap a single _root_ component.
You can call the one _root_ component anything you want but most developers call it `AppComponent`.
Which brings us to the _bootstrapping_ process itself.
a#main
l-main-section
:marked
## Bootstrap in _main.ts_
There are many ways to bootstrap an application.
The variations depend upon how you want to compile the application and where you want to run it.
In the beginning, you will compile the application dynamically with the _Just-in-Time (JiT)_ compiler
and you'll run it in a browser. You can learn about other options later.
The recommended place to bootstrap a JiT-compiled browser application is in a separate file
in the `app` folder named `app/main.ts`
+makeExample('setup/ts/app/main.ts','','app/main.ts')(format='.')
:marked
This code creates a browser platform for dynamic (JiT) compilation and
bootstrap's the `AppModule` described above.
The _bootstrapping_ process sets up the execution environment,
digs the _root_ `AppComponent` out of the module's `bootstrap` array, &nbsp;
creates an instance of the component and inserts it within the element tag identified by the component's `selector`.
The `AppComponent` selector &mdash; here and in most documentation samples &mdash; is `my-app`
so Angular looks for a `<my-app>` tag in the `index.html` like this one ...
+makeExample('setup/ts/index.html','my-app')(format='.')
:marked
... and displays the `AppComponent` there.
This file is very stable. Once you've set it up, you may never change it again.
a#quickstart-appmodule
l-main-section
:marked
## QuickStart's _AppModule_
Every Angular application must have a root `NgModule`, even the [QuickStart](../quickstart.html).
You didn't see it but it was there.
A script in the `index.html` generated a hidden `AppModule` and bootstrapped it for you
so you could focus on the `AppComponent` and discover the _essential Angular_ more quickly.
If you're feeling adventurous, add your own `AppModule` and `main.ts` to the
live code in the _QuickStart_ plunker.
Remove the following `<script>` tag from the `index.html` and see _your_ work in action.
+makeExample('quickstart/ts/index.html','autobootstrap','Remove this script tag from "index.html"')(format='.')

5
public/docs/ts/latest/guide/architecture.jade
View File

@ -5,7 +5,7 @@ block includes
:marked
Angular is a framework for building client applications in HTML and
either JavaScript or a language (like Dart or TypeScript) that compiles to JavaScript.
either JavaScript or a language like TypeScript that compiles to JavaScript.
block angular-parts
:marked
@ -56,7 +56,8 @@ figure
<br class="l-clear-both"><br>
:marked
Every Angular app has at least one module, the _root module_, conventionally named `AppModule`.
Every Angular app has at least one Angular module class, [the _root module_](appmodule.html "AppModule: the root module"),
conventionally named `AppModule`.
While the _root module_ may be the only module in a small application, most apps have many more
_feature modules_, each a cohesive block of code dedicated to an application domain,

8
public/docs/ts/latest/guide/attribute-directives.jade
View File

@ -28,8 +28,8 @@ a#directive-overview
1. Structural directives&mdash;change the DOM layout by adding and removing DOM elements.
1. Attribute directives&mdash;change the appearance or behavior of an element.
*Components* are the most common of the three directives. Read more about creating them
in step three of [QuickStart](../quickstart.html#root-component).
*Components* are the most common of the three directives.
You saw a component for the first time in the [QuickStart](../quickstart.html) example.
*Structural Directives* change the structure of the view. Two examples are [NgFor](template-syntax.html#ngFor) and [NgIf](template-syntax.html#ngIf)
in the [Template Syntax](template-syntax.html) page.
@ -64,9 +64,9 @@ a#write-directive
:marked
### Write the directive code
Create a new project folder (`attribute-directives`) and follow the steps in [QuickStart](../quickstart.html).
Follow the [setup](setup.html) instructions for creating a new project
named <span ngio-ex>attribute-directives</span>.
include ../_quickstart_repo
:marked
Create the following source file in the indicated folder with the following code:
+makeExample('app/highlight.directive.1.ts')

7
public/docs/ts/latest/guide/change-log.jade
View File

@ -5,6 +5,13 @@ block includes
The Angular documentation is a living document with continuous improvements.
This log calls attention to recent significant changes.
## QuickStart Rewrite (2016-11-18)
The QuickStart is completely rewritten so that it actually is quick.
It references a minimal "Hello Angular" app running in Plunker.
The new [Setup](setup.html) page tells you how to install a local development environment
by downloading (or cloning) the QuickStart github repository.
You are no longer asked to copy-and-paste code into setup files that were not explained anyway.
## Sync with Angular v.2.2.0 (2016-11-14)
Docs and code samples updated and tested with Angular v.2.2.0

12
public/docs/ts/latest/guide/displaying-data.jade
View File

@ -34,10 +34,9 @@ figure.image-display
is to bind the property name through interpolation.
With interpolation, you put the property name in the view template, enclosed in double curly braces: `{{myHero}}`.
To build an illustrative example, start by creating a new project folder called <ngio-ex path="displaying-data"></ngio-ex>
and following the steps in [QuickStart](../quickstart.html).
Follow the [setup](setup.html) instructions for creating a new project
named <ngio-ex path="displaying-data"></ngio-ex>.
:marked
Then modify the <ngio-ex path="app.component.ts"></ngio-ex> file by
changing the template and the body of the component.
@ -75,9 +74,8 @@ figure.image-display
Notice that you don't call **new** to create an instance of the `AppComponent` class.
Angular is creating an instance for you. How?
The CSS `selector` in the `@Component` !{_decorator} specifies an element named `my-app`.
Remember back in [QuickStart](../quickstart.html) that you added the `<my-app>`
element to the body of your `index.html` file:
The CSS `selector` in the `@Component` !{_decorator} specifies an element named `<my-app>`.
That element is a placeholder in the body of your `index.html` file:
+makeExcerpt('index.html', 'body')
@ -273,4 +271,4 @@ block final-code
displaying-data/ts/app/app.module.ts,
displaying-data/ts/app/main.ts`,
'final,,,',
'app/app.component.ts, app/hero.ts, app.module.ts, main.ts')
'app/app.component.ts, app/hero.ts, app.module.ts, main.ts')

5
public/docs/ts/latest/guide/forms.jade
View File

@ -85,10 +85,9 @@ figure.image-display
:marked
## Setup
Create a new project folder (`angular-forms`) and follow the steps in the [QuickStart](../quickstart.html).
Follow the [setup](setup.html) instructions for creating a new project
named <span ngio-ex>angular-forms</span>.
include ../_quickstart_repo
:marked
## Create the Hero Model Class
As users enter form data, we capture their changes and update an instance of a model.

103
public/docs/ts/latest/guide/index.jade
View File

@ -1,20 +1,6 @@
block includes
include ../_util-fns
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 guideData = public.docs[__lang].latest.guide._data;
- var advancedLandingPage = '';
@ -22,6 +8,19 @@ block js-alert
- if (!guideData[page].basics && !guideData[page].hide) { advancedLandingPage = page; break; }
- }
- 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"
table(width="100%")
col(width="15%")
@ -30,19 +29,22 @@ table(width="100%")
td <b><a href="../quickstart.html">QuickStart</a></b>
td
:marked
The foundation for every page and sample in this documentation.
A first taste of Angular with zero installation.
Run "Hello World" in an online code editor and start playing with live code.
tr(style=top)
td <b><a href="./">Guide</a></b>
td <b>Guide</b>
td
: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)
td <b><a href="../api">API Reference</a></b>
td <b><a href="../api/">API Reference</a></b>
td
:marked
Authoritative details about each member of the Angular libraries.
Authoritative details about each of the Angular libraries.
tr(style=top)
td <b><a href="../tutorial">Tutorial</a></b>
td <b><a href="../tutorial/">Tutorial</a></b>
td
:marked
A step-by-step, immersive approach to learning Angular that
@ -53,62 +55,35 @@ table(width="100%")
:marked
In-depth analysis of Angular features and development practices.
tr(style=top)
td <b><a href="../cookbook">Cookbook</a></b>
td <b><a href="../cookbook/">Cookbook</a></b>
td
:marked
Recipes for specific application challenges, mostly code snippets with a minimum of exposition.
:marked
## Learning path
You don't have to read the guide straight through. Most pages stand on their own.
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.
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}s.
## Code samples
Each page includes code snippets that you can reuse in your applications.
These snippets are excerpts from a sample application that accompanies the page.
Each page includes code snippets 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.
<p if-docs="ts">
The link launches a browser-based code editor where you can inspect, modify, save, and download the code.
</p>
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}.
The link launches a browser-based, code editor where you can inspect, modify, save, and download the code.
## Reference pages
- The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
- 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.
* The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
* 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.
* 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.
- Use the [Angular GitHub repo](!{_ngRepoURL}) to report issues with **Angular** itself.
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="!{_ngRepoURL}" target="_blank" title="angular source on github">Angular Github repository</a> to report issues with **Angular** itself.

43
public/docs/ts/latest/guide/learning-angular.jade Normal file
View File

@ -0,0 +1,43 @@
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.
1. [The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application.
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.

13
public/docs/ts/latest/guide/ngmodule.jade
View File

@ -12,10 +12,13 @@ block includes
It identifies the module's _own_ components, directives and pipes,
making some of them public so external components can use them.
It may add service providers to the application dependency injectors.
And there are more options covered here.
And there are many more options covered here.
This page explains how to **create** `NgModule` classes and how to load them,
either immediately when the application launches or later, as needed, via the [Router](router.html).
[The Root Module](appmodule.html) page introduced Angular Modules and the essentials
of creating and maintaining a single _root_ `AppModule` for the entire application.
Read that first.
This page goes into much greater depth as this extensive table of contents reveals.
## Table of Contents
* [Angular modularity](#angular-modularity "Add structure to the app with NgModule")
@ -102,8 +105,8 @@ a#root-module
Every Angular app has a **root module** class.
By convention it's a class called `AppModule` in a file named `app.module.ts`.
This `AppModule` is about as minimal as it gets:
+makeExample('ngmodule/ts/app/app.module.0.ts', '', 'app/app.module.ts (minimal)')(format=".")
The `AppModule` from the [_QuickStart seed_](setup.html) is about as minimal as it gets:
+makeExample('setup/ts/app/app.module.ts', '', 'app/app.module.ts (minimal)')(format=".")
:marked
The `@NgModule` decorator defines the metadata for the module.
We'll take an intuitive approach to understanding the metadata and fill in details as we go.

5
public/docs/ts/latest/guide/npm-packages.jade
View File

@ -18,9 +18,8 @@ include ../_util-fns
:marked
We recommend a comprehensive starter-set of packages as specified in the `dependencies` and `devDependencies`
sections of the QuickStart
<a href="https://docs.npmjs.com/files/package.json" target="_blank">package.json</a> file:
+makeJson('quickstart/ts/package.1.json',{ paths: 'dependencies, devDependencies'}, 'package.json (dependencies)')(format=".")
sections of the <a href="https://docs.npmjs.com/files/package.json" target="_blank">package.json</a> file
installed as described during [Setup](setup.html).
:marked
You can use other packages but we recommend *this particular set* to start with because (a) they work well together and
(b) they include everything you'll need to build and run the sample applications in this series.

154
public/docs/ts/latest/guide/setup-systemjs-anatomy.jade Normal file
View File

@ -0,0 +1,154 @@
block includes
include ../_util-fns
:marked
The documentation [setup](setup.html) procedures install a _lot_ of files,
Most of them can be safely ignored.
Application files _inside the_ **`app/`** and **`e2e/`** folders matter most to developers.
Files _outside_ those folders condition the development environment.
They rarely change and you may never view or modify them.
If you do, this page can help you understand their purpose.
style td, th {vertical-align: top}
table(width="100%")
col(width="10%")
col(width="90%")
tr
th File
th Purpose
tr
td <code>app/...</code>
td
:marked
Your Angular application files.
Ships with the "Hello Angular" sample's
`AppComponent`, `AppModule`, a component unit test (`app.component.spec.ts`), and
the bootstrap file, `main.ts`.
tr
td <code>e2e/...</code>
td
:marked
_End-to-end_ (e2e) tests of your application,
written in Jasmine and run by the
<a href="http://www.protractortest.org/" target="_blank" title="Protractor: end-to-end testing for Angular">protractor</a>
e2e test runner.
Initialized with an e2e test for the "Hello Angular" sample.
tr
td <code>node_modules/...</code>
td
:marked
The _npm_ packages installed with the `npm install` command.
tr
td
code.
.editorconfig<br>
.git/...<br>
.gitignore<br>
.travis.yml
td
:marked
Tooling configuration files and folders.
Ignore them until you have a compelling reason to do otherwise.
tr
td <code>CHANGELOG.md</code>
td
:marked
The history of changes to the _QuickStart_ repository.
Delete or ignore.
tr
td <code>favicon.ico</code>
td
:marked
The application icon that appears in the browser tab.
tr
td <code>index.html</code>
td
:marked
The application host page.
It loads a few essential scripts in a prescribed order.
Then it boots the application, placing the root `AppComponent`
in the custom `<my-app>` body tag.
The same `index.html` satisfies all documentation application samples.
tr
td <code>karma.conf.js</code>
td
:marked
Configuration for the <a href="https://karma-runner.github.io/1.0/index.html" target="_blank" title="Karma unit test runner">karma</a>
test runner described in the [Testing](testing.html) guide.
tr
td <code>karma-test-shim.js</code>
td
:marked
Script to run <a href="https://karma-runner.github.io/1.0/index.html" target="_blank" title="Karma unit test runner">karma</a>
with SystemJS as described in the [Testing](testing.html) guide.
tr
td <code>LICENSE</code>
td
:marked
The open source MIT license to use this setup code in your application.
tr
td <code>package.json</code>
td
:marked
Identifies `npm `package dependencies for the project.
Contains command scripts for running the application,
running tests, and more. Enter `npm run` for a listing.
<a href="https://github.com/angular/quickstart/blob/master/README.md#npm-scripts"
target="_blank" title="npm scripts for Angular documentation samples">Read more</a> about them.
tr
td <code>protractor.config.js</code>
td
:marked
Configuration for the
<a href="http://www.protractortest.org/" target="_blank" title="Protractor: end-to-end testing for Angular">protractor</a>
_end-to-end_ (e2e) test runner.
tr
td <code>README.md</code>
td
:marked
Instruction for using this git repository in your project.
Worth reading before deleting.
tr
td <code>styles.css</code>
td
:marked
Global styles for the application. Initialized with an `<h1>` style for the QuickStart demo.
tr
td <code>systemjs<br>.config.js</code>
td
:marked
Tells the **SystemJS** module loader where to find modules
referenced in JavaScript `import` statements such as
code-example(language="ts").
import { Component } from '@angular/core;
:marked
Don't touch this file unless you are fully versed in SystemJS configuration.
tr
td <code>systemjs<br>.config.extras.js</code>
td
:marked
Optional extra SystemJS configuration.
A way to add SystemJS mappings, such as for appliation _barrels_,
without changing the original `system.config.js`.
tr
td <code>tsconfig.json</code>
td
:marked
Tells the TypeScript compiler how to transpile TypeScript source files
into JavaScript files that run in all modern browsers.
tr
td <code>tslint.json</code>
td
:marked
The `npm` installed TypeScript linter inspects your TypeScript code
and complains when you violate one of its rules.
This file defines linting rules favored by the
[Angular style guide](style-guide.html) and by the authors of the documentation.

164
public/docs/ts/latest/guide/setup.jade Normal file
View File

@ -0,0 +1,164 @@
block includes
include ../_util-fns
a#develop-locally
:marked
## Setup a local development environment
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.
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").
Make sure you have [node and npm installed](#install-node "What if you don't have node?").
Then ...
1. Create a project folder (you can call it <span ngio-ex>quickstart</span> 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 the _npm_ packages](#install-node "What if you don't have node?").
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 https://github.com/angular/quickstart.git quickstart
cd quickstart
npm install
npm start
a#download
:marked
### Download
<a href="https://github.com/angular/quickstart/archive/master.zip" 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
:marked
## What's in the QuickStart seed?
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").
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 three 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 <code>app.component.ts</code>
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
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 <code>main.ts</code>
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-node
.l-main-section
:marked
## Appendix: _node_ and _npm_
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.
a#why-locally
.l-main-section
:marked
## Appdendix: 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).

5
public/docs/ts/latest/guide/template-syntax.jade
View File

@ -42,10 +42,11 @@ block includes
.l-main-section
:marked
## HTML
HTML is the language of the Angular template. Our [QuickStart](../quickstart.html) application has a template that is pure HTML:
HTML is the language of the Angular template.
The [QuickStart](../quickstart.html) application has a template that is pure HTML:
code-example(language="html" escape="html").
<h1>My First Angular App</h1>
<h1>Hello Angular</h1>
:marked
Almost all HTML syntax is valid template syntax. The `<script>` element is a notable exception; it is forbidden, eliminating the risk of script injection attacks. (In practice, `<script>` is simply ignored.)

12
public/docs/ts/latest/guide/testing.jade
View File

@ -169,8 +169,7 @@ table(width="100%")
A bare minimum of discussion plus the downloadable source code must suffice for now.
There are two fast paths to getting started.
1. Start a new project following the instructions in the
[QuickStart github repository](https://github.com/angular/quickstart/blob/master/README.md).
1. Start a new project following the instructions in [Setup](setup.html).
1. Start a new project with the
[Angular CLI](https://github.com/angular/angular-cli/blob/master/README.md).
@ -180,13 +179,12 @@ table(width="100%")
Their artifacts and procedures differ slightly but their essentials are the same
and there are no differences in the test code.
In this chapter, the application and its tests are based on the QuickStart repo.
In this chapter, the application and its tests are based on the documentation setup.
.alert.is-helpful
:marked
If your application was based on the QuickStart repository,
If your application was based on the [Setup](setup.html) instructions,
you can skip the rest of this section and get on with your first test.
The QuickStart repo provides all necessary setup.
#setup-files
:marked
@ -225,7 +223,7 @@ table(width="100%")
[SystemJS](https://github.com/systemjs/systemjs/blob/master/README.md)
loads the application and test files.
This script tells SystemJS where to find those files and how to load them.
It's the same version of `systemjs.config.js` used by QuickStart-based applications.
It's the same version of `systemjs.config.js` used by Setup-based applications.
tr
td(style="vertical-align: top") <code>systemjs.config.extras.js</code>
td
@ -282,7 +280,7 @@ code-example(format="." language="bash").
Both processes watch pertinent files, write messages to the console, and re-run when they detect changes.
.l-sub-section
:marked
The QuickStart development path defined the `test` command in the `scripts` section of npm's `package.json`.
The documentation setup defines the `test` command in the `scripts` section of npm's `package.json`.
The Angular CLI has different commands to do the same thing. Adjust accordingly.
:marked
After a few moments, karma opens a browser and starts writing to the console.

15
public/docs/ts/latest/guide/typescript-configuration.jade
View File

@ -23,8 +23,8 @@ a(id="tsconfig")
For details about `tsconfig.json`, see the official
[TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
:marked
We created the following `tsconfig.json` for [QuickStart](../quickstart.html):
+makeJson('quickstart/ts/tsconfig.1.json', null, 'tsconfig.json')(format=".")
We created the following `tsconfig.json` during [Setup](setup.html):
+makeJson('quickstart/ts/tsconfig.json', null, 'tsconfig.json')(format=".")
:marked
This file contains options and flags that are essential for Angular applications.
@ -36,11 +36,10 @@ a(id="tsconfig")
But your choice now can make a difference in larger projects, so it merits discussion.
When the `noImplicitAny` flag is `false` (the default), and if
the compiler cannot infer the variable type based on how it's used, the compiler silently defaults the type to `any`. That's what is meant by *implicit `any`*.
In the QuickStart exercise, the `noImplicitAny` flag is initialized to `false`
to make learning TypeScript development easier.
the compiler cannot infer the variable type based on how it's used,
the compiler silently defaults the type to `any`. That's what is meant by *implicit `any`*.
The documentation setup sets the `noImplicitAny` flag to `true`.
When the `noImplicitAny` flag is `true` and the TypeScript compiler cannot infer
the type, it still generates the JavaScript files, but it also **reports an error**.
Many seasoned developers prefer this stricter setting because type checking catches more
@ -48,12 +47,14 @@ a(id="tsconfig")
You can set a variable's type to `any` even when the `noImplicitAny` flag is `true`.
If you set the `noImplicitAny` flag to `true`, you may get *implicit index errors* as well.
When the `noImplicitAny` flag is `true, you may get *implicit index errors* as well.
Most developers feel that *this particular error* is more annoying than helpful.
You can suppress them with the following additional flag:
code-example(format=".").
"suppressImplicitAnyIndexErrors":true
:marked
The documentation setup sets this flag to `true` as well.
a(id="typings")
.l-main-section

14
public/docs/ts/latest/guide/upgrade.jade
View File

@ -433,7 +433,7 @@ figure.image-display
:marked
Now introduce Angular 2 to the project. Inspired by instructions in
[the QuickStart](../quickstart.html), you can selectively copy in material from the
[the Setup](setup.html), you can selectively copy in material from the
<a href="https://github.com/angular/quickstart" target="_blank">QuickStart github repository</a>.
Next, create an `app.module.ts` file and add the following `NgModule` class:
@ -892,7 +892,7 @@ code-example(format="").
:marked
We should also configure the TypeScript compiler so that it can understand our
project. We'll add a `tsconfig.json` file to the project directory, just like we do
in the [Quickstart](../quickstart.html). It instructs the TypeScript compiler how
in the documentation [setup](setup.html). It instructs the TypeScript compiler how
to interpret our source files.
+makeJson('upgrade-phonecat-1-typescript/ts/tsconfig.ng1.json', null, 'tsconfig.json')
@ -1020,8 +1020,9 @@ code-example(format="").
.alert.is-important The project also contains some animations, which we are not yet upgrading in this version of the guide. This will change in a later release.
:marked
Let's install Angular 2 into the project, along with the SystemJS module loader. Take a look into the
[Quickstart](../quickstart.html) guide and get the following configurations from there:
Let's install Angular 2 into the project, along with the SystemJS module loader.
Take a look at the results of the [Setup](setup.html) instructions
and get the following configurations from there:
* Add Angular 2 and the other new dependencies to `package.json`
* The SystemJS configuration file `systemjs.config.js` to the project root directory.
@ -1059,8 +1060,9 @@ code-example(format="").
+makeExample('upgrade-phonecat-2-hybrid/ts/index.html', 'ng2', 'index.html')
:marked
In the `systemjs.config.js` file we got from the Quickstart we also need to make a couple
of adjustments because of our project structure. We want to point the browser to the project
We also need to make a couple of adjustments
to the `systemjs.config.js` file installed during [setup](setup.html).
We want to point the browser to the project
root when loading things through SystemJS, instead of using the `<base>` URL:
+makeExample('upgrade-phonecat-2-hybrid/ts/systemjs.config.1.js', 'paths', 'systemjs.config.js')

416
public/docs/ts/latest/quickstart.jade
View File

@ -1,384 +1,56 @@
block includes
include _util-fns
- var _Install = 'Install'
- 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
- var step = _stepInit
+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.
include _util-fns
:marked
The QuickStart application has the structure of a real-world Angular application and
displays the simple message:
The **QuickStart playground** is the easiest way to discover Angular.
You don't need to install anything.
Just click the image below, launch the live-coding environment, and start entering code.
figure.image-display
img(src='/resources/images/devguide/quickstart/hello-angular.png' alt="Output of QuickStart app")
<live-example embedded img="devguide/quickstart/quickstart-plnkr-big.png"><live-example>
The QuickStart displays a super-simple Angular component, written in [TypeScript](#typescript):
+makeExample('app/app.component.ts','','app/app.component.ts')(format='.')
:marked
**Try it out**. Here's a link to a <live-example></live-example>.
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.
+ifDocsFor('ts')
Every component begins with a `@Component` [_decorator_](glossary.html#decorator '"Decorator" explained') function
that takes a _metadata_ object. The metadata describe 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.
Change the component class's `name` property from `'Angular'` to `'World'` and see what happens.
Binding is one of many Angular features you'll discover in this documentation.
.l-sub-section
:marked
You can also <a href="!{_quickstartSrcURL}" target="_blank">
clone the entire QuickStart application</a> from GitHub.
### Next step
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.
This QuickStart playground is fine for exploring Angular
but you won't develop a real application there.
You'll want to develop locally on your own machine.
Visit the [**setup guide**](guide/setup.html "Install Angular for local development") to learn how.
.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'
a#typescript
: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)
## TypeScript
This example is written in <a href="http://www.typescriptlang.org/" target="_blank" title="TypeScript">TypeScript</a>,
a typed super-set of the latest JavaScript.
TypeScript compiles into JavaScript that runs on any modern browser.
Most developers find it delightful which is why most Angular developers write applications in TypeScript.
You can write your application in
[other versions of JavaScript](cookbook/ts-to-js.html "TypeScript to JavaScript")
if you prefer.
//
[Dart](../../dart/latest)
<a href="https://github.com/angular/dart/latest" target="_blank" title="Dart">Dart</a> if you prefer.
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
header SystemJS or Webpack?
p.
Although we use SystemJS for illustrative purposes here, it's only one option for loading
modules. Use the module loader that you prefer. For Webpack and Angular, see <a
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>.
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&mdash;in red&mdash;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&mdash;a *view*&mdash;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
[Read more](https://github.com/angular/quickstart/blob/master/README.md#npm-scripts) about
other useful npm scripts included in this example's `package.json`.
:marked
That command runs the following two parallel node processes:
* The TypeScript compiler in watch mode.
* 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)!

2
public/docs/ts/latest/tutorial/_data.json
View File

@ -2,7 +2,7 @@
"index": {
"title": "Tutorial: Tour of Heroes",
"navTitle": "Introduction",
"intro": "The Tour of Heroes tutorial takes us through the steps of creating an Angular application in TypeScript.",
"intro": "The Tour of Heroes tutorial takes you through the steps of creating an Angular application in TypeScript.",
"nextable": true
},
"toh-pt1": {

2
public/docs/ts/latest/tutorial/index.jade
View File

@ -79,5 +79,3 @@ figure.image-display
met in countless applications. Everything has a reason.
And we’ll meet many of the core fundamentals of Angular along the way.
[Let's get started!](./toh-pt1.html)

30
public/docs/ts/latest/tutorial/toh-pt1.jade
View File

@ -1,16 +1,12 @@
include ../_util-fns
:marked
Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends.
Run the <live-example></live-example> for this part.
Create a folder called `angular-tour-of-heroes` and follow the [QuickStart](../quickstart.html) steps
which provide the prerequisites, the folder structure, and the core files for our Tour of Heroes.
include ../_quickstart_repo
:marked
We should have the following structure:
## Setup to develop locally
Real application development takes place in a local development environment like your machine.
Follow the [setup](../guide/setup.html) instructions for creating a new project
named <ngio-ex path="angular-tour-of-heroes"></ngio-ex>
after which the file structure should look like this:
.filetree
.file angular-tour-of-heroes
@ -27,10 +23,14 @@ include ../_quickstart_repo
.file systemjs.config.js
.file tsconfig.json
:marked
## Keep the app transpiling and running
We want to start the TypeScript compiler, have it watch for changes, and start our server. We'll do this by typing
When we're done with this first episode, the app runs like this <live-example></live-example>.
code-example(language="bash").
## Keep the app transpiling and running
We want to start the TypeScript compiler, have it watch for changes, and start our server.
Do this by entering the following command in the terminal window.
code-example(language="sh" class="code-shell").
npm start
:marked
@ -42,13 +42,13 @@ code-example(language="bash").
## Show our Hero
We want to display Hero data in our app
Let's add two properties to our `AppComponent`, a `title` property for the application name and a `hero` property
Update the `AppComponent` so it has two properties: &nbsp; a `title` property for the application name and a `hero` property
for a hero named "Windstorm".
+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'app-component-1', 'app.component.ts (AppComponent class)')(format=".")
:marked
Now we update the template in the `@Component` decoration with data bindings to these new properties.
Now update the template in the `@Component` decoration with data bindings to these new properties.
+makeExample('toh-1/ts-snippets/app.component.snippets.pt1.ts', 'show-hero')

4
public/docs/ts/latest/tutorial/toh-pt5.jade
View File

@ -886,9 +886,7 @@ block css-files
We can also create styles at the *application level* outside of any component.
Our designers provided some basic styles to apply to elements across the entire app.
These correspond to the full set of master styles that we
introduced earlier (see
[QuickStart, "Add some style"](../quickstart.html#add-some-style)).
These correspond to the full set of master styles that we installed earlier during [setup](../setup.html).
Here is an excerpt:
+makeExcerpt('styles.css (excerpt)', 'toh')

7
public/docs/ts/latest/tutorial/toh-pt6.jade
View File

@ -618,3 +618,10 @@ block file-summary
hero-search.component.css,
rxjs-extensions.ts`
)
.l-sub-section
:marked
### Next Step
Return to the [learning path](../guide/learning-angular.html#architecture) where
you can read about the concepts and practices you discovered in this tutorial.

BIN
public/resources/images/devguide/intro/people.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 674 KiB

After

Width:  |  Height:  |  Size: 18 KiB

BIN
public/resources/images/devguide/quickstart/hello-angular.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.0 KiB

After

Width:  |  Height:  |  Size: 4.0 KiB

BIN
public/resources/images/devguide/quickstart/quickstart-plnkr-big.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
public/resources/images/devguide/quickstart/quickstart-plnkr.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

12
tools/plunker-builder/builder.js
View File

@ -54,11 +54,13 @@ class PlunkerBuilder {
this.copyrights.html = `${pad}<!-- \n${copyright}\n-->`;
}
// config has
// files: [] - optional array of globs - defaults to all js, ts, html, json, css and md files (with certain files removed)
// description: optional string - description of this plunker - defaults to the title in the index.html page.
// tags: [] - optional array of strings
// main: string - filename of what will become index.html in the plunker - defaults to index.html
// Build plunker from JSON configuration file (e.g., plnkr.json):
// all properties are optional
// files: string[] - array of globs - defaults to all js, ts, html, json, css and md files (with certain files removed)
// description: string - description of this plunker - defaults to the title in the index.html page.
// tags: string[] - optional array of plunker tags (for searchability)
// main: string - name of file that will become index.html in the plunker - defaults to index.html
// open: string - name of file to display within the plunker as in "open": "app/app.module.ts"
_buildPlunkerFrom(configFileName) {
// replace ending 'plnkr.json' with 'plnkr.no-link.html' to create output file name;
var outputFileName = `${this.options.plunkerFileName}.no-link.html`;

2
tools/plunker-builder/indexHtmlTranslator.js
View File

@ -21,7 +21,7 @@ var _rxRules = {
},
systemjs: {
from: /<script src="systemjs.config.js"><\/script>/,
to: '<script src="https://cdn.rawgit.com/angular/angular.io/f2daab7/public/docs/_examples/_boilerplate/systemjs.config.web.js"></script>'
to: '<script src="https://cdn.rawgit.com/angular/angular.io/b3c65a9/public/docs/_examples/_boilerplate/systemjs.config.web.js"></script>'
},
// Clear script like this:
// <script>