diff --git a/.gitignore b/.gitignore index c7f1ae756b..156b58bb6d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,11 @@ node_modules bower_components jspm_packages typings +packages +build +pubspec.lock +.pub +.packages *.map .DS_Store .idea diff --git a/public/doc-shredder/doc-shredder.js b/public/doc-shredder/doc-shredder.js index 9934641cad..deb0bccfa0 100644 --- a/public/doc-shredder/doc-shredder.js +++ b/public/doc-shredder/doc-shredder.js @@ -86,7 +86,7 @@ function createShredPackage(shredOptions) { readFilesProcessor.sourceFiles = [ { // Process all candidate files in `src` and its subfolders ... include: includeFiles, - exclude: ['**/node_modules/**', '**/typings/**'], + exclude: ['**/node_modules/**', '**/typings/**', '**/packages/**', '**/build/**'], // When calculating the relative path to these files use this as the base path. // So `src/foo/bar.js` will have relative path of `foo/bar.js` basePath: options.examplesDir @@ -231,4 +231,4 @@ function initializePackage(pkg) { // Set logging level log.level = 'info'; }) -} \ No newline at end of file +} diff --git a/public/docs/_examples/gettingstarted/dart/ex1/pubspec.yaml b/public/docs/_examples/gettingstarted/dart/ex1/pubspec.yaml new file mode 100644 index 0000000000..1a5f09eb1b --- /dev/null +++ b/public/docs/_examples/gettingstarted/dart/ex1/pubspec.yaml @@ -0,0 +1,9 @@ +# #docregion +name: angular2-getting-started +version: 0.0.1 +dependencies: + angular2: 2.0.0-alpha.42 + browser: ^0.10.0 +transformers: +- angular2: + entry_points: web/main.dart diff --git a/public/docs/_examples/gettingstarted/dart/ex1/web/index.html b/public/docs/_examples/gettingstarted/dart/ex1/web/index.html new file mode 100644 index 0000000000..8bef2b4d44 --- /dev/null +++ b/public/docs/_examples/gettingstarted/dart/ex1/web/index.html @@ -0,0 +1,15 @@ + + + + + Getting Started + + + + + + + + Loading... + + diff --git a/public/docs/_examples/gettingstarted/dart/ex1/web/main.dart b/public/docs/_examples/gettingstarted/dart/ex1/web/main.dart new file mode 100644 index 0000000000..e6836148a3 --- /dev/null +++ b/public/docs/_examples/gettingstarted/dart/ex1/web/main.dart @@ -0,0 +1,10 @@ +// #docregion +import 'package:angular2/angular2.dart'; +import 'package:angular2/bootstrap.dart'; + +@Component(selector: 'my-app', template: '

My First Angular 2 App

') +class AppComponent {} + +main() { + bootstrap(AppComponent); +} diff --git a/public/docs/_examples/gettingstarted/dart/ex2/pubspec.yaml b/public/docs/_examples/gettingstarted/dart/ex2/pubspec.yaml new file mode 100644 index 0000000000..9a0bfaf8db --- /dev/null +++ b/public/docs/_examples/gettingstarted/dart/ex2/pubspec.yaml @@ -0,0 +1,11 @@ +# #docregion +name: angular2-getting-started +version: 0.0.1 +dependencies: + angular2: 2.0.0-alpha.42 + browser: ^0.10.0 + dart_to_js_script_rewriter: ^0.1.0 +transformers: +- angular2: + entry_points: web/main.dart +- dart_to_js_script_rewriter diff --git a/public/docs/_examples/gettingstarted/dart/ex2/web/index.html b/public/docs/_examples/gettingstarted/dart/ex2/web/index.html new file mode 100644 index 0000000000..8bef2b4d44 --- /dev/null +++ b/public/docs/_examples/gettingstarted/dart/ex2/web/index.html @@ -0,0 +1,15 @@ + + + + + Getting Started + + + + + + + + Loading... + + diff --git a/public/docs/_examples/gettingstarted/dart/ex2/web/main.dart b/public/docs/_examples/gettingstarted/dart/ex2/web/main.dart new file mode 100644 index 0000000000..e6836148a3 --- /dev/null +++ b/public/docs/_examples/gettingstarted/dart/ex2/web/main.dart @@ -0,0 +1,10 @@ +// #docregion +import 'package:angular2/angular2.dart'; +import 'package:angular2/bootstrap.dart'; + +@Component(selector: 'my-app', template: '

My First Angular 2 App

') +class AppComponent {} + +main() { + bootstrap(AppComponent); +} diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index 74c25c2305..2f374653e9 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -1,9 +1,14 @@ +include ../../../_includes/_util-fns + +:markdown + Let's start from zero and build a super simple Angular 2 application in Dart. + .callout.is-helpful - header Angular 2 is currently in Developer Preview - p. - We recommend using - Angular for Dart - for production applications. + header Don't want Dart? + :markdown + Although we're getting started in Dart, you can also write Angular 2 apps + in TypeScript and JavaScript. + Just select either of those languages from the combo-box in the banner. p. These instructions assume that you already have the @@ -15,21 +20,20 @@ p. 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 - h2#section-install-angular 1. Create a project - p. - Create a new directory, and put a file named - pubspec.yaml in it. +//- ########################## +.l-main-section + h2#section-install-angular Set up a new app directory + + :markdown + Create a new directory, + and put a file named `pubspec.yaml` in it. code-example(language="sh"). - > mkdir hello_world - > cd hello_world + > mkdir angular2_getting_started + > cd angular2_getting_started > vim pubspec.yaml # Use your favorite editor! p. @@ -37,168 +41,95 @@ p. 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.39. + 2.0.0-alpha.42. - code-example(language="yaml" format="linenums"). - name: hello_world - version: 0.0.1 - dependencies: - angular2: 2.0.0-alpha.39 - browser: ^0.10.0 - transformers: - - angular2: - entry_points: web/main.dart - -//- STEP 2 - Import Angular ########################## -.l-main-section - h2#section-transpile 2. Import Angular + +makeExample('gettingstarted/dart/ex1/pubspec.yaml', null, 'pubspec.yaml') p. - Still in the same directory, create a web directory. - Create a file under web named main.dart. + In the same directory, create a web directory, and then + run pub get to install the angular2 and browser packages + (along with the packages they depend on). code-example(language="sh"). > mkdir web - > vim web/main.dart # Use your favorite editor! - - p. - In the same directory, run pub get - to install the angular2 and browser packages - (along with the packages they depend on): - - code-example(language="sh"). > pub get + Resolving dependencies... //- PENDING: Create template? Link to pub/pubspec docs? - p. - Edit web/main.dart to import the angular2 - and bootstrap libraries: - code-example(language="dart" format="linenums"). - import 'package:angular2/angular2.dart'; - import 'package:angular2/bootstrap.dart'; -//- STEP 3 - Define a component ########################## +//- ########################## +.l-main-section + h2#section-transpile Create a Dart file + + p. + Create a file under web named main.dart. + + code-example(language="sh"). + > vim web/main.dart # Use your favorite editor! + + p. + Paste the following code into web/main.dart: + + +makeExample('gettingstarted/dart/ex1/web/main.dart', null, 'web/main.dart') + + :markdown + You've just defined an Angular 2 **component**, + one of the most important Angular 2 features. + Components are the primary way to create application views + and support them with application logic. + + This component is an empty, do-nothing class class named `AppComponent`. + You can add properties and application logic to it later, + when you're ready to build a substantive application. + + Above the class is the `@Component` annotation, + which tells Angular that this class *is an Angular component*. + The call to the `@Component` constructor has two + named parameters, `selector` and `template`. + + The `selector` parameter specifies a CSS selector for + a host HTML element named `my-app`. + Angular creates and displays an instance of `AppComponent` + wherever it encounters a `my-app` element. + + The `template` parameter is the component's companion template + that tells Angular how to render a view. + In this case, the template is a single line of HTML announcing + "My First Angular 2 App". + + The main() function + calls Angular's bootstrap() function, + which tells Angular to start the application with `AppComponent` + at the application root. + Someday the application will + consist of more components arising in tree-like fashion from this root. + + The top lines import two libraries. + *All* Dart files that use Angular APIs import `angular2.dart`. + Only files that call `bootstrap()` import `bootstrap.dart`. + +//- ########################## .l-main-section - h2#section-angular-create-account 3. Define a component - - p. - Update web/main.dart, adding the following code - after the imports: - - code-example(language="dart" format="linenums:4"). - @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 - has the tag <my-app>. - The Dart code for an Angular component consists of a class - (the component controller) - that has @Component and @View annotations. - - - .l-sub-section - h3 Annotations - - p. - The @Component annotation defines - the HTML tag for the component by specifying the component's CSS selector. - - p. - The @View 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 templateUrl property - and give it the path to the HTML file. - - 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> - and a template of <h1>Hello {{ name }}</h1>. - - - .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 name property through - the double-mustache syntax ({{ ... }}). - p. - The component controller assigns "Alice" to the name property. When the - template renders, "Hello Alice" appears instead of - "Hello {{ name }}". - - 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 web/main.dart: - - code-example(language="dart" format="linenums:14"). - main() { - bootstrap(AppComponent); - } - - p. - This code adds a main() function - that calls Angular's bootstrap() function. - The argument to bootstrap() 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 + h2#section-angular-create-account Create an HTML file p. Create a file named web/index.html that contains - the following code, - which loads main.dart and instantiates the my-app component: + the following code: - code-example(language="html" format="linenums"). - <!doctype html> - <html> - <head> - <title>Angular 2 Quickstart</title> + +makeExample('gettingstarted/dart/ex1/web/index.html', null, 'web/index.html') - <script async src="main.dart" type="application/dart"></script> - <script async src="packages/browser/dart.js"></script> - </head> - <body> - <my-app></my-app> - </body> - </html> + :markdown + The `` tag in the `` is + the custom HTML element defined in the Dart file. -//- STEP 6 - Run ########################## + +//- ########################## .l-main-section - h2#section-angular-run-app 6. Run your app + h2#section-angular-run-app Run the app p. You have a few options for running your app. @@ -216,25 +147,39 @@ p. p. Once the app is running, - you should see Hello Alice in your browser window. - - -//- STEP 7 - Generate JavaScript ########################## -.l-main-section - - h2#section-angular-run-app 7. Generate JavaScript + you should see My First Angular 2 App in your browser window. p. + If you don't see that, make sure you've entered all the code correctly + and run `pub get`. + +//- ########################## +.l-main-section + + h2#section-angular-run-app Generate JavaScript + + :markdown Before you can deploy your app, you need to generate JavaScript files. - Compiling your Dart code to JavaScript is easy: - just run pub build. + Pub build makes that easy. + To improve your app's performance, convert the + HTML file to directly include the generated JavaScript; + one way to do that is with dart_to_js_script_rewriter. + + :markdown + Add the dart_to_js_script_rewriter package to your pubspec, + in both the `dependencies` and `transformers` sections. + + - var stylePattern = { pnk: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)/gm, otl: /(dependencies:)|(transformers:)/g }; + +makeExample('gettingstarted/dart/ex2/pubspec.yaml', null, 'pubspec.yaml', stylePattern) + + p. + Then compile your Dart code to JavaScript, + using pub build. code-example(language="basic"). > pub build Loading source assets... - ... - Built 333 files to "build". - //- REGENERATE THIS OUTPUT - or delete it? - when updating from 2.0.0-alpha.39 + //- REGENERATE THIS OUTPUT - or delete it? - when updating from 2.0.0-alpha.42 p. The generated JavaScript appears, along with supporting files, @@ -242,24 +187,18 @@ p. p. When you generate JavaScript for an Angular app, - be sure you use the Angular transformer. + be sure to 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.39 - browser: ^0.10.0 - transformers: - - angular2: - entry_points: web/main.dart + - var stylePattern = { otl: /(transformers:)|(- angular2:)|(entry_points.*$)/gm }; + +makeExample('gettingstarted/dart/ex2/pubspec.yaml', null, 'pubspec.yaml', stylePattern) + p. - The entry_points entry + The entry_points item identifies the Dart file in your app that has a main() function. For more information, see the @@ -285,6 +224,8 @@ p. .l-main-section h2#section-transpile Great job! Next step... + + p. Follow the developer guide to continue playing with Angular 2 for Dart.