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

.callout.is-helpful
  header Angular 2 is currently in Developer Preview
  p.
    We recommend using
    <a href='https://angulardart.org'>Angular for Dart</a>
    for production applications.


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>.

p.
  Once you have the Dart SDK and any other tools you want, return here.

//- STEP 1 - Create a project ##########################
.l-main-section
  h2#section-install-angular 1. Create a project

  p.
    Create a new directory, and put a file named
    <code>pubspec.yaml</code> in it.

  code-example(language="sh").
    &gt; <span class="blk">mkdir hello_world</span>
    &gt; <span class="blk">cd hello_world</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.33</b>.

  code-example(language="yaml" format="linenums").
    name: hello_world
    version: 0.0.1
    dependencies:
      angular2: 2.0.0-alpha.33
      browser: ^0.10.0
    transformers:
    - angular2:
        entry_points: web/main.dart
  p.
    In the same directory, 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">pub get</span>

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


//- STEP 2 - Import Angular ##########################
.l-main-section
  h2#section-transpile 2. Import Angular

  p.
    Still in the same directory, create a <code>web</code> directory.
    Create a file under <code>web</code> named <code>main.dart</code>.

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

  p.
    Edit <code>web/main.dart</code> to import the Angular bootstrap library:

  code-example(language="dart" format="linenums").
    import 'package:angular2/bootstrap.dart';
//- STEP 3 - Define a component ##########################
.l-main-section

  .l-sub-section
    h3 Top-level Angular 2 libraries

    p.
      The main Dart file for any Angular 2 app must import
      <code>'package:angular2/bootstrap.dart'</code>.
      If you put part of your app into one or more additional libraries,
      those additional libraries must import <code>angular2.dart</code>
      instead of <code>bootstrap.dart</code>,

    p.
      The <code>bootstrap.dart</code> and <code>angular2.dart</code> files
      provide the same API,
      except that <code>bootstrap.dart</code> also provides a
      <code>bootstrap()</code> function, which you'll see a little later.
      For <a href="#performance">performance reasons</a>,
      use <code>angular2.dart</code> whenever possible.

  h2#section-angular-create-account 3. Define a component

  p.
    Update <code>web/main.dart</code>, adding the following code
    after the imports:

  code-example(language="dart" format="linenums:6").
    @Component(
      selector: 'my-app'
    )
    @View(
      template: '&lt;h1&gt;Hello {{ name }}&lt;/h1&gt;'
    )
    class AppComponent {
      String name = 'Alice';
    }

  p.
    The code you just added creates a component that
    has the tag <b>&lt;my-app></b>.
    The Dart code for an Angular component consists of a class
    (the <b>component controller</b>)
    that has <code>@Component</code> and <code>@View</code> annotations.


  .l-sub-section
    h3 Annotations

    p.
      The <code>@Component</code> annotation defines
      the HTML tag for the component by specifying the component's CSS selector.

    p.
      The <code>@View</code> annotation defines the HTML that
      represents the component. This component uses an inline template,
      but you can also have an external template. To use an external template,
      specify a <code>templateUrl</code> property
      and give it the path to the HTML file.

    code-example(language="dart").
      @Component(
        selector: 'my-app'
      )
      @View(
        template: '&lt;h1&gt;Hello {{ name }}&lt;/h1&gt;'
      )

    p.
      The annotations above specify an HTML tag of <code>&lt;my-app&gt;</code>
      and a template of <code ng-non-bindable>&lt;h1&gt;Hello &#123;&#123; name }}&lt;/h1&gt;</code>.


  .l-sub-section
    h3 The template and the component controller

    p.
      A template has access to all the public properties and methods
      of its component controller.
      The template above binds to a <code>name</code> property through
      the double-mustache syntax (<code ng-non-bindable>{{ ... }}</code>).
    p.
      The component controller assigns "Alice" to the name property. When the
      template renders, "Hello Alice" appears instead of
      <span ng-non-bindable>"Hello {{ name }}"</span>.

    code-example(language="dart").
      class AppComponent {
        String name = 'Alice';
      }

//- STEP 4 - Bootstrap ##########################
.l-main-section
  h2#section-transpile 4. Bootstrap

  p.
    Add the following code to the bottom of <code>web/main.dart</code>:

  code-example(language="dart" format="linenums:16").
    main() {
      bootstrap(AppComponent);
    }

  p.
    This code adds a <code>main()</code> function
    that calls Angular's <code>bootstrap()</code> function.
    The argument to <code>bootstrap()</code> is the name of the component class
    you defined above.


//- STEP 5 - Declare the HTML ##########################
.l-main-section

  h2#section-angular-create-account 5. Declare the HTML

  p.
    Create a file named <code>web/index.html</code> that contains
    the following code,
    which loads <code>main.dart</code> and instantiates the my-app component:

  code-example(language="html" format="linenums").
    &lt;!doctype html>
    &lt;html>
      &lt;head&gt;
        &lt;title&gt;Angular 2 Quickstart&lt;/title&gt;
      &lt;/head&gt;
      &lt;body>
        &lt;my-app>&lt;/my-app>

        &lt;script type="application/dart" src="main.dart">&lt;/script>
        &lt;script src="packages/browser/dart.js">&lt;/script>
      &lt;/body>
    &lt;/html>

//- STEP 6 - Run ##########################
.l-main-section

  h2#section-angular-run-app 6. Run your 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 takes a few seconds when you first visit the page.

  p.
    Once the app is running,
    you should see <b>Hello Alice</b> in your browser window.


//- STEP 7 - Generate JavaScript ##########################
.l-main-section

  h2#section-angular-run-app 7. Generate JavaScript

  p.
    Before you can deploy your app, you need to generate JavaScript files.
    Compiling your Dart code to JavaScript is easy:
    just run <code>pub build</code>.

  code-example(language="basic").
    &gt; <span class="blk">pub build</span>
    Loading source assets...
    ...
    Building hello_world... (5.7s)
    [Info from Dart2JS]:
    Compiling hello_world|web/main.dart...
    [Info from Dart2JS]:
    Took 0:00:19.177402 to compile hello_world|web/main.dart.
    Built 303 files to "build".
  //- REGENERATE THIS OUTPUT - or delete it? - when updating from 2.0.0-alpha.33

  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 you 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:

  code-example(language="yaml" format="linenums").
    name: hello_world
    version: 0.0.1
    dependencies:
      angular2: 2.0.0-alpha.33
      browser: ^0.10.0
    <span class="pnk">transformers:
    - angular2:
        entry_points: web/main.dart</span>
  p.
    The <code>entry_points</code> entry
    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
      so that they don't use mirrors.
      The transformer doesn't convert other libraries in your app,
      so be sure to
      import <code>angular2.dart</code> instead of <code>bootstrap.dart</code>
      in any libraries you create that use Angular 2
      but don't call <code>bootstrap()</code>.


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

  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>