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