Try Dart 1 hour experience first draft

src/site/articles/trydart/index.markdown

+---
+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/7-piratebadge_json/piratebadge.html">
+</iframe>
+
+<hr>
+
+## The Map
+
+* [Step 0: Set up](#set-up)
+* [Step 1: Run 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: Add a check box](#step-five)
+* [Step 6: Read the names from a JSON file with HttpRequest](#step-six)
+
+
+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.
+
+#### <i class="icon-anchor"> </i> 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/piratebadge.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 the &lt;input&gt; tag to the HTML code
+within the `widgets` &lt;div&gt;.
+
+{% 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" markdown="1">
+Import the `dart:html` library at the top of the file:
+</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">
+
+Declare 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">
+
+* <a href="https://api.dartlang.org/dart_html/InputElement.html" target="_blank">InputElement</a>
+is one of the HTML element classes defined in `dart:html`.
+
+</div></div>
+
+<div class="trydart-step-details" markdown="1">
+Register a function to handle changes to the input field.
+</div>
+
+<div class="row"> <div class="span7">
+<div class="trydart-step-details" markdown="1">
+{% prettify dart %}
+void  main() {
+[[highlight]]  inputNameElement = query('#inputName');
+  inputNameElement.onInput.listen(generateBadge);[[/highlight]]
+}
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* The `query()` function defined in
+`dart:html` gets an element from the DOM.
+This program uses the CSS ID selector `#inputName` to get the input field.
+
+* The code registers an input event handler on the input field.
+An input event occurs when the user presses a key.
+
+</div> </div>
+
+<div class="trydart-step-details" markdown="1">
+Implement the event handler as a top-level function.
+</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 an event handler based on its signature.
+
+* Set the text of the `badgeName` element from 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.
+When the user clicks the button,
+the app puts the name `Anne Bonney` on the badge.
+In later steps, the button uses a randomly selected name.
+
+#### Try it!
+
+<div class="trydart-step-details">
+Type in the input field and press return.
+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 &lt;button&gt; tag below the input field:
+</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">
+Wire up the button with a click handler.
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+InputElement inputNameElement;
+
+void main() {}
+  inputNameElement = query('#inputName');
+  inputNameElement.onInput.listen(generateBadge);
+
+[[highlight]]  query('#generateButton')
+      ..classes.add('hiddenTreasure')
+      ..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 input events.
+
+* Method cascades.
+
+&nbsp; {% comment %} non-breaking space required for bootstrap/markdown bogosity {% endcomment %}
+
+</div> </div>
+
+<div class="trydart-step-details" markdown="1">
+Modify the event handler method to have different behavior for the button:
+</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 types in the input field,
+the program updates the badge with value of the input field.
+Otherwise, it uses the name 'Anne Bonney`.
+
+* Dart has common programming language constructs like `if`-`else`
+and comparison operators.
+
+</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.
+
+<div class="trydart-step-details">
+<iframe class="running-app-frame"
+        style="height:220px;width:530px;"
+        src="examples/4-classbadge/piratebadge.html">
+</iframe>
+</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:math';
+{% endprettify %}
+</div>
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* Import dart:math to get constants such as PI and the
+<a href="https://api.dartlang.org/dart_math/Random.html" target="_blank">Random</a>
+class, which provides a pseudo-random number generator.
+
+</div></div>
+
+<div class="trydart-step-details">
+At the end of the file, add all of this code.
+</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">
+
+* Class definition.
+
+* Instance variable declaration.
+
+* Private variables start with underscore (`_`).
+
+* Getters and setters.
+
+* Fat arrow shorthand.
+
+* Constructor with optional parameter.
+
+* List literal.
+
+</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>
+
+##Step 5: Add a check box {#step-five}
+
+In this step you add a checkbox to the app.
+The check box makes it explicit if you are generating a random name
+or from the input field.
+
+#### 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/5-checkboxbadge/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.html.
+
+<div class="trydart-step-details">
+Declare a top-level boolean variable.
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+...
+[[highlight]]bool useRandomName = false[[/highlight]]
+...
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* When the check box is selected
+`useRandomName` is true.
+
+</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" markdown="1">
+Modify the `generateBadge()` function as shown:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+void generateBadge(Event event) {
+  [[highlight]]if (useRandomName) {[[/highlight]]
+    query('#badgeName').text = new PirateName().name;
+  } else {
+    query('#badgeName').text = new PirateName(firstName: inputNameElement.value).name;
+  }
+}
+
+{% 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">
+Add a click handler for the check box:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+void useRandomNameClickHandler(MouseEvent e) {  
+  if ((e.target as CheckboxInputElement).checked) {
+    genButtonElement.disabled = false;
+    inputNameElement
+        ..disabled = true
+        ..value = ''
+        ..placeholder = '';
+    useRandomName = true;
+  } else {
+    genButtonElement.disabled = true;
+    inputNameElement
+        ..disabled = false
+        ..placeholder = 'Your name here';
+    useRandomName = false;
+  }
+}
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+* 'as' typecast operator.
+
+* Cascading operators.
+
+&nbsp; {% comment %} non-breaking space required for bootstrap/markdown bogosity {% endcomment %}
+
+</div> </div>
+
+##Step 6: Read names from JSON-encoded file {#step-six}
+
+In this step you change the PirateName class to get
+the list of names and appellations from a JSON file.
+
+#### Try it!
+
+<div class="trydart-step-details">
+Select the check box, click one of the radio buttons,
+then click the button.
+</div>
+
+<div class="trydart-step-details">
+<iframe class="running-app-frame"
+        style="height:220px;width:530px;"
+        src="examples/7-piratebadge_json/piratebadge.html">
+</iframe>
+</div>
+
+#### <i class="icon-anchor"> </i> Edit piratebadge.dart.
+
+<div class="trydart-step-details">
+Add this line of code to the `main()` function
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+...
+PirateName.initialize();
+...
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* Say something about static functions to initialize the class.
+
+</div> </div>
+
+<div class="trydart-step-details">
+Replace the lists with these static lists:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+class PirateName {
+  ...
+
+  static List<String> names = [];
+  static List<String> captains = [];
+  static List<String> scallywags = [];
+}
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* Say something about static.
+
+</div> </div>
+
+<div class="trydart-step-details">
+Add this code to the PirateName class:
+</div>
+
+<div class="row"> <div class="span7">
+
+<div class="trydart-step-details">
+{% prettify dart %}
+class PirateName {
+  ...
+
+  static void initialize() {
+    makeRequest();
+  }
+  
+  static void makeRequest(/*Event e*/) {
+    var path = 'piratenames.json';
+    HttpRequest.getString(path)
+        .then(processString)
+        .catchError(handleError);
+  }
+
+  static handleError(Exception error) {
+    print('Request failed.');
+  }
+
+  static processString(String jsonString) {
+    List<List> pirateNames = JSON.decode(jsonString);
+    names = pirateNames[0];
+    captains = pirateNames[1];
+    scallywags = pirateNames[2];
+  }
+
+}
+{% endprettify %}
+</div>
+
+</div> <div class="span5" markdown="1">
+
+<i class="icon-key"> </i> <strong> Key Information </strong>
+
+* Say something about HttpRequest.
+
+</div> </div>