honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(quickstart): edit Dart & TS QuickStarts 

closes #1411
This commit is contained in:
Kathy Walrath 2016-05-16 17:10:19 -07:00
parent 6751f779d0
commit 2810218b88
2 changed files with 173 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
public/docs/dart/latest/quickstart.jade
View File

@ -13,8 +13,7 @@ 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 **[pub][pub]**, the Dart package manager, that we
will be using shortly.
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].
@ -28,15 +27,17 @@ block download-source
block package-and-config-files
:marked
In the project folder just created, put a file named
**[pubspec.yaml][pubspec]** in it.
As shown below, in `pubspec.yaml`, specify the angular2 and browser
packages as dependencies, as well as the angular2 transformer.
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).
Angular 2 is still changing, so provide an exact version: **2.0.0-beta.17**.
[pubspec]: https://www.dartlang.org/tools/pub/pubspec.html
+makeExample('quickstart/dart/pubspec.yaml', 'no-rewriter', 'pubspec.yaml')
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml')
block install-packages
:marked
@ -57,35 +58,34 @@ block create-main
Now we need something to tell Angular to load the root component.
Create:
ul
li a #[b folder named #[code web]], and inside it
li the file #[code #[+adjExPath('app/main.ts')]] with the following content:
li a #[b folder named #[code web]]
li a <b>file named #[code #[+adjExPath('app/main.ts')]]</b> with the following content:
block index-html-commentary-for-ts
//- N/A
block run-app
p.
You have a few options for running your app.
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>.
You can use whatever server you like, such as WebStorm's server
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 you first visit the page.
Pub serve also runs in <b><i>watch mode</i></b>, and will re-compile and subsequently serve
and changed assets.
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, you should see the following in your browser
window:
Once the app is running, the browser window should show the following:
block build-app
.alert.is-important
:marked
If you don't see that, make sure you've entered all the code correctly,
If you don't see **My First Angular 2 App**, make sure you've entered all the code correctly,
in the [proper folders](#wrap-up),
and run `pub get`.
@ -93,21 +93,8 @@ block build-app
h3#section-angular-run-app Building the app (generating JavaScript)
:marked
Before you can deploy your app, you need to generate JavaScript files.
Before deploying the app, we need to generate JavaScript files.
The `pub build` command makes that easy.
To improve your 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`.
Add the `dart_to_js_script_rewriter` package to your pubspec,
in both the `dependencies` and `transformers` sections.
- var stylePattern = { pnk: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)/gm, otl: /(dependencies:)|(transformers:)/g };
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
p.
Then compile your Dart code to JavaScript,
using <code>pub build</code>.
code-example(language="sh").
&gt; <span class="blk">pub build</span>
@ -115,11 +102,14 @@ block build-app
p.
The generated JavaScript appears, along with supporting files,
under the <code>build</code> directory.
under a directory named <code>build</code>.
h4#angular_transformer Using the Angular transformer
p.
When you generate JavaScript for an Angular app,
When generating JavaScript for an Angular app,
be sure to use the Angular transformer.
It analyzes your code,
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>
@ -130,7 +120,7 @@ block build-app
p.
The <code>entry_points</code> item
identifies the Dart file in your app
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
@ -139,29 +129,48 @@ block build-app
#performance.l-sub-section
h3 Performance, the transformer, and Angular 2 libraries
p.
When you import <code>bootstrap.dart</code>,
you also get <code>dart:mirrors</code>,
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 your entry points
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.
h4#dart_to_js_script_rewriter 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
Pub serve is watching and
should detect the change, recompile the Dart into JavaScript,
refresh the browser, and display the revised message.
It's a nifty way to develop an application!
To see the new version, just reload the page.
Ensure that you terminate the `pub serve` process once you are done.
.alert.is-important
:marked
Be sure to terminate the `pub serve` process once you stop working on this app.
block project-file-structure
.filetree
.file angular2-quickstart
.children
.file build ...
.file lib
.children
.file app_component.dart
@ -169,9 +178,20 @@ block project-file-structure
.file web
.children
.file index.html
.file main.ts
.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
+makeTabs(`
quickstart/ts/app/app.component.ts,

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

@ -32,13 +32,13 @@ figure.image-display
h1 Build this app!
:marked
- [Prerequisite](#prereq): install #{_prereq}
- [Step 1](#create-and-configure): create the app’s project folder and
- [Prerequisite](#prereq): Install #{_prereq}
- [Step 1](#create-and-configure): Create the app’s project folder and
define package dependencies and special project setup
- [Step 2](#root-component): create the app’s Angular root component
- [Step 3](#main): add `main.#{_docsFor}`, identifying the root component to Angular
- [Step 4](#index): add `index.html`, the web page that hosts the application
- [Step 5](#build-and-run): build and run the app
- [Step 2](#root-component): Create the app’s Angular root component
- [Step 3](#main): Add `main.#{_docsFor}`, identifying the root component to Angular
- [Step 4](#index): Add `index.html`, the web page that hosts the application
- [Step 5](#build-and-run): Build and run the app
- [Make some changes to the app](#make-some-changes)
- [Wrap up](#wrap-up)
@ -70,7 +70,7 @@ button(class="verbose on md-primary md-button md-ink-ripple", type="button", onc
Explanations have a thin border on the left like *this* block of text.
Click *Hide Explanations* to show only the instructions.
Click it again to see everything again.
Click *View Explanations* to see everything again.
.l-sub-section
:marked
@ -79,15 +79,15 @@ button(class="verbose on md-primary md-button md-ink-ripple", type="button", onc
Click the glyph on the right to copy code snippets to the clipboard ==>
.l-main-section
h2#create-and-configure Step 1: create and configure the project
h2#create-and-configure Step 1: Create and configure the project
- var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'package definition and configuration files'
:marked
In this step we:
* [(a) Create the project folder](#create-the-project-folder).
* [(b) Add #{_package_and_config_files}](#add-config-files).
* [(c) #{_Install} packages](#install-packages).
* [(a) Create the project folder](#create-the-project-folder)
* [(b) Add #{_package_and_config_files}](#add-config-files)
* [(c) #{_Install} packages](#install-packages)
h3 (a) Create the project folder
@ -150,8 +150,8 @@ block install-packages
There might be a few `npm WARN` messages along the way &mdash; and that is perfectly fine.
We often see an `npm WARN` message after a series of `gyp ERR!` messages.
Ignore them. A package may try to re-compile itself using `node-gyp`.
If the re-compile fails, the package recovers (typically with a pre-built version)
Ignore them. A package may try to recompile itself using `node-gyp`.
If the recompile fails, the package recovers (typically with a pre-built version)
and everything works.
Just make sure there are no `npm ERR!` messages at the end of `npm install`.
@ -180,7 +180,7 @@ block install-packages
* `npm run tsc` - runs the TypeScript compiler once
* `npm run tsc:w` - runs the TypeScript compiler in watch mode;
the process keeps running, awaiting changes to TypeScript files and re-compiling when it sees them
the process keeps running, awaiting changes to TypeScript files and recompiling when it sees them
* `npm run lite` - runs the <a href="https://www.npmjs.com/package/lite-server" target="_blank">lite-server</a>,
a light-weight, static file server with excellent support for Angular apps that use routing
@ -194,11 +194,11 @@ block install-packages
**We're all set.** Let's write some code.
.l-main-section
h2#root-component Step 2: our first angular component
h2#root-component Step 2: Our first Angular component
:marked
Let's create a folder to hold our application and add a super-simple Angular component.
**Create an *#{_appDir}* sub-folder** off the project root directory:
**Create #{_an} #{_appDir} subfolder** off the project root directory:
code-example.
mkdir #{_appDir}
@ -250,7 +250,7 @@ p.
We apply this function to the component class by prefixing the function with the
**@** symbol and invoking it with a metadata object, just above the class.
:marked
`@Component` is #{_a} **#{_decorator}** that allows us to associate *metadata* with the
`@Component` is #{_a} *#{_decorator}* that allows us to associate *metadata* with the
component class.
The metadata tells Angular how to create and use this component.
@ -290,7 +290,7 @@ p.
as we'll see when we create `main.ts`.
.l-main-section
h2#main Step 3: add #[code #[+adjExPath('main.ts')]]
h2#main Step 3: Add #[code #[+adjExPath('main.ts')]]
block create-main
p.
@ -337,15 +337,17 @@ block create-main
Let's make the small extra effort to do it *the right way*.
.l-main-section
h2#index Step 4: add #[code index.html]
h2#index Step 4: Add #[code index.html]
:marked
The `index.html` is the web page that hosts the application.
In the **#{_indexHtmlDir}** folder
create an`index.html` file and paste the following lines:
In the *#{_indexHtmlDir}* folder
create an `index.html` file and paste the following lines into it:
+makeExample('quickstart/ts/index.html', '', 'index.html')(format='.')
.l-verbose-section
:marked
The `index.html` file defines the web page that hosts the application.
block index-html-commentary-for-ts
:marked
The noteworthy sections of HTML are:
@ -426,15 +428,15 @@ h2#index Step 4: add #[code index.html]
* We see compiler warnings and errors that are hidden from us in the browser.
* Pre-compilation simpifies the module loading process and
* Precompilation simpifies the module loading process and
it's much easier to diagnose problems when this is a separate, external step.
* Pre-compilation means a faster user experience because the browser doesn't waste time compiling.
* Precompilation means a faster user experience because the browser doesn't waste time compiling.
* We iterate development faster because we only re-compile changed files.
* We iterate development faster because we only recompile changed files.
We notice the difference as soon as the app grows beyond a handful of files.
* Pre-compilation fits into a continuous integration process of build, test, deploy.
* Precompilation fits into a continuous integration process of build, test, deploy.
:marked
The `System.import` call tells SystemJS to import the `main` file
@ -445,25 +447,26 @@ h2#index Step 4: add #[code index.html]
All other modules are loaded upon request
either by an import statement or by Angular itself.
### *&lt;my-app&gt;*
a(id="my-app")
:marked
### *&lt;my-app&gt;*
When Angular calls the `bootstrap` function in `main.#{_docsFor}`, it reads the `AppComponent`
metadata, finds the `my-app` selector, locates an element tag named `my-app`,
and renders our application's view between those tags.
:marked
### Add some style
Styles aren't essential but they're nice and the `index.html` assumes we have
Styles aren't essential but they're nice, and `index.html` assumes we have
a stylesheet called `styles.css`.
Create a `styles.css` in the #{_indexHtmlDir} folder and start styling, perhaps with minimal
styles shown below. For the full set of master styles used by the documentation samples
see this master [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css).
Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, perhaps with the minimal
styles shown below. 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/styles.css).
+makeExcerpt('quickstart/ts/styles.1.css', '', 'styles.css')
.l-main-section
h2#build-and-run Step 5: build and run the app!
h2#build-and-run Step 5: Build and run the app!
block run-app
:marked
Open a terminal window and enter this command:
@ -478,7 +481,7 @@ block run-app
In a few moments, a browser tab should open and display
figure.image-display
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app")
:marked
**Great job!**
@ -502,7 +505,6 @@ block server-watching
.l-main-section
:marked
# Wrap up
## Final project structure and files
Our final project folder structure looks like this:
block project-file-structure
@ -522,7 +524,7 @@ block project-file-structure
.file tsconfig.json
.file typings.json
:marked
And here are the files:
Here are the file contents:
block project-files
+makeTabs(`