2d3836c8c1
* docs(cache): misc adjustments for Dart Dart cache adjustments: - Add guide/index (it was being inherited directly from latest before). - Add proper cache of `_quickstart_repo.jade` (it used to be just an include). Also: - In `_quickstart_repo.jade` use variable set to URL of repo. - Fix newly added link to Quickstart in guide/index.jade. * dart/displaying-data: just use TS's _quickstart_repo
211 lines
7.4 KiB
Plaintext
211 lines
7.4 KiB
Plaintext
extends ../../ts/_cache/quickstart.jade
|
|
|
|
block includes
|
|
include _util-fns
|
|
- var _Install = 'Get'
|
|
- var _prereq = 'the Dart SDK'
|
|
- var _angular_browser_uri = 'angular2/platform/browser.dart'
|
|
- var _angular_core_uri = 'angular2/core.dart'
|
|
- var _stepInit = 3
|
|
|
|
block setup-tooling
|
|
:marked
|
|
Install the **[Dart SDK](https://www.dartlang.org/downloads/)**,
|
|
if not already on your machine, and any tools you like to use with Dart.
|
|
The Dart SDK includes tools such as **[pub][pub]**, the Dart package manager.
|
|
If you don't have a favorite Dart editor already, try
|
|
[WebStorm][WS], which comes with a Dart plugin.
|
|
You can also download [Dart plugins for other IDEs and editors][DT].
|
|
|
|
[WS]: https://confluence.jetbrains.com/display/WI/Getting+started+with+Dart
|
|
[DT]: https://www.dartlang.org/tools/
|
|
[pub]: https://www.dartlang.org/tools/pub/
|
|
|
|
block package-and-config-files
|
|
:marked
|
|
In the project folder just created, create a file named
|
|
**[pubspec.yaml][pubspec]** with the code below.
|
|
This pubspec must specify the **angular2** and **browser**
|
|
packages as dependencies, as well as the `angular2` transformer.
|
|
It can also specify other packages and transformers for the app to use,
|
|
such as [dart_to_js_script_rewriter](https://pub.dartlang.org/packages/dart_to_js_script_rewriter).
|
|
|
|
[pubspec]: https://www.dartlang.org/tools/pub/pubspec.html
|
|
|
|
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml')
|
|
|
|
block install-packages
|
|
:marked
|
|
From the project folder, run `pub get` to install the angular2 and browser
|
|
packages (along with the packages they depend on).
|
|
|
|
code-example(language="sh" class="code-shell").
|
|
pub get
|
|
|
|
block create-your-app
|
|
:marked
|
|
Let's create a folder to hold our application and add a super-simple Angular component.
|
|
|
|
block annotation-fields
|
|
:marked
|
|
The call to the `@Component` constructor has two
|
|
named parameters, `selector` and `template`.
|
|
|
|
block create-main
|
|
p.
|
|
Now we need something to tell Angular to load the root component.
|
|
Create:
|
|
ul
|
|
li a #[b folder named #[code web]]
|
|
li a <b>file named #[code #[+adjExPath('app/main.ts')]]</b> with the following content:
|
|
|
|
block commentary-on-index-html
|
|
:marked
|
|
Note the `<my-app>` tag in the `<body>`, this is *where your app lives!*
|
|
|
|
block run-app
|
|
p.
|
|
We have a few options for running our app.
|
|
One is to launch a local HTTP server
|
|
and then view the app in
|
|
<a href="https://www.dartlang.org/tools/dartium/">Dartium</a>.
|
|
We can use any web server, such as WebStorm's server
|
|
or Python's SimpleHTTPServer.
|
|
p.
|
|
Another option is to build and serve the app using <code>pub serve</code>,
|
|
and then run it by visiting <b><code>http://localhost:8080</code></b> in any modern browser.
|
|
Pub serve generates JavaScript on the fly,
|
|
which can take a while when first visiting the page.
|
|
Pub serve also runs in <b><i>watch mode</i></b>, and will recompile and subsequently serve
|
|
any changed assets.
|
|
p.
|
|
Once the app is running, the browser window should show the following:
|
|
|
|
block build-app
|
|
//- Remove details of building from QS for now. (It is too early for these details.)
|
|
if false
|
|
.alert.is-important
|
|
:marked
|
|
If you don't see **Hello Angular!**, make sure you've entered all the code correctly,
|
|
in the [proper folders](#wrap-up),
|
|
and run `pub get`.
|
|
|
|
.l-verbose-section#section-angular-run-app
|
|
:marked
|
|
### Building the app (generating JavaScript)
|
|
|
|
Before deploying the app, we need to generate JavaScript files.
|
|
The `pub build` command makes that easy.
|
|
|
|
code-example(language="sh" class="code-shell").
|
|
> <span class="blk">pub build</span>
|
|
Loading source assets...
|
|
|
|
:marked
|
|
The generated JavaScript appears, along with supporting files,
|
|
under a directory named `build`.
|
|
|
|
#angular_transformer
|
|
h4 Using the Angular transformer
|
|
|
|
p.
|
|
When generating JavaScript for an Angular app,
|
|
be sure to use the Angular transformer.
|
|
It analyzes the Dart code,
|
|
converting reflection-using code to static code
|
|
that Dart's build tools can compile to faster, smaller JavaScript.
|
|
The highlighted lines in <code>pubspec.yaml</code>
|
|
configure the Angular transformer:
|
|
|
|
- var stylePattern = { otl: /(transformers:)|(- angular2:)|(entry_points.*$)/gm };
|
|
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
|
|
|
|
p.
|
|
The <code>entry_points</code> item
|
|
identifies the Dart file in our app
|
|
that has a <code>main()</code> function.
|
|
For more information, see the
|
|
<a href="https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer">Angular
|
|
transformer wiki page</a>.
|
|
|
|
.l-sub-section#performance
|
|
h3 Performance, the transformer, and Angular libraries
|
|
p.
|
|
When an app imports <code>bootstrap.dart</code>,
|
|
it also gets <code>dart:mirrors</code>,
|
|
a reflection library that
|
|
causes performance problems when compiled to JavaScript.
|
|
Don't worry,
|
|
the Angular transformer converts the app's entry points
|
|
(<code>entry_points</code> in <code>pubspec.yaml</code>)
|
|
so that they don't use mirrors.
|
|
|
|
#dart_to_js_script_rewriter
|
|
h4 Using dart_to_js_script_rewriter
|
|
|
|
:marked
|
|
To improve the app's performance, convert the
|
|
HTML file to directly include the generated JavaScript;
|
|
one way to do that is with `dart_to_js_script_rewriter`.
|
|
To use the rewriter, specify `dart_to_js_script_rewriter` in both
|
|
the `dependencies` and `transformers` sections of the pubspec.
|
|
|
|
- var stylePattern = { otl: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)|(dependencies:)|(transformers:)/gm };
|
|
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
|
|
|
|
.alert.is-important
|
|
:marked
|
|
The `dart_to_js_script_rewriter` transformer must be
|
|
**after** the `angular2` transformer in `pubspec.yaml`.
|
|
|
|
:marked
|
|
For more information, see the docs for
|
|
[dart_to_js_script_rewriter](https://pub.dartlang.org/packages/dart_to_js_script_rewriter).
|
|
|
|
block server-watching
|
|
:marked
|
|
To see the new version, just reload the page.
|
|
|
|
.alert.is-important
|
|
:marked
|
|
Be sure to terminate your local server once you stop working on this app.
|
|
|
|
block project-file-structure
|
|
.filetree
|
|
.file angular_quickstart
|
|
.children
|
|
.file lib
|
|
.children
|
|
.file app_component.dart
|
|
.file pubspec.yaml
|
|
.file web
|
|
.children
|
|
.file index.html
|
|
.file main.dart
|
|
.file styles.css
|
|
|
|
.l-verbose-section
|
|
:marked
|
|
This figure doesn't show generated files and directories.
|
|
For example, a `pubspec.lock` file
|
|
specifies versions and other identifying information for
|
|
the packages that our app depends on.
|
|
The `pub build` command creates a `build` directory
|
|
containing the JavaScript version of our app.
|
|
Pub, IDEs, and other tools often create
|
|
other directories and dotfiles.
|
|
|
|
block project-files
|
|
+makeTabs(`
|
|
quickstart/ts/app/app.component.ts,
|
|
quickstart/ts/app/main.ts,
|
|
quickstart/ts/index.html,
|
|
quickstart/dart/pubspec.yaml,
|
|
quickstart/ts/styles.css`,
|
|
',,,,quickstart',
|
|
`app/app.component.ts,
|
|
app/main.ts,
|
|
index.html,
|
|
pubspec.yaml,
|
|
styles.css (excerpt)`)
|