Try Dart 1 hour experience first draft

src/site/articles/trydart/index.markdown.safe.mdown

+---
+layout: default
+title: "Try Dart"
+description: "Write some Dart code. Learn some stuff."
+has-permalinks: true
+tutorial:
+  id: trydart
+js:
+- url: /js/os-switcher.js
+  defer: true
+- url: /js/editor-downloads-analytics.js
+  defer: true
+- url: /js/editor-version.js
+  defer: true
+header:
+  css: ["/articles/trydart/trydart.css"]
+---
+
+# {{ page.title }}
+
+## Got an hour? Write a Dart app.
+
+In this code lab,
+you build a pirate badge generator from a skeleton app.
+
+<strong>Build this app!</strong>
+
+<iframe class="running-app-frame"
+        style="height:220px;width:530px;"
+        src="examples/piratebadge/piratebadge.html">
+</iframe>
+
+<hr>
+
+## The Map
+
+* [Step 0: Set up](#set-up)
+* [Step 1: Look at the code for the skeleton app](#step-one)
+* [Step 2: Add an input field](#step-two)
+* [Step 3: Add a button](#step-three)
+* [Step 4: Create a PirateName class](#step-four)
+* [Step 5: Generate random names](#step-five)
+* [Step 6: Add radio buttons](#step-six)
+* [Step 7: Read the names from a JSON file with HttpRequest](#step-seven)
+
+
+XXX: Notes to self:
+XXX: use fancy code highlighter for hover, perhaps this would be 
+good for comments about language features vs. code walkthrough comments
+
+<hr>
+
+## Step 0: Set up {#set-up}
+
+In this step you download Dart and get the sample code.
+
+#### <i class="icon-anchor"> </i> Get Dart.
+
+<div class="trydart-step-details" markdown="1">
+If you haven't already done so,
+get the Dart download.
+
+{% include downloads/_dart-editor.html %}
+
+<p markdown="1">
+  The Dart tools
+  work in recent versions of
+  {% include os-choices.html %}
+Having trouble? Go to the
+[Troubleshooting Dart Editor](/tools/editor/troubleshoot.html) page.
+</p>
+</div>
+
+#### <i class="icon-anchor"> </i> Start the Editor.
+
+<div class="trydart-step-details">
+Start Dart Editor by double clicking its icon
+<img src="/imgs/Dart_Logo_21.png"
+     width="21" height="21" alt="Dart Editor icon">.
+</div>
+
+#### <i class="icon-anchor"> </i> Get the sample code.
+
+<div class="trydart-step-details">
+<a href="https://github.com/dart-lang/dart-tutorials-samples/archive/master.zip">
+   Download
+</a>
+the sample code.
+Unzip the ZIP file.
+</div>
+
+#### <i class="icon-anchor"> </i> Open the directory.
+
+<div class="trydart-step-details" markdown="1">
+In Dart Editor,
+open the `piratebadge` directory from the ZIP file
+with **File>Open Existing Folder...**.
+</div>
+
+<div class="row"> <div class="span7" markdown="1">
+
+![The files and directories in the piratebadge directory.](images/filesanddirs.png)
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* Dart web apps use the public `browser` package to run on a web page.
+This project has all of the package dependencies set up for you
+and the packages installed.
+The packages directory, the `pubspec.yaml`, and `pubspec.lock` files are
+all related to library dependencies.
+
+* Several numbered directories contain the completed code for each step.
+`1-blankbadge` contains the skeletal version of the app that you begin with.
+`6-piratebadge_json` contains the final version of the app.
+
+* The `piratebadge.css` file
+provides the CSS styles for all steps of the app.
+You don't change this file during this code lab.
+
+&nbsp; {% comment %} non-breaking space required for bootstrap/markdown bogosity {% endcomment %}
+
+</div> </div>
+
+<hr>
+
+##Step 1: Run the skeleton app {#step-one}
+
+In this step, you open the source files for the skeleton app,
+familiarize yourself with the Dart and HTML code,
+and run the app.
+
+#### <i class="icon-anchor"> </i> Expand the 1-blankbadge directory.
+
+<div class="trydart-step-details" markdown="1">
+In Dart Editor, expand the `1-blankbadge` directory,
+which contains two files, `piratebadge.html` and `piratebadge.dart`.
+</div>
+
+#### <i class="icon-anchor"> </i> Open the files.
+
+<div class="trydart-step-details" markdown="1">
+Open both files by double-clicking each filename in Dart Editor.
+</div>
+
+#### <i class="icon-anchor"> </i> Review the code
+
+<div class="trydart-step-details" markdown="1">
+Get familiar with the HTML and the Dart code for the skeleton version of the app.
+The interesting bits are highlighted below.
+</div>
+
+<div class="trydart-step-details" markdown="1">
+##### piratebadge.html
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details" markdown="1">
+{% prettify html%}
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Pirate badge</title>
+    <link rel="stylesheet" href="../piratebadge.css">
+  </head>
+  <body>
+    <h1>Pirate badge</h1>
+    
+    <div class="widgets">
+      [[highlight]]<span>TO DO: Put the UI widgets here.</span>[[/highlight]]
+    </div>
+    <div class="outer">
+      <div class="boilerplate">
+        Arrr! Me name is
+      </div>
+      <div class="name">
+        [[highlight]]<span id="badgeName"> </span>[[/highlight]]
+      </div>
+    </div>
+
+    [[highlight]]<script type="application/dart" src="piratebadge.dart"></script>[[/highlight]]
+    [[highlight]]<script src="packages/browser/dart.js"></script>[[/highlight]]
+  </body>
+</html>
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* During the code lab,
+all the changes you make to `piratebadge.html` are within
+the &lt;div&gt; element identified with the class `widgets`.
+
+* The &lt;span&gt; element with the ID `badgeName`
+is programmatically updated by the Dart code
+based on user input.
+
+* The `piratebadge.dart` script provides the main program for the app.
+
+* The `packages/browser/dart.js` script is a bootstrap script
+that takes care of turning on the Dart VM,
+as well as compatibility with non-Dart browsers.
+
+</div> </div>
+
+<div class="trydart-step-details" markdown="1">
+##### piratebadge.dart
+</div>
+
+<div class="row"> <div class="span7" markdown="1">
+
+<div class="trydart-step-details" markdown="1">
+{% prettify dart %}
+[[highlight]]void main() {
+  // Your app starts here.
+}
+[[/highlight]]
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* This file is included in the HTML file
+with the &lt;script&gt; tag.
+
+* The `main()` function is a top-level function.
+  Dart calls this function when your app starts.
+
+&nbsp; {% comment %} non-breaking space required for bootstrap/markdown bogosity {% endcomment %}
+</div> </div>
+
+#### <i class="icon-anchor"> </i> Run the app.
+
+<div class="trydart-step-details" markdown="1">
+To run the app in Dart Editor, select `piratebadge.html`
+and click the Run button
+<img src="images/run.png" width="16" height="16"
+     alt="Run button">.
+
+You should see a TO DO comment on the left
+and a red and white name badge on the right.
+</div>
+
+<div class="trydart-step-details" markdown="1">
+<iframe class="running-app-frame"
+        style="height:220px;width:530px;"
+        src="examples/1-blankbadge/piratebadge.html">
+</iframe>
+</div>
+
+<hr>
+
+##Step 2: Add an input field {#step-two}
+
+In this step you add an input field to the app.
+The user types a name into the input field and presses return.
+The Dart code updates the badge from the value of the input field
+when the user presses return.
+
+#### Try it!
+
+<div class="trydart-step-details" markdown="1">
+Type in the input field and press return.
+
+<iframe class="running-app-frame"
+        style="height:220px;width:530px;"
+        src="examples/2-inputnamebadge/inputnamebadge.html">
+</iframe>
+</div>
+
+#### <i class="icon-anchor"> </i> Edit piratebadge.html.
+
+<div class="row"> <div class="span7" markdown="1">
+
+<div class="trydart-step-details" markdown="1">
+
+Add an input field to the HTML code as shown by the highlighted code.
+
+{% prettify html %}
+...
+<div class="widgets">
+[[highlight]]  <div>
+    <input type="text" id="inputName" value="Anne">
+  </div>[[/highlight]]
+</div>
+...
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* The ID for the input element is `inputName`.
+The Dart code gets this element by querying the DOM for this ID.
+
+&nbsp; {% comment %} non-breaking space required for bootstrap/markdown bogosity {% endcomment %}
+
+</div> </div>
+
+#### <i class="icon-anchor"> </i> Edit piratebadge.dart.
+
+<div class="trydart-step-details">
+Add the highlighted code as shown in the code snippets below.
+</div>
+
+<div class="trydart-step-details">
+Import the dart:html libary:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details" markdown="1">
+
+{% prettify dart %}
+[[highlight]]import 'dart:html';[[/highlight]]
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* The `dart:html` library provides HTML elements and access to the DOM.
+
+</div> </div>
+
+<div class="trydart-step-details">
+
+Add a top-level variable to refer to the input field element.
+
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details" markdown="1">
+{% prettify dart %}
+[[highlight]]InputElement inputNameElement;[[/highlight]]
+{% endprettify %}
+</div>
+</div><div class="span5" markdown="1">
+
+* Declare a top-level variable of type
+<a href="https://api.dartlang.org/dart_html/InputElement.html" target="_blank">InputElement</a>,
+a class defined in `dart:html`.
+
+</div></div>
+
+<div class="trydart-step-details" markdown="1">
+Add code to the main program to get the input field and give it an event handler.
+</div>
+
+<div class="row"> <div class="span7">
+<div class="trydart-step-details" markdown="1">
+{% prettify dart %}
+void  main() {
+[[highlight]]  inputNameElement = query('#inputName');
+  inputNameElement.onChange.listen(generateBadge);[[/highlight]]
+}
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* The `query()` function gets an element from the DOM.
+This program uses the CSS ID selector `#inputName` to get the input field.
+
+* The code registers a change event handler on the input field.
+A change event occurs when the user presses return.
+Other kinds of events include mouse click, and input events.
+
+</div> </div>
+
+<div class="trydart-step-details" markdown="1">
+Implement the event handler for the text field.
+</div>
+
+<div class="row"> <div class="span7">
+<div class="trydart-step-details" markdown="1">
+{% prettify dart %}
+
+[[highlight]]void generateBadge(Event event) { 
+  query('#badgeName').text = inputNameElement.value;
+}[[/highlight]]
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* The `generateBadge()` function is a top-level function.
+It is also an event handler based on its signature.
+
+* Dart has common programming language constructs like `if`-`else`.
+
+* Set the text of the badgeName element using the value of the input field.
+
+
+&nbsp; {% comment %} non-breaking space required for bootstrap/markdown bogosity {% endcomment %}
+
+</div> </div>
+
+<hr> 
+
+##Step 3: Add a button {#step-three}
+
+In this step you add a button to the app.
+
+#### Try it!
+
+<div class="trydart-step-details">
+Type in the text field and click the button.
+</div>
+
+<div class="trydart-step-details">
+<iframe class="running-app-frame"
+        style="height:220px;width:530px;"
+        src="examples/3-buttonbadge/piratebadge.html">
+</iframe>
+</div>
+
+#### <i class="icon-anchor"> </i> Edit piratebadge.html.
+
+<div class="trydart-step-details">
+Add the button below the input field as shown:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify html %}
+...
+<div class="widgets">
+  <div>
+    <input type="text" id="inputName" value="Anne">
+  </div>
+[[highlight]]  <div>
+    <button id="generateButton">Generate badge</button>
+  </div>[[/highlight]]
+</div>
+...
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* The button has the ID `generateButton` so that
+the Dart code can query the DOM for element
+and provide it with a mouse click handler.
+
+</div> </div>
+
+#### <i class="icon-anchor"> </i> Edit piragebadge.dart.
+
+<div class="trydart-step-details">
+Add the highlighted line of code that
+provides a mouse click handler for the button:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+InputElement inputNameElement;
+[[highlight]]ButtonElement genButtonElement;[[/highlight]]
+...
+inputNameElement = query('#inputName');
+inputNameElement.onChange.listen(generateBadge);
+
+[[highlight]]genButtonElement = query('#generateButton');
+genButtonElement.onClick.listen(generateBadge);[[/highlight]]
+...
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* The button uses the same event handler as the input field,
+but uses it to handle mouse click events
+instead of change events.
+
+&nbsp; {% comment %} non-breaking space required for bootstrap/markdown bogosity {% endcomment %}
+
+</div> </div>
+
+<div class="trydart-step-details" markdown="1">
+Modify the `generateBadge` event handler method as follows:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+void generateBadge(Event event) {
+  [[highlight]]if (event.target == inputNameElement) {[[/highlight]]
+    query('#badgeName').text = inputNameElement.value;
+[[highlight]]  } else {
+    query('#badgeName').text = 'Anne Bonney';
+ }[[/highlight]]
+}
+{% endprettify %}
+</div>
+</div> <div class="span5" markdown="1">
+* If the user presses the button, the program updates the badge with the name `Anne Bonney`.
+Otherwise, it uses the value of the input field.
+</div></div>
+
+<hr>
+
+##Step 4: Create a PirateName class {#step-four}
+
+In this step, you change only the Dart code.
+You create a class to represent a pirate name.
+When created, an instance of this class
+randomly selects a name from a list,
+or optionally you can provide a name to the constructor.
+
+<iframe class="running-app-frame"
+        style="height:220px;width:530px;"
+        src="examples/4-classbadge/piratebadge.html">
+</iframe>
+
+#### <i class="icon-anchor"> </i> Edit piratebadge.dart.
+
+<div class="trydart-step-details">
+At the top of the file,
+add another import.
+</div>
+
+<div class="row"> <div class="span7">
+<div class="trydart-step-details">
+{% prettify dart %}
+import 'dart:math';
+{% endprettify %}
+</div>
+</div class="span5" markdown="1">
+Import the dart:math library to get constants
+and Random, the random number generator.
+
+
+<div class="trydart-step-details">
+At the end of the file, add all of this code,
+which provides the definition of a new
+class called `PirateName`.
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+class PirateName {
+  
+  Random indexGen = new Random();
+  
+  String _pirateName;
+  
+  String get name => _pirateName;
+         set name(String value) => _pirateName = value;
+         
+  String toString() => name;
+
+  PirateName({String firstName}) {
+    if (firstName == null) {
+      firstName = names[indexGen.nextInt(names.length)];
+    }
+    _pirateName = '$firstName';
+  }
+
+  List names = const [ 'Anne', 'Bette', 'Cate', 'Dawn',
+  ...
+                       'Yvan', 'Zeb'];
+}
+{% endprettify %}
+</div>
+
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* Class definition.
+
+* Instance variable declaration.
+
+* Private variables start with underscore (`_`).
+
+* Getters and setters.
+
+* Fat arrow shorthand.
+
+* Constructor with optional parameter.
+
+</div> </div>
+
+<div class="trydart-step-details" markdown="1">
+Modify the code for `generateBadge()` event handler with this code:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+void generateBadge(Event event) {
+  if (event.target == inputNameElement) {
+    [[highlight]]query('#badgeName').text = new PirateName(firstName: inputNameElement.value).name;[[/highlight]]
+  } else {
+    [[highlight]]query('#badgeName').text = new PirateName().name;[[/highlight]]
+  }
+}
+{% endprettify %}
+</div>
+
+</div><div class="span5" markdown="1">
+
+* Calling a constructor with `new`.
+
+* Passing in an optional parameter.
+
+</div></div>
+
+
+### Concepts {#step-four-concepts}
+
+Blahdity blah blah blah.
+
+![The anatomy of a class.](images/anatomyclass.png)
+
+##Step 5: Add a check box {#step-five}
+
+In this step you add a checkbox to the app
+that allows the user to use a
+randomly selected name for the badge.
+
+#### Try it!
+
+<div class="trydart-step-details">
+Select the check box then click the button.
+</div>
+
+<div class="trydart-step-details">
+<iframe class="running-app-frame"
+        style="height:220px;width:530px;"
+        src="examples/4-randombadge/piratebadge.html">
+</iframe>
+</div>
+
+#### <i class="icon-anchor"> </i> Edit piratebadge.html.
+
+<div class="trydart-step-details">
+Add the checkbox just below the input field (and above the button) as shown:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify html %}
+...
+<div class="widgets">
+  <div>
+    <input type="text" id="inputName" value="Anne">
+  </div>
+[[highlight]]  <div>
+    <input type="checkbox" id="useRandomName">
+    <label for="useRandomName">Use random name.</label>
+  </div>[[/highlight]]
+  ...
+</div>
+...
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* Include a label for the check box so that the user can click either the label
+or the checkbox to change the setting.
+
+</div> </div>
+
+#### <i class="icon-anchor"> </i> Edit piratebadge.dart.
+
+<div class="trydart-step-details">
+  Add an import to the top of the file.
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+import 'dart:html';
+[[highlight]]import 'dart:math';[[/highlight]]
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+Import the `dart:math` library, which includes
+the
+<a href="https://api.dartlang.org/dart_math/Random.html" target="_blank">Random</a>
+class, a random number generator.
+
+</div> </div>
+
+<div class="trydart-step-details">
+Declare two top-level variables.
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+...
+InputElement inputNameElement;
+
+[[highlight]]bool useRandomName = false[[/highlight]]
+[[highlight]]Random indexGenerator = new Random();[[/highlight]]
+...
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* The click handler for the check box
+sets `useRandomName` to true when 
+the check box is selected and false otherwise.
+
+* Create a random number generator object using `new`
+and the name of the constructor.
+
+</div> </div>
+
+<div class="trydart-step-details">
+Register a click handler
+for the check box in the `main()` function.
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+void main() {
+  ...
+  [[highlight]]query('#useRandomName').onClick.listen(useRandomNameClickHandler);[[/highlight]]
+}
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* is there anything to say here?
+
+&nbsp; {% comment %} non-breaking space required for bootstrap/markdown bogosity {% endcomment %}
+
+</div> </div>
+
+<div class="trydart-step-details">
+Provide the code for the click handler.
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+[[highlight]]void useRandomNameClickHandler(MouseEvent e) { 
+  if ((e.target as CheckboxInputElement).checked) {
+    inputNameElement.disabled = true;
+    useRandomName = true;
+  } else {
+    inputNameElement.disabled = false;
+    useRandomName = false;
+  }
+}[[/highlight]]
+
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* The click handler enables or disables the
+input field depending on whether the check box is selected.
+
+* The click handler sets `useRandomName` to true when the
+check box is selected.
+
+* Note the use of `as`, Dart's a typecast operator.
+
+</div> </div>
+
+<div class="trydart-step-details">
+Add a top-level variable&mdash;a
+list of names from which to randomly select.
+</div>
+
+<div class="row"> <div class="span7">
+<div class="trydart-step-details">
+{% prettify %}
+...
+bool useRandomName = false;
+Random indexGenerator = new Random();
+
+[[highlight]]List names = [ "Anne", "Bette", "Cate", "Dawn",
+  "Elise", "Faye", "Ginger", "Harriot",
+  "Izzy", "Jane", "Kaye", "Liz",
+  "Maria", "Nell", "Olive", "Pat",
+  "Queenie", "Rae", "Sal", "Tam",
+  "Uma", "Violet", "Wilma", "Xana", "Yvonne", "Zelda"]; [[/highlight]]
+...
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* This is a list literal and defines a list that contains 26 strings.
+
+</div> </div>
+
+<div class="trydart-step-details">
+Modify the click handler
+for the **Generate badge** button
+so that it generates a name when the check box is selected.
+</div>
+
+<div class="row"> <div class="span7">
+<div class="trydart-step-details">
+{% prettify dart %}
+void generateBadge(Event event) { 
+[[highlight]]  if (useRandomName) {
+    query('#badgeName').text = names[indexGenerator.nextInt(names.length)];
+  } else {[[/highlight]]
+    query('#badgeName').text = inputNameElement.value;
+[[highlight]]  } [[/highlight]]
+}
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* You can get the length of a list with the `length` property.
+
+* The random number generator's `nextInt()` function
+gets a new random number betwee 0 and `names.length`.
+
+* The code uses that number as an index into the list of strings.
+
+</div> </div>
+
+{% comment %}
+#### piratebadge.dart
+
+<div class="row">
+  <div class="span7">
+  </div>
+  <div class="span5">
+  </div>
+</div>
+
+#### piratebadge.html
+
+<div class="row">
+  <div class="span7">
+  </div>
+  <div class="span5">
+  </div>
+</div>
+{% endcomment %}