From 23fcb95fecc4781ad2e1f43f0bd26e1ad91f2d33 Mon Sep 17 00:00:00 2001 From: Kathy Walrath Date: Wed, 3 Jun 2015 12:54:59 -0700 Subject: [PATCH] Update all the code and text to latest alpha.25 examples --- .../dart/latest/guide/displaying-data.jade | 384 ++++++++++-------- .../dart/latest/guide/making-components.jade | 33 +- public/docs/dart/latest/guide/setup.jade | 36 +- public/docs/dart/latest/guide/user-input.jade | 108 ++--- 4 files changed, 287 insertions(+), 274 deletions(-) diff --git a/public/docs/dart/latest/guide/displaying-data.jade b/public/docs/dart/latest/guide/displaying-data.jade index 7253cd00ff..961d34ad80 100644 --- a/public/docs/dart/latest/guide/displaying-data.jade +++ b/public/docs/dart/latest/guide/displaying-data.jade @@ -17,22 +17,19 @@ a pubspec.yaml file: code-tabs - code-pane(language="dart" name="main.dart" format="linenums"). - // web/main.dart - library displaying_data; - + code-pane(language="dart" name="web/main.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; + import 'package:angular2/src/reflection/reflection_capabilities.dart' + show ReflectionCapabilities; - part 'show_properties.dart'; + import 'package:displaying_data/show_properties.dart'; main() { reflector.reflectionCapabilities = new ReflectionCapabilities(); bootstrap(DisplayComponent); } - code-pane(language="html" name="index.html" format="linenums"). - <!-- web/index.html --> + code-pane(language="html" name="web/index.html" format="linenums"). <!DOCTYPE html> <html> <head> @@ -47,45 +44,45 @@ </body> </html> code-pane(language="yaml" name="pubspec.yaml" format="linenums"). - # pubspec.yaml name: displaying_data description: Dart version of Angular 2 example, Displaying Data version: 0.0.1 dependencies: - angular2: 2.0.0-alpha.23 - browser: any + angular2: 2.0.0-alpha.25 + browser: ^0.10.0 + transformers: + - angular2: + entry_points: web/main.dart p. All of this code should look familiar from the previous page, - except for the library and part statements + except for the import of show_properties.dart in main.dart. - Those statements let you implement part of the app in a different Dart file. + That import statement lets you implement part of the app in a different Dart file. All three of these files remain similar in the rest of the examples, - so we'll just focus on what's different. + so we'll focus on what changes. .l-main-section h2#section-showing-properties-with-interpolation Showing properties with interpolation p. The simple method for binding text into templates is through interpolation, where you put the name of a property - inside {{ }}. + inside {{ }}. p. - To see this working, create a Dart file under web - named show_properties.dart, - and add the following: + To see this working, first create a lib directory. + Under it, put a Dart file named show_properties.dart + that contains the following code: - code-example(language="dart" format="linenums"). + code-example(language="dart" format="linenums" escape="html"). // web/show_properties.dart - part of displaying_data; + library displaying_data.show_properties; - @Component( - selector: 'display' - ) - @View( - template: ''' - <p>My name: {{ myName }}</p> - ''' - ) + import 'package:angular2/angular2.dart'; + + @Component(selector: 'display') + @View(template: ''' +

My name: {{ myName }}

