Merge pull request #133 from angular/kwalrath-dart-quickstart

dart quickstart: add transformer, use alpha.25

Author: kwalrath

public/docs/dart/latest/quickstart.jade

@@ -7,80 +7,81 @@
 
 
 p.
-  These instructions assume that you already have the Dart SDK
+  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 not, go
-  <a href="https://www.dartlang.org/downloads/">download Dart</a>.
-  Then return here.
+  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>.
 
-// STEP 1 - Create a project ##########################
+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.
 
-  pre.prettyprint
-    code.
-      &gt; mkdir hello_world
-      &gt; cd hello_world
-      &gt; vim pubspec.yaml  # Use your favorite editor!
+  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>, add the angular2 and browser packages as dependencies.
-    Angular 2 is changing rapidly, so specify an exact version:
-    <b>2.0.0-alpha.23</b>.
-
-  pre.prettyprint.linenums.lang-basic
-    code.
-      name: hello_world
-      version: 0.0.1
-      dependencies:
-        angular2: 2.0.0-alpha.23
-        browser: any
+    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.25</b>.
+
+  code-example(language="yaml" format="linenums").
+    name: hello_world
+    version: 0.0.1
+    dependencies:
+      angular2: 2.0.0-alpha.25
+      browser: ^0.10.0+2
+    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):
 
-  pre.prettyprint.lang-basic
-    code.
-      &gt; pub get
+  code-example(language="sh").
+    &gt; <span class="blk">pub get</span>
 
-  // PENDING: Create template? Link to pub/pubspec docs?
-  // Is browser really needed?
+  //- PENDING: Create template? Link to pub/pubspec docs?
 
 
-// STEP 2 - Import Angular ##########################
+//- 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>.
 
-  pre.prettyprint
-    code.
-      &gt; mkdir web
-      &gt; vim web/main.dart  # Use your favorite editor!
+  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 angular2 library
-    and (for now) two reflection libraries:
-
-  // pre.prettyprint.linenums
-  pre.prettyprint
-    code.
-      import 'package:angular2/angular2.dart';
+    and two reflection libraries:
 
-      // These imports will go away soon:
-      import 'package:angular2/src/reflection/reflection.dart' show reflector;
-      import 'package:angular2/src/reflection/reflection_capabilities.dart' show ReflectionCapabilities;
+  code-example(language="dart" format="linenums").
+    import 'package:angular2/angular2.dart';
+    import 'package:angular2/src/reflection/reflection.dart' show reflector;
+    import 'package:angular2/src/reflection/reflection_capabilities.dart' show ReflectionCapabilities;
 
-  // [PENDING: add line numbers once we can specify where they start]
-
-// STEP 3 - Define a component ##########################
+//- STEP 3 - Define a component ##########################
 .l-main-section
 
   h2#section-angular-create-account 3. Define a component
@@ -89,19 +90,16 @@ p.
     Update <code>web/main.dart</code>, adding the following code
     after the imports:
 
-  pre.prettyprint
-    code.
-      @Component(
-        selector: 'my-app'
-      )
-      @View(
-        template: '&lt;h1&gt;Hello {{ name }}&lt;/h1&gt;'
-      )
-      class AppComponent {
-        String name = 'Alice';
-      }
-
-  // [PENDING: add line numbers once we can specify where they start]
+  code-example(language="dart" format="linenums:5").
+    @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
@@ -125,16 +123,13 @@ p.
       specify a <code>templateUrl</code> property
       and give it the path to the HTML file.
 
-    pre.prettyprint
-      code.
-        @Component(
-          selector: 'my-app'
-        )
-        @View(
-          template: '&lt;h1&gt;Hello {{ name }}&lt;/h1&gt;'
-        )
-
-    // [PENDING: add line numbers once we can specify where they start]
+    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>
@@ -154,32 +149,23 @@ p.
       template renders, "Hello Alice" appears instead of
       <span ng-non-bindable>"Hello {{ name }}"</span>.
 
-    pre.prettyprint
-      code.
-        class AppComponent {
-          String name = 'Alice';
-        }
-
-    // [PENDING: add line numbers once we can specify where they start]
-
+    code-example(language="dart").
+      class AppComponent {
+        String name = 'Alice';
+      }
 
-// STEP 4 - Bootstrap ##########################
+//- 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>:
 
-  pre.prettyprint
-    code.
-      main() {
-        // Temporarily needed.
-        reflector.reflectionCapabilities = new ReflectionCapabilities();
-
-        bootstrap(AppComponent);
-      }
-
-  // [PENDING: add line numbers once we can specify where they start]
+  code-example(language="dart" format="linenums:15").
+    main() {
+      reflector.reflectionCapabilities = new ReflectionCapabilities();
+      bootstrap(AppComponent);
+    }
 
   p.
     This code adds a <code>main()</code> function
@@ -188,13 +174,18 @@ p.
     you defined above.
 
   p.
-    Setting the value of
-    <code>reflector.reflectionCapabilities</code>
-    is a temporary workaround
-    that you can remove once Angular's transformer is available.
-
-
-// STEP 5 - Declare the HTML ##########################
+    Setting the value of <code>reflector.reflectionCapabilities</code>
+    lets your app use the Dart VM's reflection (dart:mirrors)
+    when running in Dartium.
+    Reflection is fast in native Dart,
+    so using it makes sense during development.
+    Later, when you build a JavaScript version of your app,
+    the Angular transformer will
+    convert the reflection-using code to static code,
+    so your generated JavaScript can be smaller and faster.
+
+
+//- STEP 5 - Declare the HTML ##########################
 .l-main-section
 
   h2#section-angular-create-account 5. Declare the HTML
@@ -204,53 +195,110 @@ p.
     the following code,
     which loads <code>main.dart</code> and instantiates the my-app component:
 
-  pre.prettyprint.linenums
-    code.
-        &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 - Build and run ##########################
+  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. Build and run your app
+  h2#section-angular-run-app 6. Run your app
 
   p.
-    You have several options for running your app.
-    The quickest and easiest, for now,
-    is to open your project in <b>Dart Editor</b>,
-    right-click <b>web/index.html</b>,
-    and choose <b>Open in Dartium</b>.
-    This starts a web server
-    and opens your app in an experimental browser that contains the Dart VM.
-
-  // TODO: screenshot? embedded app?
+    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 a browser.
-    Generating the JavaScript takes a few seconds when you first visit the page,
-    and the generated JavaScript is currently large.
-    The generated JavaScript will be smaller once
-    Angular's transformer becomes available.
+    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.
 
-  // [PENDING: Update when transformer is working!]
 
-// WHAT'S NEXT... ##########################
+//- 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...
+    Loading angular2 transformers...
+    INFO: Formatter is being overwritten.
+    Building hello_world... (3.1s)
+    [Info from Dart2JS]:
+    Compiling hello_world|web/main.dart...
+    [Info from Dart2JS]:
+    Took 0:00:16.123086 to compile hello_world|web/main.dart.
+    Built 41 files to "build".
+  //- REGENERATE THIS OUTPUT - or delete it? - when updating from 2.0.0-alpha.25
+
+  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.25
+      browser: ^0.10.0+2
+    <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>.
+
+//- WHAT'S NEXT... ##########################
 .l-main-section
   h2#section-transpile Great job! Next step...
 
   p.
-    We plan to add a developer guide soon.
-    Until then, check out <a href="resources.html">Angular Resources</a>.
-    To learn more about Dart, go to
-    <a href="https://www.dartlang.org">dartlang.org</a>.
+    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>