Update polymer tutorial; make directory paths match new sample structure

src/site/docs/tutorials/polymer-intro/index.markdown

Index: src/site/docs/tutorials/polymer-intro/index.markdown
diff --git a/src/site/docs/tutorials/polymer-intro/index.markdown b/src/site/docs/tutorials/polymer-intro/index.markdown
index b1b6e74215eed26410820ed47900f96a8562c48d..0a437671fe66a0ccbe57d1a15efa2016dad7d383 100644
--- a/src/site/docs/tutorials/polymer-intro/index.markdown
+++ b/src/site/docs/tutorials/polymer-intro/index.markdown
@@ -49,7 +49,7 @@ within semantically meaningful HTML.
 <aside class="alert">
 <strong>Version Note:</strong> The code sample and the content
 of this tutorial are compatible with
-<a href="https://pub.dartlang.org/packages/polymer#versions">polymer.dart 0.9</a>.
+<a href="https://pub.dartlang.org/packages/polymer#versions">polymer.dart 0.10.</a>.
 </aside>
 
 <aside class="alert alert-info">
@@ -60,7 +60,6 @@ a new type of library for the web based on Web Components.
 <a href="http://www.dartlang.org/polymer-dart/"
    target="_blank">Polymer.dart</a>
 is the Dart implementation of Polymer.
