diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index aab648a5e6..7836ca52f5 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -7,13 +7,20 @@ 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. -// 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 @@ -21,38 +28,39 @@ 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. + 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. - 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" 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 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? + //- 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 @@ -60,27 +68,20 @@ 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'; + 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; - // 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] - -// 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 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 +123,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,32 +149,23 @@ p. template renders, "Hello Alice" appears instead of "Hello {{ name }}". - pre.prettyprint - code. - class AppComponent { - String name = 'Alice'; - } + code-example(language="dart"). + class AppComponent { + String name = 'Alice'; + } - // [PENDING: add line numbers once we can specify where they start] - - -// STEP 4 - Bootstrap ########################## +//- STEP 4 - Bootstrap ########################## .l-main-section h2#section-transpile 4. Bootstrap 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 @@ -188,13 +174,18 @@ p. you defined above. p. - Setting the value of - reflector.reflectionCapabilities - is a temporary workaround - that you can remove once Angular's transformer is available. + 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 @@ -204,53 +195,110 @@ 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" format="linenums"). + <!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 ########################## +//- 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 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 WebStorm's server + or 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. -// 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 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". + //- 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 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: ^0.10.0+2 + 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... ########################## .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