dart quickstart: add transformer, use alpha.25

Author: kwalrath

public/docs/dart/latest/quickstart.jade

@@ -21,32 +21,29 @@ 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
+    <b>2.0.0-alpha.25</b>.
+
+  code-example(language="yaml").
+    name: hello_world
+    version: 0.0.1
+    dependencies:
+      angular2: 2.0.0-alpha.25
+      browser: any
   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?
@@ -60,25 +57,18 @@ 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:
+    and two reflection libraries:
 
-  // pre.prettyprint.linenums
-  pre.prettyprint
-    code.
-      import 'package:angular2/angular2.dart';
-
-      // 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;
-
-  // [PENDING: add line numbers once we can specify where they start]
+  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;
 
 // STEP 3 - Define a component ##########################
 .l-main-section
@@ -89,19 +79,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 +112,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,14 +138,10 @@ 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 ##########################
 .l-main-section
@@ -170,28 +150,19 @@ p.
   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
     that calls Angular's <code>bootstrap()</code> function.
     The argument to <code>bootstrap()</code> is the name of the component class
     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.
+  //- Explain why setting reflector.reflectionCapabilities is necessary.
 
 
 // STEP 5 - Declare the HTML ##########################
@@ -204,53 +175,108 @@ 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>
+  code-example(language="html").
+    &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 ##########################
 .l-main-section
 
   h2#section-angular-run-app 6. Build and 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 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.
 
-  // [PENDING: Update when transformer is working!]
+  p.
+    Once the app is running,
+    you should see <b>Hello Alice</b> in your browser window.
+
+
+// STEP 7 - Use the Angular transformer ##########################
+.l-main-section
+
+  h2#section-angular-run-app 7. Use the Angular transformer
+
+  p.
+    To enable quick turnaround while you're developing an Angular app,
+    the framework uses reflection via dart:mirrors.
+    Unfortunately, mirror-using Dart code compiles to
+    JavaScript code that's large and slow.
+    To create more deployable JavaScript, use the Angular transformer.
+    The transformer analyzes your code,
+    converting reflection to static code
+    that Dart's build tools can compile to faster, smaller JavaScript.
+
+  p.
+    To use the Angular transformer,
+    first add the highlighted lines to your <code>pubspec.yaml</code>:
+
+  code-example(language="yaml").
+    name: hello_world
+    version: 0.0.1
+    dependencies:
+      angular2: 2.0.0-alpha.25
+      browser: any
+    <span class="pnk">transformers:
+    - angular2:
+        entry_points: web/main.dart</span>
+  p.
+    Then build the JavaScript version using <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".
+
+  p.
+    The compiled JavaScript appears, along with supporting files,
+    under the <code>build</code> directory.
+
+  p.
+    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>