Chromium Code Reviews Chromium Code Reviews
Issue 23619013:
start talking about polymer.dart (Closed)
Base URL: git@github.com:dart-lang/dartlang.org.git@master| OLD | NEW |
|---|---|
| (Empty) | |
| 1 --- | |
| 2 layout: default | |
| 3 title: "Polymer.dart" | |
| 4 description: "Standards-based Web components, templates, | |
| 5 and data binding for Dart web apps. A Dart port of the Polymer project." | |
| 6 has-permalinks: true | |
| 7 --- | |
| 8 | |
| 9 <style> | |
| 10 | |
| 11 .features h2 { | |
| 12 color: gray; | |
| 13 } | |
| 14 | |
| 15 .features i { | |
| 16 font-size: 5em; | |
| 17 } | |
| 18 | |
| 19 ol { | |
| 20 margin-left: 11px; | |
| 21 } | |
| 22 | |
| 23 .sidenav.affix { | |
| 24 top: 55px; | |
| 25 } | |
| 26 | |
| 27 hr { | |
| 28 margin: 44px 0; | |
| 29 } | |
| 30 | |
| 31 @media (min-width: 768px) and (max-width: 979px) { | |
| 32 .sidenav.affix { | |
| 33 top: 0; | |
| 34 } | |
| 35 } | |
| 36 | |
| 37 @media (max-width: 767px) { | |
| 38 .sidenav.affix { | |
| 39 position: static; | |
| 40 width: auto; | |
| 41 top: 0; | |
| 42 } | |
| 43 } | |
| 44 | |
| 45 .hero-unit h1 { | |
| 46 margin-bottom: 22px; | |
| 47 } | |
| 48 | |
| 49 </style> | |
| 50 | |
| 51 <div class="hero-unit"> | |
| 52 <h1> {{page.title}} </h1> | |
| 53 <p> | |
| 54 Build structured, encapsulated, client-side web apps with Dart and | |
| 55 web components.<br> | |
| 56 <em>A Dart port of the | |
| 57 <a href="http://www.polymer-project.org">Polymer project</a>.</em> | |
| 58 </p> | |
| 59 </div> | |
| 60 | |
| 61 <div class="row-fluid" markdown="1"> | |
| 62 | |
| 63 <div class="span3" markdown="1"> | |
| 64 | |
| 65 <div class="sidenav" data-spy="affix" data-offset-top="250" markdown="1"> | |
| 66 | |
| 67 1. ToC | |
| 68 {:toc .toc .nav .nav-list} | |
| 69 | |
| 70 </div> | |
| 71 | |
| 72 </div> | |
| 73 | |
| 74 <div class="span8" markdown="1"> | |
| 75 | |
| 76 | |
| 77 Polymer.dart, the next evolution of Web UI, is an <em>in-progress</em> | |
| 78 Dart port of the | |
| 79 [Polymer project][polymer]. | |
| 80 Polymer.dart compiles to JavaScript and runs | |
| 81 across the modern web. | |
|
mem
2013/09/04 17:39:55
If I'm coming to this without ever seeing Web UI b
sethladd
2013/09/04 21:11:02
Good point. I moved the reference to Web UI down.
| |
| 82 | |
| 83 | |
| 84 ## Features | |
| 85 | |
| 86 <div class="row-fluid features"> | |
| 87 | |
| 88 <div class="span4 text-center"> | |
| 89 | |
| 90 <i class="icon icon-code" style="color: #457FFF"> </i> | |
| 91 | |
| 92 <h2 class="no-permalink">Custom tags</h2> | |
| 93 | |
| 94 Create your own HTML tags that encapsulate | |
|
mem
2013/09/04 17:39:55
tags that -> tags to
sethladd
2013/09/04 21:11:02
Done.
| |
| 95 style, structure, and behavior. | |
| 96 | |
| 97 </div> | |
| 98 | |
| 99 <div class="span4 text-center"> | |
| 100 | |
| 101 <i class="icon icon-exchange" style="color: #FF7A5F"> </i> | |
| 102 | |
| 103 <h2 class="no-permalink">Data binding</h2> | |
| 104 | |
| 105 Live, two-way bindings for Dart objects and DOM nodes. | |
|
mem
2013/09/04 17:39:55
for Dart objects -> between Dart objects
sethladd
2013/09/04 21:11:02
Done.
| |
| 106 | |
| 107 </div> | |
| 108 | |
| 109 <div class="span4 text-center"> | |
| 110 | |
| 111 <i class="icon icon-leaf" style="color: #90CC23"> </i> | |
| 112 | |
| 113 <h2 class="no-permalink">Future proof</h2> | |
| 114 | |
| 115 Built on emerging web standards, | |
| 116 available to you today. | |
| 117 | |
| 118 </div> | |
| 119 | |
| 120 </div> | |
| 121 | |
| 122 | |
| 123 <hr> | |
| 124 | |
| 125 ## Examples | |
| 126 | |
| 127 ### Custom elements | |
| 128 | |
| 129 Extend the lexicon of HTML with your own custom elements. | |
| 130 | |
| 131 Below is a very simple custom element. More advanced custom elements | |
|
mem
2013/09/04 17:39:55
remove "very"
sethladd
2013/09/04 21:11:02
Done.
| |
| 132 can contain their own styles, custom behavior, data binding, and more. | |
| 133 | |
| 134 {% prettify html %} | |
| 135 <head> | |
| 136 <link rel="import" href="[[highlight]]hello_world.html[[/highlight]]"> | |
| 137 <script src="packages/polymer/boot.js"></script> | |
| 138 </head> | |
| 139 | |
| 140 <body> | |
| 141 [[highlight]]<hello-world></hello-world>[[/highlight]] | |
| 142 </body> | |
| 143 {% endprettify %} | |
| 144 | |
| 145 {% prettify html %}{% raw %} | |
| 146 <polymer-element name="[[highlight]]hello-world[[/highlight]]"> | |
| 147 <template> | |
| 148 <p>Hello from inside a custom element!<p> | |
| 149 </template> | |
| 150 <script type="application/dart"> | |
| 151 import 'package:polymer/polymer.dart'; | |
| 152 | |
| 153 @CustomTag('hello-world') | |
| 154 class HelloWorldElement extends PolymerElement { | |
| 155 } | |
| 156 </script> | |
| 157 </polymer-element> | |
| 158 {% endraw %}{% endprettify %} | |
| 159 | |
| 160 <hr> | |
| 161 | |
| 162 ### Data binding | |
| 163 | |
| 164 Sync object models and DOM nodes with live, two-way data binding. | |
|
mem
2013/09/04 17:39:55
Synchronize DOM nodes and object models using live
sethladd
2013/09/04 21:11:02
Done.
| |
| 165 | |
| 166 In this sample, the `count` field of `ClickCounterElement` is | |
| 167 bound to the `{% raw %}{{count}}{% endraw %}` placeholder in the custom | |
| 168 element's `<template>`. When the count field changes, the text also | |
|
mem
2013/09/04 17:39:55
should count be in code font?
sethladd
2013/09/04 21:11:02
Done.
| |
| 169 changes. | |
| 170 | |
| 171 {% prettify html %}{% raw %} | |
| 172 <polymer-element name="click-counter"> | |
| 173 <template> | |
| 174 <button on-click="increment">Click Me</button> | |
| 175 <p>You clicked the button [[highlight]]{{count}}[[/highlight]] times.</p> | |
| 176 </template> | |
| 177 <script type="application/dart"> | |
| 178 import 'package:polymer/polymer.dart'; | |
| 179 import 'dart:html'; | |
| 180 | |
| 181 @CustomTag('click-counter') | |
| 182 class ClickCounterElement extends PolymerElement with ObservableMixin { | |
| 183 [[highlight]]@observable int count[[/highlight]] = 0; | |
| 184 | |
| 185 void increment(Event e, var detail, Node target) { | |
| 186 count += 1; | |
| 187 } | |
| 188 } | |
| 189 </script> | |
| 190 </polymer-element> | |
| 191 {% endraw %}{% endprettify %} | |
| 192 | |
| 193 <hr> | |
| 194 | |
| 195 ### Template conditionals | |
| 196 | |
| 197 Control the UI with declarative conditionals and loops on templates. | |
|
mem
2013/09/04 17:39:55
Don't mention loops here. You've got that in a sec
sethladd
2013/09/04 21:11:02
Done.
| |
| 198 | |
| 199 Template conditionals are part of the data binding infrastructure. If | |
| 200 `count` changes, the templates are automatically re-evaluated. | |
| 201 | |
| 202 {% prettify html %}{% raw %} | |
| 203 <polymer-element name="click-counter"> | |
| 204 <template> | |
| 205 <button on-click="increment">Click Me</button> | |
| 206 <template [[highlight]]if="{{count <= 0}}"[[/highlight]]> | |
| 207 <p>Click the button. It's fun!</p> | |
| 208 </template> | |
| 209 <template [[highlight]]if="{{count > 0}}"[[/highlight]]> | |
| 210 <p>You clicked the button {{count}} times.</p> | |
| 211 </template> | |
| 212 </template> | |
| 213 <script type="application/dart"> | |
| 214 import 'package:polymer/polymer.dart'; | |
| 215 import 'dart:html'; | |
| 216 | |
| 217 @CustomTag('click-counter') | |
| 218 class ClickCounterElement extends PolymerElement with ObservableMixin { | |
| 219 @observable int count = 0; | |
| 220 | |
| 221 void increment(Event e, var detail, Node target) { | |
| 222 count += 1; | |
| 223 } | |
| 224 } | |
| 225 </script> | |
| 226 </polymer-element> | |
| 227 {% endraw %}{% endprettify %} | |
| 228 | |
| 229 <hr> | |
| 230 | |
| 231 ### Template loops | |
| 232 | |
| 233 Loop through a collection, rendering a template for every item in the collection . | |
|
mem
2013/09/04 17:39:55
you're not really rendering a template so much as
sethladd
2013/09/04 21:11:02
Done.
| |
| 234 | |
| 235 Template loops are part of the data binding infrastructure. If an item is | |
| 236 added or removed from `fruits`, the contents of `<ul>` are automatically | |
| 237 updated. | |
| 238 | |
| 239 {% prettify html %}{% raw %} | |
| 240 <polymer-element name="fav-fruits"> | |
| 241 <template> | |
| 242 <ul> | |
| 243 <li [[highlight]]template repeat="{{fruit in fruits}}"[[/highlight]]> | |
| 244 I like {{ fruit }}. | |
| 245 </li> | |
| 246 </ul> | |
| 247 </template> | |
| 248 <script type="application/dart"> | |
| 249 import 'package:polymer/polymer.dart'; | |
| 250 | |
| 251 @CustomTag('fav-fruits') | |
| 252 class FavFruitsElement extends PolymerElement with ObservableMixin { | |
| 253 final List [[highlight]]fruits = toObservable[[/highlight]](['apples', 'pe ars', 'bananas']); | |
| 254 } | |
| 255 </script> | |
| 256 </polymer-element> | |
| 257 {% endraw %}{% endprettify %} | |
| 258 | |
| 259 <hr> | |
| 260 | |
| 261 ### Packaging | |
| 262 | |
| 263 Reuse and share custom elements with pub, the Dart package manager. | |
|
mem
2013/09/04 17:39:55
The term pub is overloaded. It's both the tool and
sethladd
2013/09/04 21:11:02
Done.
| |
| 264 | |
| 265 {% prettify bash %}{% raw %} | |
| 266 > pub install fancy_button | |
| 267 {% endraw %}{% endprettify %} | |
| 268 | |
| 269 {% prettify html %}{% raw %} | |
| 270 <head> | |
| 271 <link [[highlight]]rel="import"[[/highlight]] | |
| 272 href="packages/fancy_button/fancy_button.html"> | |
| 273 </head> | |
| 274 <body> | |
| 275 <button [[highlight]]is="fancy-button"[[/highlight]]>Click me!</button> | |
| 276 </body> | |
| 277 {% endraw %}{% endprettify %} | |
| 278 | |
| 279 <hr> | |
| 280 | |
| 281 ## Installation | |
| 282 | |
| 283 Get polymer.dart from [pub](http://pub.dartlang.org), | |
| 284 the Dart package manager. Add the following to | |
|
mem
2013/09/04 17:39:55
the Dart package manager -> the Dart shared packag
sethladd
2013/09/04 21:11:02
Done.
| |
| 285 your `pubspec.yaml` file: | |
| 286 | |
| 287 dependencies: | |
| 288 polymer: any | |
| 289 | |
| 290 Then, run `pub install` to download the package and link it into your app. | |
| 291 | |
| 292 View the [polymer.dart pub page](http://pub.dartlang.org/packages/polymer) | |
| 293 to learn more. | |
| 294 | |
| 295 <hr> | |
| 296 | |
| 297 ## Tools | |
| 298 | |
| 299 Polymer.dart offers a validator that reports syntax or usage warnings. | |
| 300 The validator can be connected to Dart Editor to display warnings directly | |
| 301 at the source. | |
| 302 | |
| 303 More information to come. | |
| 304 | |
| 305 <hr> | |
| 306 | |
| 307 ## Upgrading from Web UI | |
| 308 | |
| 309 Here is a non-exhaustive [list of tips](upgrading-to-polymer-from-web-ui.html) | |
| 310 for developers upgrading from | |
|
mem
2013/09/04 17:39:55
The list isn't really "here".
[Upgrading to polym
sethladd
2013/09/04 21:11:02
Done.
| |
| 311 Web UI to polymer.dart. | |
| 312 | |
| 313 <hr> | |
| 314 | |
| 315 ## Compatibility | |
| 316 | |
| 317 Polymer.dart is tested against IE9, IE10, Safari 6, latest Chrome, | |
| 318 latest Firefox, and latest Chrome for Android. | |
|
mem
2013/09/04 17:39:55
does it pass?
Polymer.dart works with ...
sethladd
2013/09/04 21:11:02
"is tested" doesn't imply passing or failing, so I
| |
| 319 | |
| 320 The Dart team collaborates with the Polymer team to | |
| 321 ensure that polymer.dart elements and polyfills are fully compatible with | |
| 322 Polymer project. | |
|
mem
2013/09/04 17:39:55
first use of the term polyfill. What is it?
sethladd
2013/09/04 21:11:02
Done.
| |
| 323 | |
| 324 <hr> | |
| 325 | |
| 326 ## Support | |
| 327 | |
| 328 We actively encourage your feedback and questions. | |
| 329 | |
| 330 * Ask your [how-to questions][so] on StackOverflow | |
| 331 * Join the [general discussion about polymer.dart][web-ui-list] on our mailing | |
| 332 list | |
| 333 * Send [feedback on the web components family of specifications][polymer-dev-lis t] | |
| 334 to the polymer-dev mailing list | |
| 335 (Not Dart specific.) | |
| 336 * Please file [bugs and feature requests][dartbug] for polymer.dart | |
| 337 | |
| 338 <hr> | |
| 339 | |
| 340 ## Source code | |
| 341 | |
| 342 Polymer.dart is open source. You can view the source to polymer.dart, | |
| 343 and its many component packages, at [dart.googlecode.com/](https://code.google.c om/p/dart/source/browse/branches/bleeding_edge/dart/pkg/). | |
| 344 [Get the source](https://code.google.com/p/dart/wiki/GettingTheSource) | |
| 345 to learn how to contribute patches. | |
|
mem
2013/09/04 17:39:55
to inspect the code and contribute patches.
sethladd
2013/09/04 21:11:02
Done.
| |
| 346 | |
| 347 <hr> | |
| 348 | |
| 349 ## Status | |
| 350 | |
| 351 Polymer.dart is a work in progress, just like the Polymer project. | |
| 352 | |
| 353 ### Web UI parity | |
| 354 | |
| 355 Web UI is the precursor to polymer.dart. Polymer.dart is not quite | |
| 356 at feature parity with Web UI. Below is a list of Web UI features | |
| 357 that have not yet been implemented in polymer.dart: | |
| 358 | |
| 359 * Index iteration available as variable inside of loops | |
|
mem
2013/09/04 17:39:55
Weird to have a list of one.
Also the wording is
sethladd
2013/09/04 21:11:02
agreed... what else do we need in this list?
| |
| 360 | |
| 361 ### Polymer project parity | |
| 362 | |
| 363 One of Polymer.dart's goal is to make the entire Polymer project available | |
|
mem
2013/09/04 17:39:55
One of our goals is to make ... or
One of our goal
sethladd
2013/09/04 21:11:02
Done.
| |
| 364 to Dart developers. | |
| 365 | |
| 366 | Feature | Dart port completion | |
| 367 |-- | |
| 368 | Custom Elements | 80% | |
| 369 | Shadow DOM | 100% | |
| 370 | Observers | 100% | |
| 371 | Node.bind() | 100% | |
| 372 | Template Binding | 100% | |
| 373 | HTML imports | 90% | |
| 374 | [Polymer Core](https://github.com/Polymer/polymer) | 50% | |
| 375 | Polymer Expressions | 75% | |
| 376 | Pointer events | 0% | |
| 377 | Web animations | 0% | |
| 378 | [Polymer base elements](https://github.com/Polymer/polymer-elements) | 0% | |
| 379 | [Polymer UI elements](https://github.com/Polymer/polymer-elements) | 0% | |
| 380 {: .table} | |
| 381 | |
| 382 The percentages in the table above are subjective estimates. They attempt to | |
| 383 convey how complete the Dart port is, compared to | |
| 384 the original Polymer JavaScript code. | |
| 385 | |
| 386 <hr> | |
| 387 | |
| 388 ## Additional reading | |
| 389 | |
| 390 The cultured Dartisan studies the specifications and articles that cover | |
| 391 the lower-level primitives and features of the polymer.dart libraries. | |
| 392 | |
| 393 ### Polymer project | |
| 394 | |
| 395 * Read the [guiding principles](http://www.polymer-project.org/#guiding-principl es) | |
| 396 of the Polymer project | |
| 397 * Watch the [Hello, Polymer!](http://www.youtube.com/watch?v=irGDN5Ysi_A) | |
| 398 video featuring some of the leads of the | |
|
mem
2013/09/04 17:39:55
some of the leads -> lead members
sethladd
2013/09/04 21:11:02
Done.
| |
| 399 Polymer project. | |
| 400 | |
| 401 ### Articles | |
| 402 | |
| 403 * [HTML5Rocks - Shadow DOM 101](http://www.html5rocks.com/en/tutorials/webcompon ents/shadowdom/) | |
| 404 | |
| 405 * [HTML5Rocks - Shadow DOM 201: CSS and Styling](http://www.html5rocks.com/tutor ials/webcomponents/shadowdom-201/) | |
| 406 | |
| 407 * [HTML5Rocks - Shadow DOM 301: Advanced Concepts & DOM APIs](http://www.html5ro cks.com/tutorials/webcomponents/shadowdom-301/) | |
| 408 | |
| 409 * [Custom elements - defining new elements in HTML](http://www.html5rocks.com/en /tutorials/webcomponents/customelements/) | |
| 410 | |
| 411 ### Specifications | |
| 412 | |
| 413 Much of polymer.dart is built upon new and emerging web specifications. | |
| 414 Polymer.dart offers polyfills for the following features. | |
| 415 | |
| 416 Head's up: these are specs written for implementors. Lots of details ahead. | |
| 417 | |
| 418 [Custom elements][custom-elements-spec] | |
| 419 : A method for enabling the author to define and use new types of DOM elements. | |
| 420 | |
| 421 [Shadow DOM][shadow-dom-spec] | |
| 422 : An encapsulation primitive for DOM subtrees. It provides a method of | |
| 423 establishing and maintaining functional boundaries between DOM trees and how | |
| 424 these trees interact with each other within a document, thus enabling better | |
| 425 functional encapsulation within the DOM. | |
| 426 | |
| 427 [Template element][template-spec] | |
| 428 : A method for declaring inert DOM subtrees in HTML and manipulating them | |
| 429 to instantiate document fragments with identical contents. | |
| 430 | |
| 431 [HTML Imports][html-imports-spec] | |
| 432 : A way to include and reuse HTML documents in other HTML documents. | |
| 433 | |
| 434 | |
| 435 </div> | |
| 436 | |
| 437 </div> | |
| 438 | |
| 439 [polymer]: http://www.polymer-project.org | |
| 440 [so]: http://stackoverflow.com/tags/dart | |
| 441 [web-ui-list]: http://example.com/tbd | |
| 442 [polymer-dev-list]: http://example.com/tbd | |
| 443 [dartbug]: http://dartbug.com/new | |
| 444 [custom-elements-spec]: https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/c ustom/index.html | |
| 445 [shadow-dom-spec]: https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/shadow /index.html | |
| 446 [html-imports-spec]: https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/impo rts/index.html | |
| 447 [template-spec]: https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/template s/index.html | |
| OLD | NEW |
