almost first draft of polymer target

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

+---
+layout: default
+title: "Polymer Elements"
+description: "Use Polymer.dart to build better UIs with less code."
+has-permalinks: true
+tutorial:
+  id: polymer-intro
+next: fetchdata
+next-title: "Fetch Data Dynamically"
+prev: custom-elements
+prev-title: "Define a Custom DOM Tag"
+---
+
+{% capture whats_the_point %}
+
+* Polymer.dart is the next evolution of Web UI.
+* Everything in Polymer.dart is an element.
+* Use Polymer.dart to build custom tags.
+* Bind Dart data to HTML elements.
+* Declaratively bind event handlers to elements.
+
+{% endcapture %}
+
+{% capture sample_links %}
+
+<p>
+Get the source code for the samples featured in this target:</p>
+
+<ul>
+  <li>
+    <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/target06-polymer/stopwatch"
+       target="_blank">stopwatch</a>
+  </li>
+</ul>
+
+{% endcapture %}
+
+{% capture content %}
+
+<div class="tute-target-title">
+<h1>{{page.title}}</h1>
+<h3>Create new DOM tags with Polymer elements</h3>
+</div>
+
+<div id="under-construction" markdown="1">
+<h3> <i class="icon-wrench"> </i> Under construction </h3>
+
+This is a draft under construction.
+Your kindly worded
+<a
+ href="http://code.google.com/p/dart/issues/entry?template=Tutorial%20feedback"
+ target="_blank">
+comments and suggestions
+</a>
+are appreciated.
+Thank you for your patience.
+</div>
+
+Polymer elements are one feature of the
+<a href="http://www.polymer-project.org/">Polymer</a> project,
+whose primary aim is to help manage the complexity
+of building web applications.
+<a href="http://www.dartlang.org/polymer-dart/">Polymer.dart</a>
+is the Dart implementation of Polymer.
+
+A Polymer element is a customized element you can define yourself,
+encapsulating appearance and/or behavior within semantically meaningful DOM tags.
+
+* [An example](#an-example)
+* [Installing Polymer.dart](#getting-polymer-dart) 
+* [Including Polymer.dart in your application](#bootstrap)
+* [Instantiating a Polymer element](#instantiating) 
+* [Defining a Polymer element](#define-element) 
+* [Providing a template for the Polymer element](#providing-a-template) 
+* [Providing a script for the Polymer element](#providing-a-script) 
+* [Life-cycle methods](#life-cycle-methods)
+* [One-way data binding](#one-way-data-binding) 
+* [Setting up event handlers declaratively](#event-handlers) 
+* [Shadow DOM](#in-the-shadows) 
+* [Scoped CSS in a Polymer element](#scoped-css)
+* [Other resources](#other-resources)
+
+##An example
+
+In the example running below,
+the area within the black rectangle is implemented by a Polymer element,
+
+<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:175px;width:202px;"
+        src="http://dart-lang.github.com/dart-tutorials-samples/web/target06/stopwatch/web/out/stopwatch.html">
+</iframe>
+
+To place this Polymer element on an HTML page, you write:
+
+{% prettify html %}
+<tute-stopwatch></tute-stopwatch>
+{% endprettify %}
+
+The counting text, the three buttons along with their actions,
+and the style are all encapsulated within the Polymer element.
+The definition of the Polymer element encapsulates and
+hides the implementation details,
+which as the user of the element, you care nothing about.
+
+When you use tools to inspect the element,
+you see just the Polymer element's begin and end tag.
+The contents of the Polymer element are hidden in the *shadow DOM*.
+
+![Polymer element encapsulates its contents](images/dev-tools-dom.png)
+
+With Polymer elements, developers can easily share and use elements
+with semantically meaningful tags that are easy to share,
+re-use, and read.
+
+###Overview of the example files
+
+Three primary source files implement the stopwatch example:
+
+<dl>
+  <dt>
+    <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/target06-polymer/stopwatch/web/index.html" target="_blank">index.html</a>
+  </dt>
+  <dd>
+    The primary HTML file for the app.
+    Includes the Polymer bootstrap script and instantiates the Polymer element.
+  </dd>
+  <dt>
+    <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/target06-polymer/stopwatch/web/tute_stopwatch.html" target="_blank">tute_stopwatch.html</a>
+  </dt>
+  <dd>
+    The HTML code that defines the Polymer element.
+  </dd>
+  <dt>
+    <a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web/target06-polymer/stopwatch/web/tute_stopwatch.dart" target="_blank">tute_stopwatch.dart</a>
+  </dt>
+  <dd>
+    The Dart class that implements the Polymer element.
+  </dd>
+</dl>
+
+The following diagram shows the structure of the example
+app and its use of Polymer elements.
+
+![The connections between Dart and HTML](images/connections.png)
+
+##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,
+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:
+
+  ![Sample pubspec file with polymer dependency](images/sample-pubspec.png)
+
+* If you are using Dart Editor,
+when you save pubspec.yaml
+the editor automatically runs `pub install`.
+If you are using command line tools,
+you can run it with the command `pub install`.
+The installation process
+recursively installs the polymer.dart package
+and all the packages that it depends on.
+
+##Including Polymer.dart in your application {#bootstrap}
+
+To use Polymer.dart features, such as Polymer elements,
+you need to include Polymer in both
+the HTML side and in the Dart side of your app.
+
+* In the primary HTML file for your app,
+you must include `packages/polymer/boot.js`
+in the &lt;head&gt; section.
+When using this script,
+you do not need to include a top-level `main()` function,
+although you may.
+**Note:** Use this script in lieu of `packages/browser/dart.js`.
+
+  ![Include the Polymer bootstrap script](images/bootstrap-script.png)
+
+* Each Dart file that uses Polymer features
+needs to import the Polymer library:
+
+  ![Import the Polymer library](images/polymer-library.png)
+
+##Instantiating a Polymer element {#instantiating}
+
+To create an instance of the Polymer element,
+use the name of the Polymer element just as you would any normal HTML tag.
+In this example, the tag name is `tute-stopwatch`.
+
+![Instantiate a Polymer element with a custom tag](images/polymer-element-instantiation.png)
+
+Using best practices,
+the Polymer element definition is in a separate file
+from where it is instantiated.
+Use `link` to import the HTML definition file as shown.
+
+##Defining a Polymer element {#define-element} 
+
+The definition for the tute-stopwatch element is
+in `tute-stopwatch.html`.
+A Polymer element definition should be in its own
+source file so that it can be included by other files.
+
+To define a Polymer element,
+use the &lt;polymer-element&gt; tag and provide a name.
+
+{% prettify html %}
+<polymer-element name="tute-stopwatch">
+  ...
+</polymer-element>
+{% endprettify %}
+
+A Polymer element name must have at least one hyphen (`-`).
+We advise using an identifiable prefix to 
+avoid naming conflicts with elements shared by others
+and to help identify the project from which the element originates.
+For example, for all tutorial polymer elements, we use the prefix `tute`.
+
+Within the &lt;polymer-element&gt; tag,
+you can provide a template (appearance) and a script (behavior).
+UI widgets, like our stopwatch example,
+typically have both a template and a script.
+But neither is required.
+A polymer element with a script and no template is purely functional,
+for example a [xx].
+A polymer element with a template and no script is purely visual,
+for example a [xx].
+
+{% prettify html %}
+<polymer-element name="tute-stopwatch">
+  <template>
+    ...
+  </template>
+  <script type="application/dart" src="tute_stopwatch.dart">
+  </script>
+</polymer-element>
+{% endprettify %}
+
+<dl>
+  <dt> &lt;template&gt; </dt>
+  <dd>
+    Describes the element's structure&mdash;its user interface.
+    The template comprises any valid HTML code within the &lt;template&gt; tag.
+    The template is rendered when a Polymer element is instantiated.
+    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 Polymer elements, the Dart script is a Dart class
+    that implements the behavior of the element.
+    Life-cycle methods and event handlers join the UI with the Dart code.
+    In this example, the script is in the `tute_stopwatch.dart` file.
+  </dd>
+</dl>
+
+##Providing a template for the Polymer element {#providing-a-template}
+
+Here's the template code for the tute-stopwatch element:
+
+![The template code for the tute-stopwatch element](images/template-code.png)
+
+The tute-stopwatch template uses a &lt;style&gt; tag, which is optional.
+These styles are scoped; they affect only
+the appearance of the Polymer element and the elements it contains.
+More about this in [Scoped CSS in a Polymer element](#scoped-css).
+
+The rest of the code within the template tag
+is normal HTML with two exceptions:
+
+* {% raw %}`{{counter}}`{% endraw %}--a Polymer syntax for
+[one-way data binding](#one-way-data-binding).
+
+* `on-click`--a Polymer element attribute that lets you
+[declaratively attach a mouse click handler](#event-handlers).
+to UI elements, such as buttons.
+Polymer has other attributes for other event types, such as `on-change`.
+
+Let's take a look at structure of the Dart code
+before we get into the details of data binding
+and event handlers.
+
+##Providing a script for the Polymer element {#providing-a-script}
+
+[xx: this is an important section. make it better. slow it down.
+explain things better. What do you get with PolymerElement?
+What do you get with ObservableMixin?]
+
+The stopwatch example provides the Dart script for the custom
+element in a separate file called `tute-stopwatch.dart`.
+The Dart script is a class that provides the implementation
+for the life-cycle events and event handlers for the Polymer element.
+This diagram gives an overview of the TuteStopwatch class:
+
+![The script code for the tute-stopwatch element](images/dart-script-code.png)
+
+When you define a Polymer element you give it a name using the `name` attribute.
+On the Dart side, a class implements the behavior of the Polymer element.
+You associate the Dart class with the Polymer element using the `@CustomTag`
+annotation and the name of the Polymer element.
+
+![Two parts to a Polymer element definition](images/polymer-element-definition.png)
+
+Any Dart class that backs a polymer element
+must subclass PolymerElement.
+
+[xx: more about PolymerElement]
+
+[xx: more about ObservableMixin]
+
+The class may override one of several [life-cycle methods](#life-cycle-methods)
+such as the inserted() method you see overridden here.
+
+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.
+
+##Life-cycle methods {#life-cycle-methods}
+
+The inserted() method is one of four Polymer element life-cycle methods:
+
+* created(): called when an instance of a Polymer element is created.
+
+* inserted(): called when an instance of a Polymer element is
+inserted into the DOM.
+
+* removed(): called when an instance of a Polymer element is
+removed from the DOM.
+
+* attributeChanged(): called when an attribute, such as `class`,
+of an instance of the Polymer element is added, changed, or removed.
+
+You can override any of these life-cycle methods.
+The overriding method
+*must* call the super class methods first.
+
+The stopwatch example overrides the inserted() method
+to initialize the app.
+The app needs a reference to each of the three buttons
+so that it can enable and disable the buttons
+as appropriate for the state of the app.
+You'll notice that it gets the buttons by querying
+its [shadow DOM](#in-the-shadows).
+
+##One-way data binding {#one-way-data-binding}
+
+In HTML, use double curly brackets to embed Dart data into your webpage.
+In Dart use the `@observable` annotation in the Dart code
+to mark the embedded data.
+Here, the data is a string called `counter`.
+
+![One-way data binding](images/one-way-data-binding.png)
+
+This little program uses a periodic Timer to fire an event every second.
+When the Timer fires, it calls the `updateTImer` callback function,
+which modifies the `counter` string.
+Polymer updates the bound area on the HTML page.
+
+This type of binding is called _one-way data binding_
+because the data can change only on the Dart side.
+Polymer also supports two-way data binding
+in which the data can be changed on the HTML side,
+perhaps with a type of input element,
+and it changes the value in the Dart code.
+
+You can use expressions within the double curly brackets.
+<a href="http://pub.dartlang.org/packages/polymer_expressions">Polymer expressions</a>
+provide the default syntax.
+
+Examples include:
+
+[xx: include some examples of Polymer expressions]
+
+##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.
+
+![Declaratively attach a click handler](images/click-handler.png)
+
+In HTML, use the `on-click` attribute
+to attach a mouse click handler to an HTML element.
+The value of the attribute is the name of a method
+in the class that implements the Polymer element.
+When the user clicks the button the named method is called
+with three parameters:
+
+* the event, which contains information about the event,
+such as [xx what is of interest here]
+
+* detail, which as far as I can tell is never used
+
+* and Node, which is the element which fired the event,
+the **Start** button in this case.
+
+You can attach other types of event handlers to other types of input elements.
+For example, you can use `on-change` to handle events for input text elements
+when the text changes.
+
+##Shadow DOM {#in-the-shadows}
+
+Hey! Remember we mentioned the shadow DOM earlier.
+Now we get to bring it out of the shadows.
+
+The Shadow DOM is key to encapsulation.
+The DOM tree for a Polymer element is in the shadows,
+hidden from outside of the Polymer element
+(unless the Polymer element chooses to reveal them).
+
+![Shadow DOM for tute-stopwatch Polymer element](images/shadow-dom.png)
+
+You can programmatically get items from the shadow DOM
+by querying a Polymer element's shadow root.
+
+{% prettify dart %}
+startButton = getShadowRoot("tute-stopwatch").query('#startbutton');
+stopButton = getShadowRoot("tute-stopwatch").query('#stopbutton');
+resetButton = getShadowRoot("tute-stopwatch").query('#resetbutton');
+{% endprettify %}
+
+Call `getShadowRoot` with the name of the Polymer element.
+[xx: getShadowRoot returns the shadow root for 'this' instance of
+the element named]
+Then use `query` with a CSS selector to get the element(s) of interest.
+
+Note that this code queries for each button using the button's id.
+By querying the shadow root object,
+you are guaranteed to get the objects from within the Polymer element,
+not from anywhere else on the page.
+
+##Scoped CSS in a Polymer element {#scoped-css} 
+
+You can optionally include CSS styles for your Polymer element
+that applies to the contents of the Polymer element.
+
+![Scoped CSS styleing](images/css-styling.png)
+
+The primary div element within the template has an id `stopwatch_container`.
+The styles within the template apply only to the template.
+So any ID within the template need only be unique within the template.
+You don't need to worry about naming conflicts on the page.
+
+##Other resources
+
+* We converted all tutorial examples that previously used Web UI
+to use Polymer instead.
+Checkout the 
+<a href="https://github.com/dart-lang/dart-tutorials-samples/tree/master/web">github repo</a>
+to find the source code for all of the Polymer examples.
+
+* Check out the
+<a href="http://www.dartlang.org/polymer-dart/">Polymer.dart</a>
+home page.
+
+* Check out the Polymer project website at
+<a href="http://www.polymer-project.org/">polymer-project.org</a>.
+
+* The next target is going to talk about other nifty polymer.dart features like
+two-way data binding, xtag, and the &lt;content&gt; tag and shadow DOM.
+Aren't you excited?
+
+Wahoo!
+
+Go write some code.
+
+{% endcapture %}
+
+{% include tutorial.html %}