Chromium Code Reviews| OLD | NEW |
|---|---|
| 1 polymer_expressions | 1 polymer_expressions |
| 2 =================== | 2 =================== |
| 3 | 3 |
| 4 | 4 |
| 5 Polymer expressions are an expressive syntax that can be used in HTML templates | 5 Polymer expressions are an expressive syntax that can be used in HTML templates |
| 6 with Dart. | 6 with Dart. |
| 7 | 7 |
| 8 Templates are one feature of Polymer.dart, which is a set of comprehensive UI | 8 Templates are one feature of Polymer.dart, which is a set of comprehensive UI |
| 9 and utility components for building web applications. | 9 and utility components for building web applications. |
| 10 This package is automatically included with the | 10 This package is automatically included with the |
| (...skipping 30 matching lines...) Expand all Loading... | |
| 41 <template> | 41 <template> |
| 42 <p>Hello {{ person.name }}</p> | 42 <p>Hello {{ person.name }}</p> |
| 43 </template> | 43 </template> |
| 44 ``` | 44 ``` |
| 45 | 45 |
| 46 MDV includes a very basic binding syntax which only allows a series of | 46 MDV includes a very basic binding syntax which only allows a series of |
| 47 dot-separate property names. | 47 dot-separate property names. |
| 48 | 48 |
| 49 [mdv]: http://www.polymer-project.org/platform/mdv.html | 49 [mdv]: http://www.polymer-project.org/platform/mdv.html |
| 50 | 50 |
| 51 ### Custom Binding Syntaxes with BindingDelegate | 51 ### Custom binding syntaxes with bindingDelegate |
|
Kathy Walrath
2013/10/29 17:19:51
should this be BindingDelegate? (or binding delega
Andrei Mouravski
2013/10/29 17:21:47
I chose the later.
| |
| 52 | 52 |
| 53 While MDV's built-in syntax is very basic, it does allow custom syntaxes called | 53 While MDV's built-in syntax is very basic, it does allow custom syntaxes called |
| 54 "binding delegates" to be installed and used. A binding delegate can interpret | 54 "binding delegates" to be installed and used. A binding delegate can interpret |
| 55 the contents of mustaches however it likes. PolymerExpressions is such a | 55 the contents of mustaches however it likes. PolymerExpressions is such a |
| 56 binding delegate. | 56 binding delegate. |
| 57 | 57 |
| 58 Example: | 58 Example: |
| 59 | 59 |
| 60 ```html | 60 ```html |
| 61 <template bind> | 61 <template bind> |
| (...skipping 12 matching lines...) Expand all Loading... | |
| 74 polymer_expressions: any | 74 polymer_expressions: any |
| 75 ``` | 75 ``` |
| 76 | 76 |
| 77 Hint: check https://pub.dartlang.org/packages/polymer_expressions for the latest | 77 Hint: check https://pub.dartlang.org/packages/polymer_expressions for the latest |
| 78 version number. | 78 version number. |
| 79 | 79 |
| 80 Then import polymer_expressions.dart: | 80 Then import polymer_expressions.dart: |
| 81 | 81 |
| 82 import 'package:polymer_expressions/polymer_expressions.dart'; | 82 import 'package:polymer_expressions/polymer_expressions.dart'; |
| 83 | 83 |
| 84 ### Registering a Binding Delegate | 84 ### Registering a binding delegate |
| 85 | 85 |
| 86 **Polymer Expressions are now the default syntax for `<polymer-element>` custom | 86 **Polymer Expressions are now the default syntax for `<polymer-element>` custom |
| 87 elements.** | 87 elements.** |
| 88 | 88 |
| 89 You do not need to manually register the bindingDelegate if your bindings are | 89 You do not need to manually register the bindingDelegate if your bindings are |
| 90 inside a custom element. However, if you want to use polymer_expressions outside | 90 inside a custom element. However, if you want to use polymer_expressions outside |
| 91 a custom element, read on: | 91 a custom element, read on: |
| 92 | 92 |
| 93 Binding delegates must be installed on a template before they can be used. | 93 Binding delegates must be installed on a template before they can be used. |
| 94 For example, set the bindingDelegate property of your template | 94 For example, set the bindingDelegate property of your template |
| 95 elements to an instance of PolymerExpressions. The templates will then use the | 95 elements to an instance of PolymerExpressions. The templates will then use the |
| 96 PolymerExpressions instance to interpret | 96 PolymerExpressions instance to interpret |
| 97 binding expressions. | 97 binding expressions. |
| 98 | 98 |
| 99 ```dart | 99 ```dart |
| 100 import 'dart:html'; | 100 import 'dart:html'; |
| 101 import 'package:polymer_expressions/polymer_expressions.dart'; | 101 import 'package:polymer_expressions/polymer_expressions.dart'; |
| 102 | 102 |
| 103 main() { | 103 main() { |
| 104 var template = query('#my_template'); | 104 var template = query('#my_template'); |
| 105 template.bindingDelegate = new PolymerExpressions(); | 105 template.bindingDelegate = new PolymerExpressions(); |
| 106 } | 106 } |
| 107 ``` | 107 ``` |
| 108 | 108 |
| 109 ### Registering Top-Level Variables | 109 ### Registering top-level variables |
| 110 | 110 |
| 111 Before a top-level variable can be used, it must be registered. The | 111 Before a top-level variable can be used, it must be registered. The |
| 112 PolymerExpressions constructor takes a map of named values to use as variables. | 112 PolymerExpressions constructor takes a map of named values to use as variables. |
| 113 | 113 |
| 114 ```dart | 114 ```dart |
| 115 main() { | 115 main() { |
| 116 var globals = { | 116 var globals = { |
| 117 'uppercase': (String v) => v.toUpperCase(), | 117 'uppercase': (String v) => v.toUpperCase(), |
| 118 'app_id': 'my_app_123', | 118 'app_id': 'my_app_123', |
| 119 }; | 119 }; |
| 120 var template = query('#my_template'); | 120 var template = query('#my_template'); |
| 121 template.bindingDelegate = new PolymerExpressions(globals: globals); | 121 template.bindingDelegate = new PolymerExpressions(globals: globals); |
| 122 } | 122 } |
| 123 ``` | 123 ``` |
| 124 | 124 |
| 125 ## Features | 125 ## Features |
| 126 | 126 |
| 127 ### The Model and Scope | 127 ### The model and scope |
| 128 | 128 |
| 129 Polymer Expressions allow binding to more than just the model assigned to a | 129 Polymer Expressions allow binding to more than just the model assigned to a |
| 130 template instance. Top-level variables can be defined so that you can use | 130 template instance. Top-level variables can be defined so that you can use |
| 131 filters, global variables and constants, functions, etc. These variables and the | 131 filters, global variables and constants, functions, etc. These variables and the |
| 132 model are held together in a container called a Scope. Scopes can be nested, | 132 model are held together in a container called a Scope. Scopes can be nested, |
| 133 which happens when template tags are nested. | 133 which happens when template tags are nested. |
| 134 | 134 |
| 135 ### Two-way Bindings | 135 ### Two-way bindings |
| 136 | 136 |
| 137 Bindings can be used to modify the data model based on events in the DOM. The | 137 Bindings can be used to modify the data model based on events in the DOM. The |
| 138 most common case is to bind an <input> element's value field to a model | 138 most common case is to bind an <input> element's value field to a model |
| 139 property and have the property update when the input changes. For this to work, | 139 property and have the property update when the input changes. For this to work, |
| 140 the binding expression must be "assignable". Only a subset of expressions are | 140 the binding expression must be "assignable". Only a subset of expressions are |
| 141 assignable. Assignable expressions cannot contain function calls, operators, and | 141 assignable. Assignable expressions cannot contain function calls, operators, and |
| 142 any index operator must have a literal argument. Assignable expressions can | 142 any index operator must have a literal argument. Assignable expressions can |
| 143 contain filter operators as long as all the filters are two-way transformers. | 143 contain filter operators as long as all the filters are two-way transformers. |
| 144 | 144 |
| 145 Some restrictions may be relaxed further as allowed. | 145 Some restrictions may be relaxed further as allowed. |
| (...skipping 24 matching lines...) Expand all Loading... | |
| 170 ### Streams | 170 ### Streams |
| 171 | 171 |
| 172 Polymer Expressions have experimental support for binding to streams, and when | 172 Polymer Expressions have experimental support for binding to streams, and when |
| 173 new values are passed to the stream, the template updates. The feature is not | 173 new values are passed to the stream, the template updates. The feature is not |
| 174 fully implemented yet. | 174 fully implemented yet. |
| 175 | 175 |
| 176 See the examples in /example/streams for more details. | 176 See the examples in /example/streams for more details. |
| 177 | 177 |
| 178 ## Syntax | 178 ## Syntax |
| 179 | 179 |
| 180 ### Property Access | 180 ### Property access |
| 181 | 181 |
| 182 Properties on the model and in the scope are looked up via simple property | 182 Properties on the model and in the scope are looked up via simple property |
| 183 names, like `foo`. Property names are looked up first in the top-level | 183 names, like `foo`. Property names are looked up first in the top-level |
| 184 variables, next in the model, then recursively in parent scopes. Properties on | 184 variables, next in the model, then recursively in parent scopes. Properties on |
| 185 objects can be access with dot notation like `foo.bar`. | 185 objects can be access with dot notation like `foo.bar`. |
| 186 | 186 |
| 187 The keyword `this` always refers to the model if there is one, otherwise `this` | 187 The keyword `this` always refers to the model if there is one, otherwise `this` |
| 188 is `null`. If you have model properties and top-level variables with the same | 188 is `null`. If you have model properties and top-level variables with the same |
| 189 name, you can use `this` to refer to the model property. | 189 name, you can use `this` to refer to the model property. |
| 190 | 190 |
| 191 ### Literals | 191 ### Literals |
| 192 | 192 |
| 193 Polymer Expressions support number, boolean, string, and map literals. Strings | 193 Polymer Expressions support number, boolean, string, and map literals. Strings |
| 194 can use either single or double quotes. | 194 can use either single or double quotes. |
| 195 | 195 |
| 196 * Numbers: `1`, `1.0` | 196 * Numbers: `1`, `1.0` |
| 197 * Booleans: `true`, `false` | 197 * Booleans: `true`, `false` |
| 198 * Strings: `'abc'`, `"xyz"` | 198 * Strings: `'abc'`, `"xyz"` |
| 199 * Maps: `{ 'a': 1, 'b': 2 }` | 199 * Maps: `{ 'a': 1, 'b': 2 }` |
| 200 | 200 |
| 201 List literals are planned, see [issue 9](https://github.com/dart-lang/polymer_ex pressions/issues/9) | 201 List literals are planned, see [issue 9](https://github.com/dart-lang/polymer_ex pressions/issues/9) |
| 202 | 202 |
| 203 ### Functions and Methods | 203 ### Functions and methods |
| 204 | 204 |
| 205 If a property is a function in the scope, a method on the model, or a method on | 205 If a property is a function in the scope, a method on the model, or a method on |
| 206 an object, it can be invoked with standard function syntax. Functions and | 206 an object, it can be invoked with standard function syntax. Functions and |
| 207 Methods can take arguments. Named arguments are not supported. Arguments can be | 207 Methods can take arguments. Named arguments are not supported. Arguments can be |
| 208 literals or variables. | 208 literals or variables. |
| 209 | 209 |
| 210 Examples: | 210 Examples: |
| 211 | 211 |
| 212 * Top-level function: `myFunction()` | 212 * Top-level function: `myFunction()` |
| 213 * Top-level function with arguments: `myFunction(a, b, 42)` | 213 * Top-level function with arguments: `myFunction(a, b, 42)` |
| 214 * Model method: `aMethod()` | 214 * Model method: `aMethod()` |
| 215 * Method on nested-property: `a.b.anotherMethod()` | 215 * Method on nested-property: `a.b.anotherMethod()` |
| 216 | 216 |
| 217 ### Operators | 217 ### Operators |
| 218 | 218 |
| 219 Polymer Expressions supports the following binary and unary operators: | 219 Polymer Expressions supports the following binary and unary operators: |
| 220 | 220 |
| 221 * Arithmetic operators: +, -, *, /, %, unary + and - | 221 * Arithmetic operators: +, -, *, /, %, unary + and - |
| 222 * Comparison operators: ==, !=, <=, <, >, >= | 222 * Comparison operators: ==, !=, <=, <, >, >= |
| 223 * Boolean operators: &&, ||, unary ! | 223 * Boolean operators: &&, ||, unary ! |
| 224 | 224 |
| 225 Expressions do not support bitwise operators such as &, |, << and >>, or increme nt/decrement operators (++ and --) | 225 Expressions do not support bitwise operators such as &, |, << and >>, or increme nt/decrement operators (++ and --) |
| 226 | 226 |
| 227 ### List and Map Indexing | 227 ### List and Map indexing |
| 228 | 228 |
| 229 List and Map like objects can be accessed via the index operator: [] | 229 List and Map like objects can be accessed via the index operator: [] |
| 230 | 230 |
| 231 Examples: | 231 Examples: |
| 232 | 232 |
| 233 * `items[2]` | 233 * `items[2]` |
| 234 * `people['john']` | 234 * `people['john']` |
| 235 | 235 |
| 236 Unlike JavaScript, list and map contents are not generally available via | 236 Unlike JavaScript, list and map contents are not generally available via |
| 237 property access. That is, the previous examples are not equivalent to `items.2` | 237 property access. That is, the previous examples are not equivalent to `items.2` |
| 238 and `people.john`. This ensures that access to properties and methods on Lists | 238 and `people.john`. This ensures that access to properties and methods on Lists |
| 239 and Maps is preserved. | 239 and Maps is preserved. |
| 240 | 240 |
| 241 ### Filters and Transformers | 241 ### Filters and transformers |
| 242 | 242 |
| 243 A filter is a function that transforms a value into another, used via the pipe | 243 A filter is a function that transforms a value into another, used via the pipe |
| 244 syntax: `value | filter` Any function that takes exactly one argument can be | 244 syntax: `value | filter` Any function that takes exactly one argument can be |
| 245 used as a filter. | 245 used as a filter. |
| 246 | 246 |
| 247 Example: | 247 Example: |
| 248 | 248 |
| 249 If `person.name` is "John", and a top-level function named `uppercase` has been | 249 If `person.name` is "John", and a top-level function named `uppercase` has been |
| 250 registered, then `person.name | uppercase` will have the value "JOHN". | 250 registered, then `person.name | uppercase` will have the value "JOHN". |
| 251 | 251 |
| 252 The pipe syntax is used rather than a regular function call so that we can | 252 The pipe syntax is used rather than a regular function call so that we can |
| 253 support two-way bindings through transformers. A transformer is a filter that | 253 support two-way bindings through transformers. A transformer is a filter that |
| 254 has an inverse function. Transformers must extend or implement the `Transformer` | 254 has an inverse function. Transformers must extend or implement the `Transformer` |
| 255 class, which has `forward()` and `reverse()` methods. | 255 class, which has `forward()` and `reverse()` methods. |
| 256 | 256 |
| 257 ### Repeating Templates | 257 ### Repeating templates |
| 258 | 258 |
| 259 A template can be repeated by using the "repeat" attribute with a binding. The | 259 A template can be repeated by using the "repeat" attribute with a binding. The |
| 260 binding can either evaluate to an Iterable, in which case the template is | 260 binding can either evaluate to an Iterable, in which case the template is |
| 261 instantiated for each item in the iterable and the model of the instance is | 261 instantiated for each item in the iterable and the model of the instance is |
| 262 set to the item, or the binding can be a "in" iterator expression, in which | 262 set to the item, or the binding can be a "in" iterator expression, in which |
| 263 case a new variable is added to each scope. | 263 case a new variable is added to each scope. |
| 264 | 264 |
| 265 The following examples produce the same output. | 265 The following examples produce the same output. |
| 266 | 266 |
| 267 Evaluate to an iterable: | 267 Evaluate to an iterable: |
| (...skipping 20 matching lines...) Expand all Loading... | |
| 288 [web-ui@dartlang.org mailing list][web-ui-list]. | 288 [web-ui@dartlang.org mailing list][web-ui-list]. |
| 289 | 289 |
| 290 Please [file issues on Dart project page](http://dartbug.com/new) | 290 Please [file issues on Dart project page](http://dartbug.com/new) |
| 291 for any bugs you find or for feature requests. Make a note that it applies to | 291 for any bugs you find or for feature requests. Make a note that it applies to |
| 292 "package:polymer_expressions" | 292 "package:polymer_expressions" |
| 293 | 293 |
| 294 You can discuss Polymer Expressions on the | 294 You can discuss Polymer Expressions on the |
| 295 [web-ui@dartlang.org mailing list][web-ui-list]. | 295 [web-ui@dartlang.org mailing list][web-ui-list]. |
| 296 | 296 |
| 297 [web-ui-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/web-ui | 297 [web-ui-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/web-ui |
| OLD | NEW |