+ ''') class DisplayComponent { String myName = 'Alice'; } @@ -94,8 +91,8 @@ You've just defined a component that encompasses a view and controller for the app. The view defines a template: - code-example(language="html"). - <p>My name: {{ myName }}</p> + code-example(language="html" escape="html"). +

My name: {{ myName }}

p. Angular will automatically pull the value of myName and @@ -132,85 +129,86 @@ <p>Current time: {{ time }}</p> p. - Then give the DisplayComponent a starting value for time and - a call to update time - via setInterval: + Then import dart:async so you can use a Timer, + and give the DisplayComponent a starting value for time and + create a periodic Timer call to update the time: - code-example(language="dart" format="linenums"). - class DisplayComponent { - String myName = 'Alice'; - String time; - Timer _timer; + code-example(language="dart"). + import 'dart:async'; + ... + class DisplayComponent { + String myName = 'Alice'; + String time; + Timer _timer; - DisplayComponent() { - _updateTime(null); - _timer = new Timer.periodic(new Duration(seconds: 1), _updateTime); - } - - _updateTime(Timer _) { - time = new DateTime.now().toString(); - } + DisplayComponent() { + _updateTime(null); + _timer = new Timer.periodic(new Duration(seconds: 1), _updateTime); } + _updateTime(Timer _) { + time = new DateTime.now().toString(); + } + } + p Reload the app, and you'll now see the seconds updating automatically. .l-main-section - h2#Create-an-array Display an iterable using *for + h2#Create-an-array Display an iterable using *ng-for p Moving up from a single value, create a property that's a list of values. - code-example(language="dart" format="linenums"). + code-example(language="dart"). class DisplayComponent { String myName = 'Alice'; - List<String> friendNames = ['Aarav', 'Martín', 'Shannon', 'Ariana', 'Kai']; + List<String> friendNames = const [ + 'Aarav', + 'Martín', + 'Shannon', + 'Ariana', + 'Kai' + ]; } p. - You can then use this list in your template with the for directive to create copies of DOM elements + You can then use this list in your template with + the ng-for directive to create copies of DOM elements with one for each item in the list. - code-example(language="dart" format="linenums"). - @View( - template: ''' - <p>My name: {{ myName }}</p> - <p>Friends:</p> - <ul> - <li *for="#name of friendNames"> + code-example(language="dart"). + @View(template: ''' + <p>My name: {{ myName }}</p> + <p>Friends:</p> + <ul> + <li *ng-for="#name of friendNames"> {{ name }} - </li> - </ul> - ''' - ) - p. - To make this work, you'll also need to add the Angular For directive used by - the template to show_properties.dart, so that Angular knows to include it. - Add For using the optional directives parameter, - which contains a list of directives: + </li> + </ul> + ''', directives: const [NgFor]) - code-example(language="dart" format="linenums"). - @View( - template: ''' - // ...HTML... - ''', - directives: const[For] - ) + p. + To make ng-for work, + you need to add the Angular NgFor directive, + so that Angular knows to include it. + Add NgFor using the optional directives parameter. p Reload and you've got your list of friends! p. - Again, Angular will mirror changes you make to this list over in the DOM. Add a new item and it appears in your - list. Delete one and Angular deletes the <li>. Reorder items and Angular makes the corresponding reorder of - the DOM list. + Again, Angular will mirror changes you make to this list over in the DOM. + Add a new item and it appears in your list. + Delete one and Angular deletes the <li>. + Reorder items and Angular makes the corresponding reorder of the DOM list. p Let's look at the few lines that do the work again: - code-example(language="html" format="linenums"). - <li *for="#name of friendNames"> + code-example(language="html"). + <li *ng-for="#name of friendNames"> {{ name }} </li> p The way to read this is: ul li. - *for: Create a DOM element for each item in an + *ng-for: Create a DOM element for each item in an iterable such as a list. li #name: Refer to individual values of the iterable as name. @@ -221,157 +219,151 @@ .l-main-section h2#Create-a-class Create a model and inject it p. - Before we get too much further, we should mention that putting the model (list) directly into the controller isn't - proper form. We should separate the concerns by having another class serve the role of model and inject it into - the controller. + Before we get too much further, we should mention that + putting the model (list) directly into the controller isn't proper form. + We should separate the concerns by having another class + serve the role of model and inject it into the controller. p. - Make a FriendsService class to implement a model containing a list of friends. We'll put this in a new - friends_service.dart under web/. Here's what the class looks like: + Make a FriendsService class to implement a model + containing a list of friends. + Put this in a new file under web/ + named friends_service.dart. Here's what the class looks like: code-example(language="dart" format="linenums"). // web/friends_service.dart - part of displaying_data; + library displaying_data.friends_service; + import 'package:angular2/angular2.dart'; + + @Injectable() class FriendsService { - List<String> friendNames = ['Aarav', 'Martín', 'Shannon', 'Ariana', 'Kai']; + List<String> names = ['Aarav', 'Martín', 'Shannon', 'Ariana', 'Kai']; } - .callout.is-helpful - header Note - p. - Remember to tie friends_service.dart into the library's main file: - add part friends_service.dart to main.dart. p. Now you can replace the current list of friends in DisplayComponent. - First add a FriendsService parameter to the constructor. + Import friends_service.dart, + and add a FriendsService parameter to the constructor. Then set friendNames to the names provided by the service. - code-example(language="dart" format="linenums"). + code-example(language="dart"). // In web/show_properties.dart + import 'package:displaying_data/friends_service.dart'; + ... class DisplayComponent { String myName = 'Alice'; - List friendNames; + List<String> friendNames; - DisplayComponent(FriendsService friendsService) { - friendNames = friendsService.names; + DisplayComponent(FriendsService friendsService) { + friendNames = friendsService.names; } } p. Next, make FriendsService available to dependency injection - by adding an injectables parameter to DisplayComponent's + by adding an appInjector parameter to DisplayComponent's @Component annotation: - code-example(language="dart" format="linenums"). - @Component( - selector: 'display', - injectables: const[FriendsService] - ) + code-example(language="dart"). + @Component(selector: 'display', appInjector: const [FriendsService]) .l-main-section - h2#Conditionally-displaying-data-with-If Conditionally display data using *if + h2#Conditionally-displaying-data-with-NgIf Conditionally display data using *ng-if p. - Lastly, before we move on, let's handle showing parts of our UI conditionally with *if. The - If directive adds or removes elements from the DOM based on the expression you provide. + Lastly, before we move on, let's handle showing parts of our UI conditionally with *ng-if. The + NgIf directive adds or removes elements from the DOM based on the expression you provide. p See it in action by adding a paragraph at the end of your template: code-example(language="html"). - <p *if="names.length > 3">You have many friends!</p> + <p *ng-if="friendNames.length > 3">You have many friends!</p> p. - Also add If to the list of directives, + Also add NgIf to the list of directives, so Angular knows to include it: code-example(language="dart"). - directives: const[For, If] + directives: const[NgFor, NgIf] p. - The list current has 5 items, so if you run the app you'll see the message + The list currently has 5 items, so if you run the app you'll see the message congratulating you on your many friends. Remove two items from the list, reload your browser, and see that the message no longer displays. - p Here's the final code. code-tabs - code-pane(language="dart" name="show_properties.dart" format="linenums"). - // web/show_properties.dart - part of displaying_data; + code-pane(language="dart" name="lib/show_properties.dart" format="linenums"). + library displaying_data.show_properties; - @Component( - selector: 'display', - injectables: const[FriendsService] - ) - @View( - template: ''' - <p>My name: {{ myName }}</p> - <p>Friends:</p> - <ul> - <li *for="#name of friendNames"> + import 'package:angular2/angular2.dart'; + import 'package:displaying_data/friends_service.dart'; + + @Component(selector: 'display', appInjector: const [FriendsService]) + @View(template: ''' + <p>My name: {{ myName }}</p> + <p>Friends:</p> + <ul> + <li *ng-for="#name of friendNames"> {{ name }} - </li> - </ul> - ''', - directives: const[For] - ) + </li> + </ul> + <p *ng-if="friendNames.length > 3">You have many friends!</p> + ''', directives: const [NgFor, NgIf]) class DisplayComponent { String myName = 'Alice'; - List<String> friendNames; + List<String> friendNames; DisplayComponent(FriendsService friendsService) { friendNames = friendsService.names; } } - code-pane(language="dart" name="friends_service.dart" format="linenums"). - // web/friends_service.dart - part of displaying_data; - - class FriendsService { - List<String> names = ['Aarav', 'Martín', 'Shannon', 'Ariana', 'Kai']; - } - code-pane(language="dart" name="main.dart" format="linenums"). - // web/main.dart - library displaying_data; - - import 'dart:async'; + code-pane(language="dart" name="lib/friends_service.dart" format="linenums"). + library displaying_data.friends_service; import 'package:angular2/angular2.dart'; - import 'package:angular2/src/reflection/reflection.dart' show reflector; - import 'package:angular2/src/reflection/reflection_capabilities.dart' show ReflectionCapabilities; - part 'show_properties.dart'; - part 'friends_service.dart'; + @Injectable() + class FriendsService { + List<String> names = ['Aarav', 'Martín', 'Shannon', 'Ariana', 'Kai']; + } + code-pane(language="dart" name="web/main.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; + + import 'package:displaying_data/show_properties.dart'; main() { reflector.reflectionCapabilities = new ReflectionCapabilities(); bootstrap(DisplayComponent); } - code-pane(language="html" name="index.html" format="linenums"). - <!-- web/index.html --> + code-pane(language="html" name="web/index.html" format="linenums"). <!DOCTYPE html> <html> <head> - <link rel="stylesheet" href="style.css"> + <link rel="stylesheet" href="style.css"> </head> <body> <display></display> - <script type="application/dart" src="main.dart"></script> - <script src="packages/browser/dart.js"></script> + <script type="application/dart" src="main.dart"></script> + <script src="packages/browser/dart.js"></script> </body> </html> code-pane(language="yaml" name="pubspec.yaml" format="linenums"). - # pubspec.yaml name: displaying_data - description: Dart version of Angular 2 example, Displaying Data + description: Displaying Data example version: 0.0.1 dependencies: - angular2: 2.0.0-alpha.23 - browser: any + angular2: 2.0.0-alpha.25 + browser: ^0.10.0 + transformers: + - angular2: + entry_points: web/main.dart .l-main-section h2#section-explanations Explanations @@ -380,40 +372,74 @@ p. Dart offers a few ways to implement an app in multiple files. - In this guide, all the code for each example is in a single library; - each Dart file under web is part of that library. + In this guide, each example is in a single package, + and each Dart file implements a separate library. + For a bigger project, you might split the code into libraries + in two or more packages. p. - To let the code in main.dart - use the code in show_properties.dart, - declare a library in main.dart. - Then make show_properties.dart part of that library. + To use the API defined in show_properties.dart, + main.dart must import that file. + The import statement uses the package name + (defined in pubspec.yaml to be displaying_data) + and the path to show_properties.dart + (starting at the app's top directory, + but omitting the lib/ directory). - code-tabs - code-pane(language="dart" name="main.dart" format="linenums"). - // web/main.dart - library displaying_data; - // imports... - part 'show_properties.dart'; - // Code goes here... - code-pane(language="dart" name="show_properties.dar" format="linenums"). - // web/show_properties.dart - part of displaying_data; - // Code goes here... + code-example(language="dart"). + // In web/main.dart: + ... + import 'package:displaying_data/show_properties.dart'; + ... + + // In lib/show_properties.dart: + library displaying_data.show_properties; + ... p. - Another way to split Dart code is to - define multiple libraries in a single package. - The additional libraries go under a lib directory - parallel to web. - + The name that show_properties.dart specifies for its library + is similar to the path used to import the library, + but with no ".dart" suffix and + with dots (.) instead of slashes (/). + Naming + conventions for libraries, + along with lots of other helpful information, are in the + Dart Style Guide. p. - Yet another approach, often used when some of the code is highly reusable, - is to split the code into libraries in two or more packages. + Another import lets show_properties.dart + use the API defined in friends_service.dart: + + code-example(language="dart"). + // In lib/show_properties.dart: + library displaying_data.show_properties; + ... + import 'package:displaying_data/friends_service.dart'; + ... + + // In lib/friends_service.dart: + library displaying_data.friends_service; + ... + + p. + Because both show_properties.dart and friends_service.dart + are under lib, + the import could instead use a relative path: + + code-example(language="dart"). + // In lib/show_properties.dart: + library displaying_data.show_properties; + ... + import 'friends_service.dart'; + ... + + // In lib/friends_service.dart: + library displaying_data.friends_service; + ... p. For more information on implementing Dart libraries, see Libraries and visibility in the Dart language tour. + diff --git a/public/docs/dart/latest/guide/making-components.jade b/public/docs/dart/latest/guide/making-components.jade index aacb4a9697..45cb6c4b0b 100644 --- a/public/docs/dart/latest/guide/making-components.jade +++ b/public/docs/dart/latest/guide/making-components.jade @@ -11,18 +11,16 @@ component that uses a <child> component like so: code-example(language="dart" format="linenums"). - part of making_components; + library parent_child.parent; - @Component( - selector: 'parent' - ) - @View( - template: ''' + import 'package:angular2/angular2.dart'; + import 'package:parent_child/child.dart'; + + @Component(selector: 'parent') + @View(template: ''' <h1>{{ message }}</h1> <child></child> - ''', - directives: const[ChildComponent] - ) + ''', directives: const [ChildComponent]) class ParentComponent { String message = "I'm the parent"; } @@ -30,19 +28,16 @@ p You then just need to write the ChildComponent class to make it work: code-example(language="dart" format="linenums"). - part of making_components; + library parent_child.child; - @Component( - selector: 'child' - ) - @View( - template: ''' + import 'package:angular2/angular2.dart'; + + @Component(selector: 'child') + @View(template: ''' <p> {{ message }} </p> - ''' - ) + ''') class ChildComponent { String message = "I'm the child"; } - //p. - [TODO: Motivate communication between components with iterator example that passes index to the child] +//- [TODO: Motivate communication between components with iterator example that passes index to the child] diff --git a/public/docs/dart/latest/guide/setup.jade b/public/docs/dart/latest/guide/setup.jade index 9aeb1fcec3..0fbc0f2d4b 100644 --- a/public/docs/dart/latest/guide/setup.jade +++ b/public/docs/dart/latest/guide/setup.jade @@ -27,11 +27,14 @@ code-example(language="yaml"). # pubspec.yaml name: getting_started - description: Dart version of Angular 2 example, Getting Started + description: Getting Started example version: 0.0.1 dependencies: - angular2: 2.0.0-alpha.23 - browser: any + angular2: 2.0.0-alpha.25 + browser: ^0.10.0 + transformers: + - angular2: + entry_points: web/main.dart p. Run pub get to download the packages your app depends on. (Dart-savvy editors and IDEs @@ -50,20 +53,16 @@ and creating a top-level main() function that calls Angular's bootstrap() function. - code-example(language="javascript"). + code-example(language="dart" escape="html"). // web/main.dart import 'package:angular2/angular2.dart'; import 'package:angular2/src/reflection/reflection.dart' show reflector; - import 'package:angular2/src/reflection/reflection_capabilities.dart' show ReflectionCapabilities; + import 'package:angular2/src/reflection/reflection_capabilities.dart' + show ReflectionCapabilities; - @Component( - selector: 'my-app' - ) - @View( - template: '<h1>My first Angular 2 App</h1>' - ) - class AppComponent { - } + @Component(selector: 'my-app') + @View(template: '