-(Note: Polymer supersedes Web UI.)
 </aside>
 
 * [An example](#an-example)
@@ -74,6 +73,7 @@ is the Dart implementation of Polymer.
 * [Using data binding](#data-binding) 
 * [Setting up event handlers declaratively](#event-handlers) 
 * [Styling a custom element](#scoped-css)
+* [Deploying an app that uses Polymer](#deploying-an-app-that-uses-polymer)
 * [Other resources](#other-resources)
 * [What next?](#what-next)
 
@@ -89,14 +89,16 @@ Reset the stopwatch to 00:00 using the **Reset** button.
 
 <iframe class="running-app-frame"
         style="height:220px;width:230px;"
-        src="examples/stopwatch/out/web/index.html">
+        src="examples/stopwatch/web/index.html">
 </iframe>
 
 To place this custom element on an HTML page,
-import the file with the custom element definition
+import `packages/polymer/polymer.html`
+and the HTML file with the custom element definition,
 and use the name of the element as an HTML tag:
 
 {% prettify html %}
+<link rel="import" href="packages/polymer/polymer.html">
 <link rel="import" href="tute_stopwatch.html">
 ...
 <tute-stopwatch></tute-stopwatch>
@@ -108,12 +110,6 @@ The definition of the custom element encapsulates and
 hides the implementation details,
 which as the user of the element, you care nothing about.
 
-When you use developer tools to inspect the element,
-you see just the custom element's begin and end tags.
-
-<img class="scale-img-max" src="images/dev-tools-dom.png"
-     alt="Custom element encapsulates its contents">
-
 With custom elements, you can easily create new kinds of elements
 that have semantically meaningful tags and that are easy to share,
 reuse, and read.
@@ -128,7 +124,8 @@ Three main source files implement the Stopwatch example:
   </dt>
   <dd>
     The primary HTML file for the app.
-    Includes the Polymer bootstrap script and instantiates the custom element.
+    It imports HTML files for Polymer and the custom element,
+    and it instantiates the custom element.
   </dd>
   <dt>
     tute_stopwatch.html
@@ -145,11 +142,21 @@ Three main source files implement the Stopwatch example:
 </dl>
 
 The following diagram shows the structure of the example
-app and its use of custom elements.
+app and its use of custom elements:
+
+* <span style="background: rgb(249, 238, 172);">
+  Import Polymer</span>
+* <span style="background: rgb(190, 249, 221);">
+  Import custom element definition</span>
+* <span style="background: rgb(209, 226, 254);">
+  Define, implement, and instantiate custom element by name</span>
+* <span style="background: rgb(242, 209, 235);">
+  Associate Dart class with custom element definition</span>
 
 <img class="scale-img-max" src="images/connections.png"
      alt="The connections between Dart and HTML">
 
+
 ##Installing Polymer.dart {#getting-polymer-dart}
 
 To use the features provided by Polymer.dart,
@@ -161,23 +168,37 @@ which describes the process in detail.
 
 In brief, to install the Polymer package:
 
-* In the application's `pubspec.yaml` file,
+<ul markdown="1"> 
+  <li markdown="1">
+In the application's `pubspec.yaml` file,
 add the package to the list of dependencies
 by adding the package name, `polymer`, to the list.
-YAML is whitespace-sensitive,
-so take care to indent the package name as shown:
 
-  <img class="scale-img-max" src="images/sample-pubspec.png"
-     alt="Sample pubspec file with polymer dependency">
+  <pre>
+name: stopwatch
+description: A sample application
+dependencies:
+  <b>polymer: ">=0.10.0 &lt;0.11.0"</b>
+  </pre>
+  </li>
 
-* Run `pub get`,
+<aside class="alert alert-warning">
+<b>Important:</b>
+YAML is whitespace-sensitive,
+so take care to indent the package name as shown.
+</aside>
+
+  <li markdown="1">
+Run `pub get`,
 which recursively installs the polymer.dart package
 and all the packages that it depends on.
 If you are using Dart Editor,
 when you save pubspec.yaml
 the editor automatically runs `pub get` for you.
-If you are using command line tools,
-you can run it with the command `pub get`.
+If you are using command-line tools,
+you can use the command `pub get`.
+  </li>
+</ul>
 
 ##Including Polymer.dart in your application {#bootstrap}
 
@@ -185,26 +206,33 @@ To use Polymer.dart features such as custom elements,
 you need to include Polymer in both
 the HTML side and the Dart side of your app.
 
-* In the primary HTML file for your app,
-export `package:polymer/init.dart` within a &lt;script&gt; tag
-in the &lt;head&gt; section.
-This script contains the `main()` function
-for the app and initializes Polymer.
-
-  <img class="scale-img-max" src="images/init-script.png"
-     alt="Include the Polymer init script">
+<aside class="alert alert-warning">
+<b>Important:</b>
+Unlike other Dart web apps,
+Polymer apps have no <tty>main()</tty> function
+and do not use <tty>packages/browser/dart.js</tty>.
+</aside>
 
 * In the primary HTML file for your app,
-include the `packages/browser/dart.js` bootstrap script
-in the &lt;head&gt; section.
+  import `packages/polymer/polymer.html`
+  in the the &lt;head&gt; section:
 
-  <img class="scale-img-max" src="images/bootstrap-script.png"
-     alt="Include the Polymer bootstrap script">
+  <pre>
+&lt;head>
+  ...
+  <b>&lt;link rel="import" href="packages/polymer/polymer.html"></b>
+  ...
+&lt;/head>
+  </pre>
 
 * In your Dart code, import the Polymer library:
 
-  <img class="scale-img-max" src="images/polymer-library.png"
-     alt="Import the Polymer library">
+  <pre>
+import 'dart:html';
+import 'dart:async';
+<b>import 'package:polymer/polymer.dart';</b>
+...
+  </pre>
 
 ##Instantiating a custom element {#instantiating}
 
@@ -256,7 +284,8 @@ A custom element with a template and no script is purely visual.
   <template>
     ...
   </template>
-  <script type="application/dart" src="tute_stopwatch.dart">
+  <script type="application/dart;component=1"
+          src="tute_stopwatch.dart">
   </script>
 </polymer-element>
 {% endprettify %}
@@ -279,6 +308,8 @@ A custom element with a template and no script is purely visual.
     life-cycle methods and provides event handlers
     that join the UI with its programmatic behavior.
     In this example, the script is in tute_stopwatch.dart.
+    The script type for custom elements must be
+    "application/dart;component=1".
   </dd>
 </dl>
 
@@ -298,7 +329,7 @@ The rest of the code within the &lt;template&gt; tag
 is normal HTML, with two exceptions:
 
 |---|---|
-| `{``{``counter}}` | Uses a Polymer syntax to [bind Dart data](#data-binding) to the HTML page. The double curly braces are commonly known as a "double mustache". |
+| `{``{`<em><code>expression</code></em>`}}` | Uses a Polymer syntax to [bind Dart data](#data-binding) to the HTML page. The double curly braces are commonly known as a "double mustache". |
 | `on-click` | Uses Polymer [declarative event mapping](#event-handlers), which allows you to set up event handlers for a UI element. `on-click` sets up an event handler for mouse clicks. Polymer has mappings for other event types, such as `on-input` for changes to text fields. |
 {: .table}
 
@@ -320,7 +351,25 @@ This diagram gives an overview of the TuteStopwatch class:
 <img class="scale-img-max" src="images/dart-script-code.png"
      alt="The script code for the tute-stopwatch element">
 
-Any Dart class that backs a Polymer element must subclass PolymerElement.
+Classes that back Polymer elements are usually subclasses of PolymerElement,
+but they don't have to be.
+They can extend any other HtmlElement subclass,
+as long as they implement
+<a href="https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/polymer/polymer.Polymer">Polymer</a> and
+<a href="https://api.dartlang.org/observe/observe.Observable">Observable</a> (typically as mixins)
+and provide a constructor named <code><em>CustomElement</em>.created()</code>
+that invokes `super.created()` and
+(if using Polymer as a mixin) `polymerCreated()`.
+**{PENDING: true?}**

[Siggi Cherem (dart-lang), 2014/05/28 19:00:21]

Yes, the paragraph above seems accurate. A couple notes: 
- you can define custom-elements without polymer, they are just not going to
have any of the fancy features like data-binding built in.
- we may want to highlight that if you mixin Polymer, the call to polymerCreated
is practically mandatory - without it, bindings and other features will not work
properly.
- People find it useful to see an example where you extend elements that already
have a basic style or use, for example if you were to extend <li>:

@CustomTag('my-li')
class MyLI extends LIElement with Polymer, Observable {
  MyLI.created() : super.created() {
    polymerCreated();
  }
}

[Kathy Walrath, 2014/05/29 21:14:15]

Done.

+As an example, here's the code for PolymerElement:
+
+{% prettify dart %}
+class PolymerElement extends HtmlElement with Polymer, Observable {
+  PolymerElement.created() : super.created() {
+    polymerCreated();
+  }
+}
+{% endprettify %}
 
 {% comment %}
 [xx: more about PolymerElement]
@@ -338,19 +387,21 @@ Refer to [Setting up event handlers declaratively](#event-handlers) to see how.
 
 ##Overriding life-cycle methods {#life-cycle-methods}
 
-A custom element has four life-cycle methods
+A custom element has a constructor and three life-cycle methods
 that it can override:
 
 |---|---|
-| `created()` | Called when an instance of a custom element is created. |
+| <code><em>CustomElement</em>.created()</code> | The constructor used when creating an instance of a custom element. |
 | `enteredView()` | Called when an instance of a custom element is inserted into the DOM. |

[Siggi Cherem (dart-lang), 2014/05/28 19:00:21]

enteredView/leftView got renamed. They are still around, but deprecated. The new
names are:
- attached (was enteredView)
- detached (was leftView)

[Kathy Walrath, 2014/05/29 21:14:15]

Done.

 | `leftView()` | Called when an instance of a custom element is removed from the DOM. |
 | `attributeChanged()` | Called when an attribute, such as `class`, of an instance of the custom element is added, changed, or removed. |
 {: .table}
 
-You can override any of these life-cycle methods.
-The overriding method
-*must* call the super class method first.
+You can implement the constructor,
+if necessary,
+and override any of the life-cycle methods.
+The constructor or overriding method
+*must* call the superclass constructor or method first.
 
 The Stopwatch app overrides the `enteredView()` method because it
 needs a reference to each of the three buttons
@@ -501,6 +552,86 @@ For further details about styling custom elements,
 refer to
 [A Guide to Styling Elements](http://www.polymer-project.org/articles/styling-elements.html)
 
+
+##Deploying an app that uses Polymer
+
+To convert your app to JavaScript
+that you can deploy to the web,
+you need to use the Polymer transformers.
+You can test your app's JavaScript version using
+either Dart Editor's **Run as JavaScript** command
+or the `pub serve` command.
+To produce deployable files,
+use the `pub build` command.
+
+###Specifying transformers
+
+Add a `transformers` entry to your app's `pubspec.yaml` file
+to specify the Polymer transformers:
+
+{% prettify yaml %}
+...
+dependencies:
+  polymer: ">=0.10.0 <0.11.0"
+transformers:
+- polymer
+{% endprettify %}
+
+By default, Polymer assumes that all files under `web` can be
+_entry points_—**{PENDING: define entry point here}**.

[Siggi Cherem (dart-lang), 2014/05/28 19:00:21]

That would be practically the equivalent of an app: a page you intend to serve,
not an individual custom-element.

It's the equivalent of a file with a 'main' in Dart, but for HTML.

[Kathy Walrath, 2014/05/29 21:14:15]

What if you have a secondary page—one that you show only sometimes, and maybe
only after showing another page? Would that secondary page be an entry point?

On 2014/05/28 19:00:21, Siggi Cherem (dart-lang) wrote:

[Kathy Walrath, 2014/05/29 21:14:15]

Done.

[Siggi Cherem (dart-lang), 2014/05/29 22:21:21]

Yes - basically anything you'll serve up and expect the user will point the
browser directly at.

+You can use an `entry_points` field to limit the HTML files that
+the Polymer transformers process.
+For example:
+
+{% prettify yaml %}
+...
+transformers:
+- polymer:
+    entry_points: web/index.html
+{% endprettify %}
+
+<aside class="alert alert-warning">
+<b>Important:</b>
+YAML is whitespace-sensitive,
+so take care to indent the <tty>entry_points</tty> field as shown.
+</aside>
+
+For more information on using the Polymer transformers, see the
+[Polymer package documentation](http://pub.dartlang.org/packages/polymer).
+
+###Testing the JavaScript version
+
+If you're using Dart Editor,
+you can test the JavaScript version in your default web browser
+by right-clicking your app's main file
+(for example, web/index.html)
+and choosing **Run as JavaScript**.

[Siggi Cherem (dart-lang), 2014/05/28 19:00:21]

I just realized one thing. Starting in SDK 1.5 the editor relies on using
pub-serve as the default development server when you launch Dartium. So that
means that these transformers will also be run even early when you are just
developing and not deploying your application.

Polymer is designed to support running apps in Dartium without any transformers,
or after running the transformers, though. 

Not sure if you want to mention that here or somewhere else in the article. 

[Kathy Walrath, 2014/05/29 21:14:15]

I'll leave out that detail for now.

Will running the transformers slow down Dart Editor or the dev cycle?

On 2014/05/28 19:00:21, Siggi Cherem (dart-lang) wrote:

[Siggi Cherem (dart-lang), 2014/05/29 22:21:21]

A little bit - the first launch is slower, subsequent refreshes might not be
noticeable. 

+A browser tab opens containing your running app.
+You can copy the URL from that tab into any other browser
+that you'd like to test.
+
+Alternatively, run `pub serve`
+on the command line,
+from the app's top directory.
+That command runs the Polymer transformers on the app
+and starts up an HTTP server to serve the app.
+The command's output gives you a URL that you can
+copy and paste into a browser window.
+If you change the app's files and reload the window,
+you see the updated version of the app.
+
+
+###Generating JavaScript files
+
+When you're ready to generate files,
+run `pub build`—either at the command line or
+using Dart Editor—to
+generate the files your app needs
+to run in any modern browser.
+The generated files appear in the
+`build` directory, alongside your `pubspec.yaml` file.
+
+
 ##Other resources
 
 Use these other resources to learn more about Polymer: