angular-cn/public/docs/dart/latest/quickstart.jade

include ../../../_includes/_util-fns

:marked
  Let's start from zero and build a super simple Angular 2 application in Dart.

.callout.is-helpful
  header Don't want Dart?
  :marked
    Although we're getting started in Dart, you can also write Angular 2 apps
    in TypeScript and JavaScript.
    Just select either of those languages from the combo-box in the banner.

p.
  These instructions assume that you already have the
  <a href="https://www.dartlang.org/downloads/">Dart SDK</a>
  and any tools you like to use with Dart.
  If you don't have a favorite editor already, try
  <a href="https://confluence.jetbrains.com/display/WI/Getting+started+with+Dart">WebStorm</a>,
  which comes with a Dart plugin.
  You can also download
  <a href="https://www.dartlang.org/tools/">Dart plugins for
  other IDEs and editors</a>.
  Once you have the Dart SDK and any other tools you want, return here.


//-  ##########################
.l-main-section
  h2#section-install-angular Set up a new app directory

  :marked
    Create a new directory,
    and put a file named `pubspec.yaml` in it.

  code-example(language="sh").
    &gt; <span class="blk">mkdir angular2_getting_started</span>
    &gt; <span class="blk">cd angular2_getting_started</span>
    &gt; <span class="blk">vim pubspec.yaml</span>  # Use your favorite editor!

  p.
    In <code>pubspec.yaml</code>,
    specify the angular2 and browser packages as dependencies,
    as well as the angular2 transformer.
    Angular 2 is changing rapidly, so provide an exact version:
    <b>2.0.0-alpha.45</b>.

  +makeExample('quickstart/dart/ex1/pubspec.yaml', null, 'pubspec.yaml')

  p.
    In the same directory, create a <code>web</code> directory, and then
    run <code>pub get</code> to install the angular2 and browser packages
    (along with the packages they depend on).

  code-example(language="sh").
    &gt; <span class="blk">mkdir web</span>
    &gt; <span class="blk">pub get</span>
    Resolving dependencies...

  //- PENDING: Create template? Link to pub/pubspec docs?


//-  ##########################
.l-main-section
  h2#section-transpile Create a Dart file

  p.
    Create a file under <code>web</code> named <code>main.dart</code>.

  code-example(language="sh").
    &gt; <span class="blk">vim web/main.dart</span>  # Use your favorite editor!

  p.
    Paste the following code into <code>web/main.dart</code>:

  +makeExample('quickstart/dart/ex1/web/main.dart', null, 'web/main.dart')

  :marked
    You've just defined an Angular 2 **component**,
    one of the most important Angular 2 features.
    Components are the primary way to create application views
    and support them with application logic.

    This component is an empty, do-nothing class named `AppComponent`.
    You can add properties and application logic to it later,
    when you're ready to build a substantive application.

    Above the class is the `@Component` annotation,
    which tells Angular that this class *is an Angular component*.
    The call to the `@Component` constructor has two
    named parameters, `selector` and `template`.

    The `selector` parameter specifies a CSS selector for
    a host HTML element named `my-app`.
    Angular creates and displays an instance of `AppComponent`
    wherever it encounters a `my-app` element.

    The `template` parameter is the component's companion template
    that tells Angular how to render a view.
    In this case, the template is a single line of HTML announcing
    "My First Angular 2 App".

    The <code>main()</code> function
    calls Angular's <code>bootstrap()</code> function,
    which tells Angular to start the application with `AppComponent`
    at the application root.
    Someday the application will
    consist of more components arising in tree-like fashion from this root.

    The top lines import two libraries.
    *All* Dart files that use Angular APIs import `angular2.dart`.
    Only files that call `bootstrap()` import `bootstrap.dart`.

//-  ##########################
.l-main-section


  h2#section-angular-create-account Create an HTML file

  p.
    Create a file named <code>web/index.html</code> that contains
    the following code:

  +makeExample('quickstart/dart/ex1/web/index.html', null, 'web/index.html')

  :marked
    The `<my-app>` tag in the `<body>` is
    the custom HTML element defined in the Dart file.


//-  ##########################
.l-main-section

  h2#section-angular-run-app Run the app

  p.
    You have a few options for running your 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
    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>http://localhost:8080</b> in any modern browser.
    Pub serve generates the JavaScript on the fly,
    which can take a while when you first visit the page.

  p.
    Once the app is running,
    you should see <b>My First Angular 2 App</b> in your browser window.

  :marked
    If you don't see that, make sure you've entered all the code correctly
    and run `pub get`.

//-  ##########################
.l-main-section

  h2#section-angular-run-app Generate JavaScript

  :marked
    Before you can deploy your app, you need to generate JavaScript files.
    Pub build 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.

  :marked
    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/ex2/pubspec.yaml', null, 'pubspec.yaml', stylePattern)

  p.
    Then compile your Dart code to JavaScript,
    using <code>pub build</code>.

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

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

  p.
    When you generate JavaScript for an Angular app,
    be sure to use the Angular transformer.
    It analyzes your 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/ex2/pubspec.yaml', null, 'pubspec.yaml', stylePattern)

  p.
    The <code>entry_points</code> item
    identifies the Dart file in your 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 you import <code>bootstrap.dart</code>,
      you also get <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
      (<code>entry_points</code> in <code>pubspec.yaml</code>)
      so that they don't use mirrors.


//- WHAT'S NEXT... ##########################
.l-main-section
  h2#section-transpile Great job! Next step...

    <!--TODO: Join us on the [Tour of Heroes](./toh-pt1.html) -->

  p.
    Follow the <a href="guide">developer guide</a>
    to continue playing with Angular 2 for Dart.

  p.
    Or read more about Angular or Dart:

  ul
    li
      <a href="resources.html">Angular resources</a>
    li
      <a href="https://www.dartlang.org">dartlang.org</a>