My first Angular 2 App

') + class AppComponent {} main() { reflector.reflectionCapabilities = new ReflectionCapabilities(); @@ -73,7 +72,8 @@ .l-main-section h2#section-create-an-entry-point Create an HTML file p. - In the web/ directoryapp, create an HTML file (index.html). + In the web/ directory of your app, + create an HTML file (index.html). Edit index.html to add a <my-app> element and call main.dart. @@ -98,14 +98,6 @@ Now run the app. How you do this depends on your tools. ul - li. - If you're using Dart Editor, - right-click web/index.html, - and choose Open in Dartium. - This starts a web server - and opens your app in Dartium, - an experimental version of the Chromium browser that contains the Dart VM. - li. If you're using WebStorm or IntelliJ IDEA, right-click web/index.html, diff --git a/public/docs/dart/latest/guide/user-input.jade b/public/docs/dart/latest/guide/user-input.jade index a79bdca809..86d48801b9 100644 --- a/public/docs/dart/latest/guide/user-input.jade +++ b/public/docs/dart/latest/guide/user-input.jade @@ -44,11 +44,14 @@ Then add a method that adds new items to the list. - code-example(language="dart" format="linenums"). + code-example(language="dart"). class TodoList { - List<String> todos = - ['Eat breakfast', 'Walk dog', 'Breathe', 'Learn Angular']; - + List<String> todos =[ + 'Eat breakfast', + 'Walk dog', + 'Breathe', + 'Learn Angular' + ]; addTodo(String todo) { todos.add(todo); } @@ -67,12 +70,12 @@ .l-main-section h2#section-display-the-list-of-todos Display the list of todos p. - Using the *for iterator, create an <li> for each item in the todos list and set + Using the *ng-for iterator, create an <li> for each item in the todos list and set its text to the value. - code-example(language="html" format="linenums"). + code-example(language="html"). <ul> - <li *for="#todo of todos"> + <li *ng-for="#todo of todos"> {{ todo }} </li> </ul> @@ -101,54 +104,54 @@ dart:html, so be sure to import that library. - code-tabs - code-pane(language="dart" name="todo_list.dart" format="linenums"). - // In the template: - <input #todotext (keyup)="doneTyping(\$event)"> + code-example(language="dart"). + import 'dart:html'; + ... - // In the component controller class: - doneTyping(KeyboardEvent event) { - if (event.keyCode == KeyCode.ENTER) { - InputElement e = event.target; - addTodo(e.value); - e.value = null; - } + // In the template: + <input #todotext (keyup)="doneTyping(\$event)"> + ... + + // In the component controller class: + doneTyping(KeyboardEvent event) { + if (event.keyCode == KeyCode.ENTER) { + InputElement e = event.target; + addTodo(e.value); + e.value = null; } - code-pane(language="dart" name="main.dart" format="linenums"). - library user_input; - - import 'dart:html'; - ... + } .l-main-section h2#section-final-code Final code code-tabs - code-pane(language="dart" name="todo_list.dart" format="linenums"). - // web/todo_list.dart - part of user_input; + code-pane(language="dart" name="lib/todo_list.dart" format="linenums"). + library user_input.todo_list; - @Component( - selector: 'todo-list' - ) + import 'dart:html'; + import 'package:angular2/angular2.dart'; + + @Component(selector: 'todo-list') @View( - // Without r before ''' (a raw string), $event breaks Angular. - // An alternative to a raw string is to use \$event instead. - template: r''' + // An alternative to using \$event is to use a raw string instead. + // For example, change "template: '''" to "template: r'''". + template: ''' <ul> - <li *for="#todo of todos"> + <li *ng-for="#todo of todos"> {{ todo }} </li> </ul> - <input #todotext (keyup)="doneTyping($event)"> - <button (click)="addTodo(todotext.value)">Add Todo</button> - ''', - directives: const[For] - ) + <input #todotext (keyup)="doneTyping(\$event)"> + <button (click)="addTodo(todotext.value)">Add Todo</button> + ''', directives: const [NgFor]) class TodoList { - List<String> todos = - ['Eat breakfast', 'Walk dog', 'Breathe', 'Learn Angular']; + List<String> todos = [ + 'Eat breakfast', + 'Walk dog', + 'Breathe', + 'Learn Angular' + ]; addTodo(String todo) { todos.add(todo); @@ -162,24 +165,19 @@ } } } - code-pane(language="dart" name="main.dart" format="linenums"). - // web/main.dart - library user_input; - - import 'dart:html'; - + code-pane(language="dart" name="web/main.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; + import 'package:angular2/src/reflection/reflection_capabilities.dart' + show ReflectionCapabilities; - part 'todo_list.dart'; + import 'package:user_input/todo_list.dart'; main() { reflector.reflectionCapabilities = new ReflectionCapabilities(); bootstrap(TodoList); } - code-pane(language="html" name="index.html" format="linenums"). - <!-- web/index.html --> + code-pane(language="html" name="web/index.html" format="linenums"). <!DOCTYPE html> <html> <head> @@ -194,10 +192,12 @@ </body> </html> code-pane(language="yaml" name="pubspec.yaml" format="linenums"). - # pubspec.yaml name: user_input - description: Dart version of Angular 2 example, Responding to User Input + description: User Input example version: 0.0.1 dependencies: - angular2: 2.0.0-alpha.23 - browser: any + angular2: 2.0.0-alpha.25 + browser: ^0.10.0 + transformers: + - angular2: + entry_points: web/main.dart