Merge branch 'master' of https://github.com/Polymer/docs

ebidel · ebidel · commit 6de6398a31af · 2014-07-31T19:05:08.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,6 @@
 node_modules
 bower_components
-components
+/components
 polymer-all
 _site
 .DS_Store
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ Polymer docs are mostly in Markdown with some HTML. [Jekyll][jekyll] is used to
 We use Jekyll 2.0+ and [Grunt][grunt] to generate the documentation, and compass to compile SASS to CSS. You'll need to install the requirements before working on the docs (these instructions assume [NPM is already installed](http://nodejs.org/download/)):
 
     gem install jekyll kramdown jekyll-page-hooks compass rouge
-    npm install -g grunt-cli
+    npm install -g grunt-cli vulcanize
 
 **Note:** If you receive permission warnings, you may need to run the above tasks with `sudo`.
 
diff --git a/_includes/samples/computed-property.html b/_includes/samples/computed-property.html
@@ -0,0 +1,28 @@
+<link rel="import" href="/samples/components/computed-property.html">
+
+<!-- <link rel="import" href="/elements/demo-tabs.html"> -->
+
+<demo-tabs selected="0">
+  <demo-tab heading="square-element.html">
+{% highlight html %}
+{% include_external samples/components/computed-property.html %}
+{% endhighlight %}
+  </demo-tab>
+  <demo-tab heading="index.html">
+{% highlight html %}
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="platform.js"></script>
+    <link rel="import" href="square-element.html">
+  </head>
+  <body>
+    <square-element></square-element>
+  </body>
+</html>
+{% endhighlight %}
+  </demo-tab>
+  <div class="result">
+    <square-element></square-element>
+  </div>
+</demo-tabs>
diff --git a/docs/polymer/expressions.md b/docs/polymer/expressions.md
@@ -14,6 +14,8 @@ Within a `<polymer-element>` you can use {{site.project_title}}'s [expression
 library](https://github.com/polymer/polymer-expressions) to write inline expressions, 
 named scopes, and iterative markup, anywhere {%raw%}`{{`&nbsp;`}}`{%endraw%} bindings are used.
 
+Expressions can also be used to define [computed properties](/docs/polymer/polymer.html#computed-properties).
+
 ## Expression syntax
 
 {{site.project_title}} supports expressions in {%raw%}`{{}}`{%endraw%} with a strict
@@ -45,27 +47,33 @@ Expressions support the following subset of JavaScript:
 | Grouping (parenthesis) | `(a + b) * (c + d)` |
 | Literal values | numbers, strings, `null`, `undefined` | Escaped strings and non-decimal numbers are not supported. |
 | Array & Object initializers | `[foo, 1]`, `{id: 1, foo: bar}` |
+| Function | `reverse(my_list)` | The expression's value is the return value of the function. The function's arguments are observed for changes, and the expression is re-evaluated whenever one of the arguments changes. 
 {: .first-col-nowrap .responsive-table .expressions-table }
 
+
 In addition to the JavaScript portion, an expression can also include one or more _filters_, which
 modify the output of the JavaScript expression. See [Filtering expressions](#filters) for
 information.
 
 ## Evaluating expressions
 
-Expressions are parsed when they're within a double-mustache binding:
+Expressions are parsed when they're within a binding or computed property declaration:
 
-<pre class="prettyprint">
-{%raw%}{{ <var>expression</var> }}{%endraw%}
+<pre class="nocode">
+{%raw%}<b>{{</b> <var>expression</var> <b>}}</b>{%endraw%}
 </pre>
 
-or a one-time binding:
+<pre class="nocode">
+<b>[[</b> <var>expression</var> <b>]]</b>
+</pre>
 
-<pre class="prettyprint">
-[[ <var>expression</var> ]]
+<pre class="nocode">
+<b>computed: {</b>
+  <var>property_name</var><b>: '</b><var>expression</var><b>'
+}</b>
 </pre>
 
-The value of the expression is evaluated and the result inserted as the value of the binding:
+The value of the expression is evaluated. In a binding, the result inserted as the value of the binding:
 
 {% raw %}
     <div>Jill has {{daughter.children.length + son.children.length}} grandchildren</div>
@@ -75,8 +83,9 @@ may result in:
 
     <div>Jill has 100 grandchildren</div>
 
-For standard (double-mustache) bindings, the expression is re-evaluated whenever the value of one or
-more paths in the expression changes.
+For standard (double-mustache) bindings and computed properties, the 
+expression is re-evaluated whenever the value of one or more paths 
+in the expression changes.
 
 ## Expression scopes {#expression-scopes}
 
@@ -85,6 +94,8 @@ are visible. The expressions in `bind`, `repeat` or `if` attributes are evaluate
 the parent template. For an element's outermost template, paths and identifiers are 
 interpreted relative to the element itself (so `this.prop` is available as {%raw%}`prop`{%endraw%}).
 
+For computed properties, the scope of an expression is always the element itself.
+
 Templates that don't include `bind` or `repeat` share the current scope.
 
 A `bind` or `repeat` without an expression is the same as using an expression that 
@@ -244,6 +255,8 @@ The code for the `toFixed` filter could look like this:
       return Number(value).toFixed(precision);
     }
 
+The parameters passed to a filter are observed for changes.
+
 #### Chaining filters
 
 You can also chain filters, passing the output of one filter to another:
diff --git a/docs/polymer/layout-attrs.md b/docs/polymer/layout-attrs.md
@@ -95,13 +95,13 @@ For example, to make "Gamma" 2x larger than "Beta" and "Alpha" 3x larger, use `f
 
     <div horizontal layout>
       <div flex three>Alpha</div>
-      <div>Beta</div>
+      <div flex>Beta</div>
       <div flex two>Gamma</div>
     </div>
 
 <div horizontal layout class="demo">
   <div flex three>Alpha</div>
-  <div>Beta</div>
+  <div flex>Beta</div>
   <div flex two>Gamma</div>
 </div>
 
@@ -297,4 +297,4 @@ Attribute | Result
 <div class="demo">Hidden: <span hidden>Not displayed</span></div>
 <div relative style="height: 100px;" class="demo">
   <div fit style="background-color: #000;color: white">Fit</div>
-</div>
+</div>
diff --git a/docs/polymer/polymer.md b/docs/polymer/polymer.md
@@ -133,7 +133,7 @@ If you wish to define methods/properties on your element (optional), pass an obj
 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`
+The following example defines a property `message`, a property `greeting`
 using an ES5 getter, and a method `foo`:
 
     <polymer-element name="tag-name">
@@ -278,7 +278,7 @@ Below is a table of the lifecycle methods according to the Custom Elements
 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).
+- | 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.
 - | 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.
@@ -599,6 +599,37 @@ In this example, the published property `name` has initial value of `null` and `
 
 For more information see the [Data binding overview](databinding.html).
 
+### Computed properties
+
+In addition to standard published properties, you can define 
+properties that are computed based on other property values.
+
+Computed properties are defined in the `computed` object on the
+element's prototype:
+
+<pre class="nocode">
+<b>computed: {</b>
+  <var>property-name</var><b>: '</b><var>expression</var><b>'
+}</b>
+</pre>
+
+Each computed property is defined by a property name and a 
+[Polymer expression](/docs/polymer/expressions.html). The value
+of the computed property is updated dynamically whenever one of 
+the input values in the expression changes. 
+
+In the following example, when you update the input value,
+`num`, the computed property `square` updates automatically.
+
+{% include samples/computed-property.html %}
+
+**Limitations**: Currently, computed properties aren't published
+so they can't be data bound from _outside_ the element. For example,
+you can't bind to the `square` property on `square-element` using
+ `<square-element square="{%raw%}{{value}}{%endraw%}>`. This
+is [a known issue](https://github.com/Polymer/polymer/issues/638).
+{: .alert .alert-warning }
+
 ### Declarative event mapping
 
 {{site.project_title}} supports declarative binding of events to methods in the component.
@@ -736,7 +767,14 @@ 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 automatic node finding. 
+Nodes in a component's shadow DOM that are tagged with an 
+`id` attribute are automatically referenced in the component's `this.$` hash.
+
+**Note:** Nodes created dynamically using data binding are _not_ added to the 
+`this.$` hash. The hash includes only _statically_ created shadow DOM nodes 
+(that is, the nodes defined in the element's outermost template).
+{: .alert .alert-warning }
 
 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`.
 
@@ -753,6 +791,24 @@ For example, the following defines a component whose template contains an `<inpu
       </script>
     </polymer-element>
 
+To locate other nodes inside the element's shadow DOM, you can create a 
+container element with a known ID and use `querySelector` to retrieve
+descendants. For example, if your element's template looks like this:
+
+    <template>
+      <div id="container">
+        <template if="{%raw%}{{some_condition}}{%endraw%}">
+          <div id="inner">
+           This content is created by data binding.
+          </div>
+        </template>
+      </div>
+    </template>
+
+You can locate the inner container using:
+
+    this.$.container.querySelector('#inner');
+
 ### Firing custom events {#fire}
 
 {{site.project_title}} core provides a convenient `fire()` method for
diff --git a/samples/components/computed-property.html b/samples/components/computed-property.html
@@ -0,0 +1,16 @@
+<link rel="import" href="../../components/polymer/polymer.html">
+
+<polymer-element name="square-element">
+  <template>
+    <input type="number" value="{{num}}"><br>
+    <em>{{num}}^2 = {{square}}</em>
+  </template>
+  <script>
+    Polymer('square-element', {
+      num: 2,
+      computed: {
+        square: 'num * num'
+      }
+    });
+   </script>
+</polymer-element>
