From 3bd646b228f8cb0533ca636cba7652b615c372de Mon Sep 17 00:00:00 2001 From: Kathy Walrath Date: Fri, 29 May 2015 17:55:02 -0700 Subject: [PATCH 1/3] dart quickstart: add transformer, use alpha.25 --- public/docs/dart/latest/quickstart.jade | 244 +++++++++++++----------- 1 file changed, 135 insertions(+), 109 deletions(-) diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index aab648a5e6..4bb54c2632 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -21,32 +21,29 @@ p. Create a new directory, and put a file named pubspec.yaml in it. - pre.prettyprint - code. - > mkdir hello_world - > cd hello_world - > vim pubspec.yaml # Use your favorite editor! + code-example(language="sh"). + > mkdir hello_world + > cd hello_world + > vim pubspec.yaml # Use your favorite editor! p. In pubspec.yaml, add the angular2 and browser packages as dependencies. Angular 2 is changing rapidly, so specify an exact version: - 2.0.0-alpha.23. + 2.0.0-alpha.25. - pre.prettyprint.linenums.lang-basic - code. - name: hello_world - version: 0.0.1 - dependencies: - angular2: 2.0.0-alpha.23 - browser: any + 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 pub get to install the angular2 and browser packages (along with the packages they depend on): - pre.prettyprint.lang-basic - code. - > pub get + code-example(language="sh"). + > pub get // PENDING: Create template? Link to pub/pubspec docs? // Is browser really needed? @@ -60,25 +57,18 @@ p. Still in the same directory, create a web directory. Create a file under web named main.dart. - pre.prettyprint - code. - > mkdir web - > vim web/main.dart # Use your favorite editor! + code-example(language="sh"). + > mkdir web + > vim web/main.dart # Use your favorite editor! p. Edit web/main.dart 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 web/main.dart, adding the following code after the imports: - pre.prettyprint - code. - @Component( - selector: 'my-app' - ) - @View( - template: '<h1>Hello {{ name }}</h1>' - ) - 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: '<h1>Hello {{ name }}</h1>' + ) + class AppComponent { + String name = 'Alice'; + } p. The code you just added creates a component that @@ -125,16 +112,13 @@ p. specify a templateUrl property and give it the path to the HTML file. - pre.prettyprint - code. - @Component( - selector: 'my-app' - ) - @View( - template: '<h1>Hello {{ name }}</h1>' - ) - - // [PENDING: add line numbers once we can specify where they start] + code-example(language="dart"). + @Component( + selector: 'my-app' + ) + @View( + template: '<h1>Hello {{ name }}</h1>' + ) p. The annotations above specify an HTML tag of <my-app> @@ -154,14 +138,10 @@ p. template renders, "Hello Alice" appears instead of "Hello {{ name }}". - 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,16 +150,11 @@ p. p. Add the following code to the bottom of web/main.dart: - 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 main() function @@ -187,11 +162,7 @@ p. The argument to bootstrap() is the name of the component class you defined above. - p. - Setting the value of - reflector.reflectionCapabilities - 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,20 +175,19 @@ p. the following code, which loads main.dart and instantiates the my-app component: - pre.prettyprint.linenums - code. - <!doctype html> - <html> - <head> - <title>Angular 2 Quickstart</title> - </head> - <body> - <my-app></my-app> + code-example(language="html"). + <!doctype html> + <html> + <head> + <title>Angular 2 Quickstart</title> + </head> + <body> + <my-app></my-app> - <script type="application/dart" src="main.dart"></script> - <script src="packages/browser/dart.js"></script> - </body> - </html> + <script type="application/dart" src="main.dart"></script> + <script src="packages/browser/dart.js"></script> + </body> + </html> // STEP 6 - Build and run ########################## .l-main-section @@ -225,32 +195,88 @@ p. 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 Dart Editor, - right-click web/index.html, - and choose Open in Dartium. - 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 + Dartium. + You can use whatever server you like, such as Python's SimpleHTTPServer. p. Another option is to build and serve the app using pub serve, - and then run it by visiting http://localhost:8080 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 http://localhost:8080 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 Hello Alice 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 pubspec.yaml: + + code-example(language="yaml"). + name: hello_world + version: 0.0.1 + dependencies: + angular2: 2.0.0-alpha.25 + browser: any + transformers: + - angular2: + entry_points: web/main.dart + p. + Then build the JavaScript version using pub build: + + code-example(language="basic"). + > pub build + 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 build directory. + + p. + For more information, see the + Angular + transformer wiki page. // 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 Angular Resources. - To learn more about Dart, go to - dartlang.org. + Follow the developer guide + to continue playing with Angular 2 for Dart. + + p. + Or read more about Angular or Dart: + + ul + li + Angular resources + li + dartlang.org From 22fcdb346f050c914dcd0827f338adfb996d95ae Mon Sep 17 00:00:00 2001 From: Kathy Walrath Date: Mon, 1 Jun 2015 09:24:11 -0700 Subject: [PATCH 2/3] make the transformer more prominent --- public/docs/dart/latest/quickstart.jade | 99 ++++++++++++++----------- 1 file changed, 57 insertions(+), 42 deletions(-) diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index 4bb54c2632..5979ee7fbd 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -13,7 +13,7 @@ p. download Dart. Then return here. -// STEP 1 - Create a project ########################## +//- STEP 1 - Create a project ########################## .l-main-section h2#section-install-angular 1. Create a project @@ -27,16 +27,21 @@ p. > vim pubspec.yaml # Use your favorite editor! p. - In pubspec.yaml, add the angular2 and browser packages as dependencies. - Angular 2 is changing rapidly, so specify an exact version: + In pubspec.yaml, + specify the angular2 and browser packages as dependencies, + as well as the angular2 transformer. + Angular 2 is changing rapidly, so provide an exact version: 2.0.0-alpha.25. - code-example(language="yaml"). + code-example(language="yaml" format="linenums"). name: hello_world version: 0.0.1 dependencies: angular2: 2.0.0-alpha.25 browser: any + transformers: + - angular2: + entry_points: web/main.dart p. In the same directory, run pub get to install the angular2 and browser packages @@ -45,11 +50,11 @@ p. code-example(language="sh"). > pub get - // PENDING: Create template? Link to pub/pubspec docs? - // Is browser really needed? + //- PENDING: browser: any -> ??? + //- 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 @@ -70,7 +75,7 @@ p. import 'package:angular2/src/reflection/reflection.dart' show reflector; import 'package:angular2/src/reflection/reflection_capabilities.dart' show ReflectionCapabilities; -// STEP 3 - Define a component ########################## +//- STEP 3 - Define a component ########################## .l-main-section h2#section-angular-create-account 3. Define a component @@ -143,7 +148,7 @@ p. String name = 'Alice'; } -// STEP 4 - Bootstrap ########################## +//- STEP 4 - Bootstrap ########################## .l-main-section h2#section-transpile 4. Bootstrap @@ -162,10 +167,19 @@ p. The argument to bootstrap() is the name of the component class you defined above. - //- Explain why setting reflector.reflectionCapabilities is necessary. + p. + Setting the value of reflector.reflectionCapabilities + 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 ########################## +//- STEP 5 - Declare the HTML ########################## .l-main-section h2#section-angular-create-account 5. Declare the HTML @@ -175,7 +189,7 @@ p. the following code, which loads main.dart and instantiates the my-app component: - code-example(language="html"). + code-example(language="html" format="linenums"). <!doctype html> <html> <head> @@ -189,10 +203,10 @@ p. </body> </html> -// STEP 6 - Build and run ########################## +//- 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 a few options for running your app. @@ -212,36 +226,15 @@ p. you should see Hello Alice in your browser window. -// STEP 7 - Use the Angular transformer ########################## +//- STEP 7 - Generate JavaScript ########################## .l-main-section - h2#section-angular-run-app 7. Use the Angular transformer + h2#section-angular-run-app 7. Generate JavaScript 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 pubspec.yaml: - - code-example(language="yaml"). - name: hello_world - version: 0.0.1 - dependencies: - angular2: 2.0.0-alpha.25 - browser: any - transformers: - - angular2: - entry_points: web/main.dart - p. - Then build the JavaScript version using pub build: + Before you can deploy your app, you need to generate JavaScript files. + Compiling your Dart code to JavaScript is easy: + just run pub build. code-example(language="basic"). > pub build @@ -254,17 +247,39 @@ p. [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 compiled JavaScript appears, along with supporting files, + The generated JavaScript appears, along with supporting files, under the build 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 pubspec.yaml + 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: any + transformers: + - angular2: + entry_points: web/main.dart + p. + The entry_points entry + identifies the Dart file in your app + that has a main() function. For more information, see the Angular transformer wiki page. -// WHAT'S NEXT... ########################## +//- WHAT'S NEXT... ########################## .l-main-section h2#section-transpile Great job! Next step... From 0bff66b9b6ab015477d3597ee2df9477dfb88521 Mon Sep 17 00:00:00 2001 From: Kathy Walrath Date: Mon, 1 Jun 2015 15:41:41 -0700 Subject: [PATCH 3/3] Update browser version; add more info about tools. --- public/docs/dart/latest/quickstart.jade | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index 5979ee7fbd..7836ca52f5 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -7,11 +7,18 @@ p. - These instructions assume that you already have the Dart SDK + These instructions assume that you already have the + Dart SDK and any tools you like to use with Dart. - If not, go - download Dart. - Then return here. + If you don't have a favorite editor already, try + WebStorm, + which comes with a Dart plugin. + You can also download + Dart plugins for + other IDEs and editors. + +p. + Once you have the Dart SDK and any other tools you want, return here. //- STEP 1 - Create a project ########################## .l-main-section @@ -38,7 +45,7 @@ p. version: 0.0.1 dependencies: angular2: 2.0.0-alpha.25 - browser: any + browser: ^0.10.0+2 transformers: - angular2: entry_points: web/main.dart @@ -50,7 +57,6 @@ p. code-example(language="sh"). > pub get - //- PENDING: browser: any -> ??? //- PENDING: Create template? Link to pub/pubspec docs? @@ -213,7 +219,8 @@ p. One is to launch a local HTTP server and then view the app in Dartium. - You can use whatever server you like, such as Python's SimpleHTTPServer. + 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 pub serve, @@ -267,7 +274,7 @@ p. version: 0.0.1 dependencies: angular2: 2.0.0-alpha.25 - browser: any + browser: ^0.10.0+2 transformers: - angular2: entry_points: web/main.dart