Update polymer tutorial; make directory paths match new sample structure

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

 ---
 layout: tutorial
 title: "Define a Custom Element"
 description: "Create a custom HTML element using Polymer."
 has-permalinks: true
 tutorial:
   id: polymer-intro
 next: futures/
 next-title: "Use Future-Based APIs"
 prev: shared-pkgs/
@@ skipping 31 matching lines @@
 <h3>Create a custom HTML element using Polymer</h3>
 </div>
 
 A custom element is an HTML element you can define yourself,
 encapsulating appearance and/or behavior
 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">
   Custom elements are one feature of
 <a href="http://www.polymer-project.org/"
    target="_blank">Polymer</a>,
 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)
 * [Installing Polymer.dart](#getting-polymer-dart) 
 * [Including Polymer.dart in your application](#bootstrap)
 * [Instantiating a custom element](#instantiating) 
 * [Defining a custom element](#define-element) 
 * [Providing a template for the custom element](#providing-a-template) 
 * [Providing a script for the custom element](#providing-a-script) 
 * [Overiding life-cycle methods](#life-cycle-methods)
 * [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)
 
 ##An example
 
 In the example running below,
 the LemonChiffon area outlined in black
 is a custom element implemented using Polymer.
 
 <strong>Try it!</strong>
 Start and stop the stopwatch.
 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>
 {% endprettify %}
 
 The counting text, the three buttons along with their actions,
 and the style are all contained within the custom element.
 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.
 
 ###Overview of the example files
 
 Three main source files implement the Stopwatch example:
 
 <dl>
   <dt>
     index.html
   </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
   </dt>
   <dd>
     The HTML code that defines the custom element.
   </dd>
   <dt>
     tute_stopwatch.dart
   </dt>
   <dd>
     The Dart class that implements the custom element.
   </dd>
 </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,
 you need to install the Polymer package.
 If you are unfamiliar with installing packages,
 refer to
 <a href="/docs/tutorials/shared-pkgs/">Install Shared Packages</a>,
 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.
+
+  <pre>
+name: stopwatch
+description: A sample application
+dependencies:
+  <b>polymer: ">=0.10.0 &lt;0.11.0"</b>
+  </pre>
+  </li>
+
+<aside class="alert alert-warning">
+<b>Important:</b>
 YAML is whitespace-sensitive,
-so take care to indent the package name as shown:
+so take care to indent the package name as shown.
+</aside>
 
-  <img class="scale-img-max" src="images/sample-pubspec.png"
-     alt="Sample pubspec file with polymer dependency">
-
-* Run `pub get`,
+  <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}
 
 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}
 
 To create an instance of a custom element,
 use the name of the custom element just as you would any normal HTML tag.
 In this example, the tag name is `tute-stopwatch`.
 
 <img class="scale-img-max" src="images/polymer-instance-create.png"
      alt="Instantiate a custom element with a custom tag">
 
@@ skipping 31 matching lines @@
 typically have both a template and a script,
 but neither is required.
 A custom element with a script and no template is purely functional.
 A custom element with a template and no script is purely visual.
 
 {% prettify html %}
 <polymer-element name="tute-stopwatch">
   <template>
     ...
   </template>
-  <script type="application/dart" src="tute_stopwatch.dart">
+  <script type="application/dart;component=1"
+          src="tute_stopwatch.dart">
   </script>
 </polymer-element>
 {% endprettify %}
 
 <dl>
   <dt> &lt;template&gt; </dt>
   <dd>
     Describes the custom element's structure&mdash;its user interface.
     The template comprises any valid HTML code within the &lt;template&gt; tag.
     When the custom element is instantiated,
     the instance is created from the template.
     The template can include CSS styles within a &lt;style&gt; tag.
   </dd>
 
   <dt> &lt;script&gt; </dt>
   <dd markdown="1"> Specifies a Dart script.
     For custom elements, the Dart script is a Dart class
     that implements the behavior of the element.
     The class typically overrides some
     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>
 
 ##Providing a template for the custom element {#providing-a-template}
 
 Here's the template code for the tute-stopwatch element:
 
 <img class="scale-img-max" src="images/template-code.png"
      alt="The template code for the tute-stopwatch element">
 
 The tute-stopwatch template uses a &lt;style&gt; tag, which is optional.
 These styles are scoped; they affect only
 the appearance of the custom element and the elements it contains.
 More about scoped CSS in [Styling a custom element](#scoped-css).
 
 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}
 
 Let's take a look at the structure of the Dart code
 before we get into the details of data binding, event handlers,
 and scoped CSS.
 
 ##Providing a script for the custom element {#providing-a-script}
 
 On the Dart side, a class implements the behavior of the custom element.
 You associate the Dart class with the custom element using the `@CustomTag`
 annotation and the name of the custom element.
 
 <img class="scale-img-max" src="images/polymer-element-definition.png"
      alt="Two parts to a custom element definition">
 
 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]
 {% endcomment %}
 
 The class can respond to life-cycle milestones
 by overriding [life-cycle methods](#life-cycle-methods).
 For example, the TuteStopwatch class overrides the `enteredView()`
 method—which is called when the element is inserted
 into the DOM—to initialize the app.
 
 The `start()` method is an event handler for the **Start** button.
 The event handler is declaratively connected to the button.
 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
 so that it can enable and disable them.
 When a tute-stopwatch custom element is inserted into the DOM
 the buttons have been created, so the references to them
 will be available when the enteredView() method is called.
 
 {% prettify dart %}
 void enteredView() {
@@ skipping 42 matching lines @@
 
 You can use expressions within the double curly brackets.
 <a href="http://pub.dartlang.org/packages/polymer_expressions"
    target="_blank">Polymer expressions</a>
 provide the default syntax. Examples of allowable expressions include:
 
 |---|---|
 | `{``{``myObject.aProperty}}` | Property access. |
 | `{``{``!empty}}` | Operators, like the logical not operator. |
 | `{``{``myList[3]}}` | List indexing. |
 | `{``{``myFilter()}}` | Data filtering. |

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

let's remove this line - the syntax changed to "exp | myFilter", but it seems
that it my change again to "myFilter(exp)", so it might be just fine to keep
this out of this discussion while this settles down.

Here is a relevant discussion about it:

https://groups.google.com/a/dartlang.org/d/msgid/web/CAEKsHmD4fC7av%3DYS7x1fH...

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

Done.

 {: .table}
 
 ##Setting up event handlers declaratively {#event-handlers}
 
 This example has three buttons, each
 with an event handler that is written in Dart,
 but attached to the button declaratively from HTML.
 
 <img class="scale-img-max" src="images/click-handler.png"
      alt="Declaratively attach a click handler">
@@ skipping 67 matching lines @@
 You can style elements within the custom element using
 the appropriate selectors for those elements.
 You don't need to worry about naming conflicts on the page.
 Any CSS selectors used within the &lt;style&gt; section
 apply only to those elements within the template.
 
 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:
 
 * The
 <a href="http://www.dartlang.org/polymer-dart/"
    target="_blank">Polymer.dart</a> homepage provides information
    specific to the Dart port of the Polymer project.
 
 * The Polymer project website
@@ skipping 16 matching lines @@
 
 The next tutorial,
 [Fetch Data Dynamically](/docs/tutorials/fetchdata/),
 shows you how to fetch data
 and use JSON to encode and decode
 that data.
 
 {% endcapture %}
 
 {% include tutorial.html %}