Skip to content

Commit 2626564

Browse files
ebidelebidel
committed
Merge pull request Polymer#569 from arthurevans/computed
docs-468: Doc computed block & inline function support.
2 parents 3cc979d + 9ecde09 commit 2626564

File tree

5 files changed

+99
-11
lines changed

5 files changed

+99
-11
lines changed

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
node_modules
22
bower_components
3-
components
3+
/components
44
polymer-all
55
_site
66
.DS_Store

‎_includes/samples/computed-property.html

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<link rel="import" href="/samples/components/computed-property.html">
2+
3+
<!-- <link rel="import" href="/elements/demo-tabs.html"> -->
4+
5+
<demo-tabs selected="0">
6+
<demo-tab heading="square-element.html">
7+
{% highlight html %}
8+
{% include_external samples/components/computed-property.html %}
9+
{% endhighlight %}
10+
</demo-tab>
11+
<demo-tab heading="index.html">
12+
{% highlight html %}
13+
<!DOCTYPE html>
14+
<html>
15+
<head>
16+
<script src="platform.js"></script>
17+
<link rel="import" href="square-element.html">
18+
</head>
19+
<body>
20+
<square-element></square-element>
21+
</body>
22+
</html>
23+
{% endhighlight %}
24+
</demo-tab>
25+
<div class="result">
26+
<square-element></square-element>
27+
</div>
28+
</demo-tabs>

‎docs/polymer/expressions.md

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ Within a `<polymer-element>` you can use {{site.project_title}}'s [expression
1414
library](https://github.com/polymer/polymer-expressions) to write inline expressions,
1515
named scopes, and iterative markup, anywhere {%raw%}`{{`&nbsp;`}}`{%endraw%} bindings are used.
1616

17+
Expressions can also be used to define [computed properties](/docs/polymer/polymer.html#computed-properties).
18+
1719
## Expression syntax
1820

1921
{{site.project_title}} supports expressions in {%raw%}`{{}}`{%endraw%} with a strict
@@ -45,27 +47,33 @@ Expressions support the following subset of JavaScript:
4547
| Grouping (parenthesis) | `(a + b) * (c + d)` |
4648
| Literal values | numbers, strings, `null`, `undefined` | Escaped strings and non-decimal numbers are not supported. |
4749
| Array & Object initializers | `[foo, 1]`, `{id: 1, foo: bar}` |
50+
| 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.
4851
{: .first-col-nowrap .responsive-table .expressions-table }
4952

53+
5054
In addition to the JavaScript portion, an expression can also include one or more _filters_, which
5155
modify the output of the JavaScript expression. See [Filtering expressions](#filters) for
5256
information.
5357

5458
## Evaluating expressions
5559

56-
Expressions are parsed when they're within a double-mustache binding:
60+
Expressions are parsed when they're within a binding or computed property declaration:
5761

58-
<pre class="prettyprint">
59-
{%raw%}{{ <var>expression</var> }}{%endraw%}
62+
<pre class="nocode">
63+
{%raw%}<b>{{</b> <var>expression</var> <b>}}</b>{%endraw%}
6064
</pre>
6165

62-
or a one-time binding:
66+
<pre class="nocode">
67+
<b>[[</b> <var>expression</var> <b>]]</b>
68+
</pre>
6369

64-
<pre class="prettyprint">
65-
[[ <var>expression</var> ]]
70+
<pre class="nocode">
71+
<b>computed: {</b>
72+
<var>property_name</var><b>: '</b><var>expression</var><b>'
73+
}</b>
6674
</pre>
6775

68-
The value of the expression is evaluated and the result inserted as the value of the binding:
76+
The value of the expression is evaluated. In a binding, the result inserted as the value of the binding:
6977

7078
{% raw %}
7179
<div>Jill has {{daughter.children.length + son.children.length}} grandchildren</div>
@@ -75,8 +83,9 @@ may result in:
7583

7684
<div>Jill has 100 grandchildren</div>
7785

78-
For standard (double-mustache) bindings, the expression is re-evaluated whenever the value of one or
79-
more paths in the expression changes.
86+
For standard (double-mustache) bindings and computed properties, the
87+
expression is re-evaluated whenever the value of one or more paths
88+
in the expression changes.
8089

8190
## Expression scopes {#expression-scopes}
8291

@@ -85,6 +94,8 @@ are visible. The expressions in `bind`, `repeat` or `if` attributes are evaluate
8594
the parent template. For an element's outermost template, paths and identifiers are
8695
interpreted relative to the element itself (so `this.prop` is available as {%raw%}`prop`{%endraw%}).
8796

97+
For computed properties, the scope of an expression is always the element itself.
98+
8899
Templates that don't include `bind` or `repeat` share the current scope.
89100

90101
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:
244255
return Number(value).toFixed(precision);
245256
}
246257

258+
The parameters passed to a filter are observed for changes.
259+
247260
#### Chaining filters
248261

249262
You can also chain filters, passing the output of one filter to another:

‎docs/polymer/polymer.md

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@ If you wish to define methods/properties on your element (optional), pass an obj
133133
as the second argument to `Polymer()`. This object is used to define
134134
the element's `prototype`.
135135

136-
The following example defines a property `message`, a computed property `greeting`
136+
The following example defines a property `message`, a property `greeting`
137137
using an ES5 getter, and a method `foo`:
138138

139139
<polymer-element name="tag-name">
@@ -599,6 +599,37 @@ In this example, the published property `name` has initial value of `null` and `
599599

600600
For more information see the [Data binding overview](databinding.html).
601601

602+
### Computed properties
603+
604+
In addition to standard published properties, you can define
605+
properties that are computed based on other property values.
606+
607+
Computed properties are defined in the `computed` object on the
608+
element's prototype:
609+
610+
<pre class="nocode">
611+
<b>computed: {</b>
612+
<var>property-name</var><b>: '</b><var>expression</var><b>'
613+
}</b>
614+
</pre>
615+
616+
Each computed property is defined by a property name and a
617+
[Polymer expression](/docs/polymer/expressions.html). The value
618+
of the computed property is updated dynamically whenever one of
619+
the input values in the expression changes.
620+
621+
In the following example, when you update the input value,
622+
`num`, the computed property `square` updates automatically.
623+
624+
{% include samples/computed-property.html %}
625+
626+
**Limitations**: Currently, computed properties aren't published
627+
so they can't be data bound from _outside_ the element. For example,
628+
you can't bind to the `square` property on `square-element` using
629+
`<square-element square="{%raw%}{{value}}{%endraw%}>`. This
630+
is [a known issue](https://github.com/Polymer/polymer/issues/638).
631+
{: .alert .alert-warning }
632+
602633
### Declarative event mapping
603634

604635
{{site.project_title}} supports declarative binding of events to methods in the component.

‎samples/components/computed-property.html

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<link rel="import" href="../../components/polymer/polymer.html">
2+
3+
<polymer-element name="square-element">
4+
<template>
5+
<input type="number" value="{{num}}"><br>
6+
<em>{{num}}^2 = {{square}}</em>
7+
</template>
8+
<script>
9+
Polymer('square-element', {
10+
num: 2,
11+
computed: {
12+
square: 'num * num'
13+
}
14+
});
15+
</script>
16+
</polymer-element>

0 commit comments

Comments
 (0)