quickstart.jade

extends ../../ts/latest/quickstart.jade

block includes
  include _util-fns
  - var _Install = 'Get'
  - var _prereq = 'the Dart SDK'
  - var _angular_browser_uri = 'package:angular2/platform/browser.dart'
  - var _angular_core_uri = 'package:angular2/core.dart'

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 download-source
  // exclude this section from Dart

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).
    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', 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").
    &gt; <span class="blk">pub get</span>
    Resolving dependencies...

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 index-html-commentary-for-ts
  //- N/A

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
  .alert.is-important
    :marked
      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`.

  .l-verbose-section
    h3#section-angular-run-app Building the app (generating JavaScript)

    :marked
      Before deploying the app, we need to generate JavaScript files.
      The `pub build` command makes that easy.

    code-example(language="sh").
      &gt; <span class="blk">pub build</span>
      Loading source assets...

    p.
      The generated JavaScript appears, along with supporting files,
      under a directory named <code>build</code>.

    h4#angular_transformer 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>.

    #performance.l-sub-section
      h3 Performance, the transformer, and Angular 2 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.

    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
    To see the new version, just reload the page.

  .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 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.1.css`
    ,null,
    `app/app.component.ts,
    app/main.ts,
    index.html,
    pubspec.yaml,
    styles.css`)

block what-next-ts-overhead
  //- N/A