Merge branch 'prtksxna-doc'

ebidel · ebidel · commit c6e56d56a1ee · 2014-06-29T13:01:12.000-07:00
diff --git a/docs/polymer/binding-types.md b/docs/polymer/binding-types.md
@@ -12,18 +12,18 @@ subtitle: Data-binding
 There are several ways to bind data to a template. You can:
 
 *   Create a single instance of a template, by specifying a single object using the `bind` attribute.
-*   Create multiple instances of a template, by specifying an array of objects using the `repeat` 
+*   Create multiple instances of a template, by specifying an array of objects using the `repeat`
      attribute.
 *   Conditionally create an instance of a template, depending on whether the value passed to the `if`attribute is truthy.
 
-**Note:** Binding templates only works inside {{site.project_title}} elements. For example, if a 
-`<template>` element is inserted directly into a page’s `<body>` tag, the `bind` attribute 
-doesn’t work as described here. If you need to use template binding outside of a 
-{{site.project_title}} element, see [Using data binding outside of a {{site.project_title}} element](/docs/polymer/databinding-advanced.html#bindingoutside). 
+**Note:** Binding templates only works inside {{site.project_title}} elements. For example, if a
+`<template>` element is inserted directly into a page’s `<body>` tag, the the `bind` attribute
+doesn’t work as described here. If you need to use template binding outside of a
+{{site.project_title}} element, see [Using data binding outside of a {{site.project_title}} element](/docs/polymer/databinding-advanced.html#bindingoutside).
 {: .alert .alert-info }
 
-When you use a binding _inside_ a template, you create a _node binding_, which binds a model value to a 
-DOM node. Node bindings are interpreted by the node, based on the element type and where the binding 
+When you use a binding _inside_ a template, you create a _node binding_, which binds a model value to a
+DOM node. Node bindings are interpreted by the node, based on the element type and where the binding
 occurs. See [Node bindings](#node-bindings) for details.
 
 ## Single template instances
@@ -37,9 +37,9 @@ Using the `bind` attribute, you can create a single instance of a template bound
     </template>
 {% endraw %}
 
-Where `person` is an object (or more accurately, a [{{site.project_title}} expression](#expressions) that yields an object).
+Where `person` is an object (or more accurately, a [{{site.project_title}} expression](/docs/polymer/expressions.html) that yields an object).
 
-Bindings inside the template are evaluated in the context of the bound object. For example, 
+Bindings inside the template are evaluated in the context of the bound object. For example,
 if `person` has a property, `name`, {%raw%}`{{name}}`{%endraw%} evaluates to the value of `person.name`.
 
 For convenience, you can also create a _named scope_ when binding an object:
@@ -51,7 +51,7 @@ For convenience, you can also create a _named scope_ when binding an object:
     </template>
 {% endraw %}
 
-In this case, you can use the named scope `p` to access the properties of the `person` object. 
+In this case, you can use the named scope `p` to access the properties of the `person` object.
 Named scopes can be handy when nesting templates.
 
 
@@ -131,7 +131,7 @@ Conditional templates use the `if` attribute to conditionally create a template
     </template>
 {% endraw %}
 
-The conditional template can be explicitly bound to an object using the 
+The conditional template can be explicitly bound to an object using the
 {%raw%}`bind={{expression}}`{%endraw%} syntax.
 
 Where the explicit binding is omitted, a nested template can inherit the scope of
@@ -145,7 +145,7 @@ the containing template. Conditional templates are frequently used this way:
     </template>
 {% endraw %}
 
-For more information on nesting templates, see [Expression scopes](#expression-scopes).
+For more information on nesting templates, see [Expression scopes](/docs/polymer/expressions.html#expression-scopes).
 
 You can also use `if` with the  `repeat` attribute.
 
@@ -157,9 +157,9 @@ You can also use `if` with the  `repeat` attribute.
     </template>
 {% endraw %}
 
-## Importing templates by reference 
+## Importing templates by reference
 
-Sometimes, you may want to reuse a template in multiple places, or reference a template generated elsewhere. 
+Sometimes, you may want to reuse a template in multiple places, or reference a template generated elsewhere.
 That's where the `ref` attribute comes in:
 
 {% raw %}
@@ -187,7 +187,7 @@ You can use the `ref` attribute to define recursive templates, such as tree stru
     </template>
 {% endraw %}
 
-In addition, you can bind to the `ref` attribute _itself_, to choose templates dynamically: 
+In addition, you can bind to the `ref` attribute _itself_, to choose templates dynamically:
 
 {% raw %}
     <template bind ref="{{node.nodeType}}"></template>
@@ -205,13 +205,13 @@ How nodes interpret bindings depends on the _type of element_, and the _binding
 
 ### Binding to text
 
-If a binding occurs between tags, it creates a `textContent` binding to the element. 
+If a binding occurs between tags, it creates a `textContent` binding to the element.
 
 {% raw %}
     <p>This paragraph has some {{adjective}} text.</p>
 {% endraw %}
 
-All text nodes treat a `textContent` bindingas a one-way binding: changing the model changes the bound node, but imperatively changing the DOM value does _not_ update the model.
+All text nodes treat a `textContent` binding as a one-way binding: changing the model changes the bound node, but imperatively changing the DOM value does _not_ update the model.
 
 ### Binding to attributes
 
@@ -244,7 +244,7 @@ Two-way bindings are supported as a special case on some user input elements. Sp
 
 When you bind to a [published property](polymer.html#published-properties) on a {{site.project_title}} element, you get a two-way binding to the property.
 
-In the following sample, the `intro-tag` binds to a published property on the `say-hello` element: 
+In the following sample, the `intro-tag` binds to a published property on the `say-hello` element:
 
 {% raw %}
     <!-- say-hello element publishes the 'name' property -->
@@ -273,19 +273,19 @@ In the following sample, the `intro-tag` binds to a published property on the `s
 {% endraw %}
 
 Here, `yourName` is bound to _both_ the `say-hello` element's `name` property and
-the `input` element's `value` attribute. Both bindings are two-way, so when the user enters 
-a name, it's pushed into the `say-hello` element's `name` property. If you change the 
+the `input` element's `value` attribute. Both bindings are two-way, so when the user enters
+a name, it's pushed into the `say-hello` element's `name` property. If you change the
 value of the `name` property, the value is pushed into the `input` element.
 
-**Note:** The `intro-tag` element doesn't define a `yourName` property. In this case, the data 
+**Note:** The `intro-tag` element doesn't define a `yourName` property. In this case, the data
 binding system creates the property automatically.
 {: .alert .alert-info }
 
 
 #### Binding objects and arrays to published properties
 
-Most of the examples show data binding with simple string values, 
-but {{site.project_title}} lets you bind references between elements 
+Most of the examples show data binding with simple string values,
+but {{site.project_title}} lets you bind references between elements
 using published properties.
 
 Let's modify the `name-tag` example to take an object instead of individual
@@ -354,13 +354,12 @@ If _boolean-expression_ is truthy, _attribute_  appears in the markup; otherwise
 
 Sometimes, you may not need dynamic bindings. For these cases, there are one-time bindings.
 
-Anywhere you use {% raw %}`{{}}`{% endraw %} in expressions, you can use double brackets 
+Anywhere you use {% raw %}`{{}}`{% endraw %} in expressions, you can use double brackets
 (`[[]]`) to set up a one-time binding. The binding becomes inactive after {{site.project_title}}
 sets its value for the first time.
 
 Example:
 
     <input type="text" value="this value is inserted once: [[ obj.value ]]">
 
-One-time bindings can potentially be a performance win if you don't need the overhead of setting up property observation.
-
+One time bindings can potentially be a performance win if you don't need the overhead of setting up property observation.
diff --git a/docs/polymer/polymer.md b/docs/polymer/polymer.md
@@ -25,7 +25,7 @@ At the heart of {{site.project_title}} are [Custom Elements](/platform/custom-el
 
 ### Attributes
 
-{{site.project_title}} [reserves](https://github.com/Polymer/polymer/blob/master/src/declaration/attributes.js#L53) special attributes to be used on `<polymer-element>`:
+{{site.project_title}} reserves special attributes to be used on `<polymer-element>`:
 
 <table class="table responsive-table attributes-table">
   <tr>
@@ -85,19 +85,19 @@ For convenient decoupling of script and markup, you don't have to inline your sc
 {{site.project_title}} elements can be created by referencing an external script
 which calls `Polymer('tag-name')`:
 
-    <!-- 2. Script referenced inside the element definition. -->
+    <!-- 1. Script referenced inside the element definition. -->
     <polymer-element name="tag-name">
       <template>...</template>
       <script src="path/to/tagname.js"></script>
     </polymer-element>
 
-    <!-- 3. Script comes before the element definition. -->
+    <!-- 2. Script comes before the element definition. -->
     <script src="path/to/tagname.js"></script>
     <polymer-element name="tag-name">
       <template>...</template>
     </polymer-element>
 
-    <!-- 4. No script -->
+    <!-- 3. No script -->
     <polymer-element name="tag-name" constructor="TagName" noscript>
       <template>
         <!-- shadow DOM here -->
@@ -119,22 +119,22 @@ Elements can be registered in pure JavaScript like so:
         </polymer-element>';
       // The custom elements polyfill can't see the <polymer-element>
       // unless you put it in the DOM.
-      document.body.appendChild(el);    
+      document.body.appendChild(el);
     </script>
 
     <name-tag name="John"></name-tag>
 
-Note that you need to add the `<polymer-element>` to the document so that the 
+Note that you need to add the `<polymer-element>` to the document so that the
 Custom Elements polyfill picks it up.
-    
+
 ### Adding public properties and methods {#propertiesmethods}
 
 If you wish to define methods/properties on your element (optional), pass an object
 as the second argument to `Polymer()`. This object is used to define
 the element's `prototype`.
 
 The following example defines a property `message`, a computed property `greeting`
-using an ES5 getter, and a method `foo`: 
+using an ES5 getter, and a method `foo`:
 
     <polymer-element name="tag-name">
       <template>{{greeting}}</template>
@@ -143,7 +143,7 @@ using an ES5 getter, and a method `foo`:
           message: "Hello!",
           get greeting() {
             return this.message + ' there!';
-          }, 
+          },
           foo: function() {...}
         });
       </script>
@@ -152,7 +152,7 @@ using an ES5 getter, and a method `foo`:
 **Note:** `this` references the custom element itself inside a {{site.project_title}} element. For example, `this.localName == 'tag-name'`.
 {: .alert .alert-info }
 
-**Important:** Be careful when initializing properties that are objects or arrays. Due to the nature of `prototype`, you may run into unexpected "shared state" across instances of the same element. If you're initializing an array or object, do it in the `created` callback rather than directly on the `prototype`. 
+**Important:** Be careful when initializing properties that are objects or arrays. Due to the nature of `prototype`, you may run into unexpected "shared state" across instances of the same element. If you're initializing an array or object, do it in the `created` callback rather than directly on the `prototype`.
 
     // Good!
     Polymer('x-foo', {
@@ -256,7 +256,7 @@ The main page configures the globals by passing attributes:
 {{site.project_title}} has first class support for the Custom Element lifecycle
 callbacks, though for convenience, implements them with shorter names.
 
-All of the lifecycle callbacks are optional: 
+All of the lifecycle callbacks are optional:
 
     Polymer('tag-name', {
       created: function() { ... },
@@ -277,7 +277,7 @@ Spec | {{site.project_title}} | Called when
 |-
 createdCallback | created | An instance of the element is created.
 - | ready | The `<polymer-element>` has been fully prepared (e.g. Shadow DOM created, property observers setup, event listeners attached, etc).
-attachedCallback | attached | An instance of the element was inserted into the DOM. 
+attachedCallback | attached | An instance of the element was inserted into the DOM.
 - | domReady | Called when the element's initial set of children are guaranteed to exist. This is an appropriate time to poke at the element's parent or light DOM children. Another use is when you have sibling custom elements (e.g. they're `.innerHTML`'d together, at the same time). Before element A can use B's API/properties, element B needs to be upgraded. The `domReady` callback ensures both elements exist.
 detachedCallback | detached | An instance was removed from the DOM.
 attributeChangedCallback | attributeChanged | An attribute was added, removed, or updated. **Note**: to observe changes to [published properties](#published-properties), use [changed watchers](#change-watchers).
@@ -453,7 +453,7 @@ When attribute values are converted to property values, {{site.project_title}}
 attempts to convert the value to the correct type, depending on the default
 value of the property.
 
-For example, suppose an `x-hint` element has a `count` property that defaults to `0`. 
+For example, suppose an `x-hint` element has a `count` property that defaults to `0`.
 
     <x-hint count="7"></x-hint>
 
@@ -465,7 +465,7 @@ double-quoted JSON string. For example:
 
     <x-name fullname='{ "first": "Bob", "last": "Dobbs" }'></x-name>
 
-This is equivalent to setting the element's `fullname` property to an object 
+This is equivalent to setting the element's `fullname` property to an object
 literal in JavaScript:
 
     xname.fullname = { first: 'Bob', last: 'Dobbs' };
@@ -648,7 +648,7 @@ All properties on {{site.project_title}} elements can be watched for changes by
       </script>
     </polymer-element>
 
-In this example, there are two watched properties, `better` and `best`. The `betterChanged` and `bestChanged` function will be called whenever `better` or `best` are modified, respectively. 
+In this example, there are two watched properties, `better` and `best`. The `betterChanged` and `bestChanged` function will be called whenever `better` or `best` are modified, respectively.
 
 #### Custom property observers - `observe` blocks {#observeblock}
 
@@ -734,7 +734,7 @@ It's important to note that **{{site.project_title}} does not call the <code><em
 
 ### Automatic node finding
 
-Another useful feature of {{site.project_title}} is node reference marshalling. Every node in a component's shadow DOM that is tagged with an `id` attribute is automatically referenced in the component's `this.$` hash. 
+Another useful feature of {{site.project_title}} is node reference marshalling. Every node in a component's shadow DOM that is tagged with an `id` attribute is automatically referenced in the component's `this.$` hash.
 
 For example, the following defines a component whose template contains an `<input>` element whose `id` attribute is `nameInput`. The component can refer to that element with the expression `this.$.nameInput`.
 
@@ -762,7 +762,7 @@ Example:
 {% raw %}
     <polymer-element name="ouch-button">
       <template>
-        <button on-click="{{onClick}}">Send hurt</button> 
+        <button on-click="{{onClick}}">Send hurt</button>
       </template>
       <script>
         Polymer('ouch-button', {
@@ -806,7 +806,7 @@ and data-bound.
     <polymer-element name="polymer-cooler" extends="polymer-cool">
       <template>
         <!-- A shadow element render's the extended
-             element's shadow dom here. --> 
+             element's shadow dom here. -->
         <shadow></shadow> <!-- "You are cool Matt" -->
       </template>
       <script>
@@ -864,8 +864,8 @@ to "coolest".
 
 ### Observing changes to light DOM children {#onMutation}
 
-To know when light DOM children change, you can setup a Mutation Observer to 
-be notified when nodes are added or removed. To make this more convenient, {{site.project_title}} adds an `onMutation()` callback to every element. Its first argument is the DOM element to 
+To know when light DOM children change, you can setup a Mutation Observer to
+be notified when nodes are added or removed. To make this more convenient, {{site.project_title}} adds an `onMutation()` callback to every element. Its first argument is the DOM element to
 observe. The second argument is a callback which is passed the `MutationObserver` and the mutation records:
 
     this.onMutation(domElement, someCallback);
@@ -953,7 +953,7 @@ declared in markup.
 
 If you instantiate an element (e.g. `document.createElement('x-foo')`) and do **not** add it to the DOM,
 {{site.project_title}} asynchronously removes its {%raw%}`{{}}`{%endraw%} bindings and `*Changed` methods.
-This helps prevent memory leaks, ensuring the element will be garbage collected. 
+This helps prevent memory leaks, ensuring the element will be garbage collected.
 
 If you want the element to "remain active" when it's not in the `document`,
 call `cancelUnbindAll()` right after you create or remove it. The [lifecycle methods](#lifecyclemethods)
@@ -998,7 +998,7 @@ when `Object.observe()` is available. When it's not supported, {{site.project_ti
 
 `Platform.flush()` is part of {{site.project_title}}'s data observation polyfill, [observe-js](https://github.com/Polymer/observe-js). It dirty check's all objects that have been observed and ensures notification callbacks are dispatched. {{site.project_title}} automatically calls `Platform.flush()` periodically, and this should be sufficient for most application workflows. However, there are times when you'll want to call `Platform.flush()` in application code.
 
-**Note**: on platforms that support `Object.observe()` natively, `Platform.flush()` does nothing.
+**Note:** on platforms that support `Object.observe()` natively, `Platform.flush()` does nothing.
 {: .alert .alert-info }
 
 #### When should I call `Platform.flush()`?
@@ -1012,6 +1012,7 @@ need to manually call `Platform.flush()`. Here are specific examples:
 2. The author of a slider element wants to ensure that data can propagate from it as the user slides the slider. A user of the element, might, for example, bind the slider's value to an input and expect to see the input change while the slider is moving. To achieve this, the element author calls `Platform.flush()` after setting the element's value in the `ontrack` event handler.
 
 **Note:** {{site.project_title}} is designed such that change notifications are asynchronous. Both `Platform.flush()` and `Object.observe()` (after which it's modeled) are asynchronous. Therefore, **`Platform.flush()` should not be used to try to enforce synchronous data notifications**. Instead, always use [change watchers](#change-watchers) to be informed about state.
+{: .alert .alert-info }
 
 ### How {{site.project_title}} elements prepare themselves {#prepare}
 
@@ -1037,7 +1038,7 @@ prepare themselves even when they do not satisfy the above rules.
 
 ### Resolving paths of sibling elements {#resolvepath}
 
-For the general case of element re-use and sharing, URLs in HTML Imports are meant to be relative to the location of the import. The majority of the time, the browser takes care of this for you. 
+For the general case of element re-use and sharing, URLs in HTML Imports are meant to be relative to the location of the import. The majority of the time, the browser takes care of this for you.
 
 However, JavaScript doesn't have a notion of a local import. Therefore, {{site.project_title}} provides a `resolvePath()` utility for converting paths relative to the import to paths relative to the document.
 
