Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(942)

Side by Side Diff: pkg/polymer_expressions/README.md

Issue 51003002: Update headings to use sentence case. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Created 7 years, 1 month ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « pkg/http_server/README.md ('k') | pkg/scheduled_test/lib/scheduled_test.dart » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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
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 &lt;input&gt; element's value field to a model 138 most common case is to bind an &lt;input&gt; 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
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
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
OLDNEW
« no previous file with comments | « pkg/http_server/README.md ('k') | pkg/scheduled_test/lib/scheduled_test.dart » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698