| OLD | NEW |
|---|
| (Empty) | |
| 1 --- |
| 2 layout: default |
| 3 title: "Upgrading to Polymer.dart from Web UI" |
| 4 description: "Learn tips for upgrading your Web UI app to Polymer.dart." |
| 5 has-permalinks: true |
| 6 --- |
| 7 |
| 8 # {{ page.title }} |
| 9 |
| 10 Here is a non-exhaustive list of tips for developers upgrading from |
| 11 Web UI to [polymer.dart](/polymer-dart/). |
| 12 |
| 13 Do you have other tips for upgrading? Please send us a |
| 14 [pull request](https://github.com/dart-lang/dartlang.org) |
| 15 for this page, or email your tips to |
| 16 [web-ui@dartlang.org](https://groups.google.com/a/dartlang.org/forum/#!forum/web
-ui). |
| 17 Thanks in advance! |
| 18 |
| 19 ### Getting Started |
| 20 |
| 21 * You *should* include `<script src="packages/polymer/boot.js"></script>` |
| 22 and **not** dart.js in your HTML file. |
| 23 |
| 24 * The boot.js file **must** go into the `<head>` and *not* the `<body>`. |
| 25 (We may allow boot.js in the body later, |
| 26 see [issue 12388](https://code.google.com/p/dart/issues/detail?id=12388).) |
| 27 |
| 28 * We recommend creating a component for your "application" HTML page. |
| 29 Polymer believes that everything is a component. |
| 30 - This enables Polymer-style event binding, which only works inside a |
| 31 polymer-element's template. |
| 32 - This also sets up data binding to your component's fields, and turns on |
| 33 [Polymer Expressions](http://pub.dartlang.org/packages/polymer_expressions) |
| 34 in bindings. |
| 35 |
| 36 * You can place `<template>` elements on the main HTML page, but they will *not* |
| 37 be bound to the main library's scope. Polymer.dart does not support binding |
| 38 to a library scope, but you can instantiate a template by setting the |
| 39 [model](http://api.dartlang.org/docs/releases/latest/dart_html/Element.html#mo
del) |
| 40 to a Dart object. |
| 41 |
| 42 The template of a polymer element *will* be instantiate automatically with |
| 43 itself as the model, providing convenient access to its fields, exactly like |
| 44 Web UI. |
| 45 |
| 46 * To create an app that works when compiled to JavaScript, you need to first |
| 47 build it. See the |
| 48 [deploy_to_javascript](https://github.com/sethladd/dart-polymer-dart-examples/
tree/master/web/deploy_to_javascript) |
| 49 and its `build.dart` file. Notice the `--deploy` argument. |
| 50 |
| 51 ### Custom Elements |
| 52 |
| 53 * Use `<polymer-element>` instead of `<element>`. |
| 54 |
| 55 * The `extends` attribute on polymer-element is optional. If you use it, |
| 56 you should use the form of `<div is="my-element">`. If you omit the |
| 57 `extends` attribute, you are safe to use `<my-element>`. |
| 58 |
| 59 * The `constructor` attribute on polymer-element is no longer used. |
| 60 |
| 61 * Polymer.dart does **not** support polymer.js's `noscript` attribute on |
| 62 polymer-element. All custom elements must have a Dart class (see the |
| 63 next item). |
| 64 |
| 65 * Every custom element must have a Dart class. Use an empty Dart class |
| 66 if necessary. |
| 67 See [issue 12254](https://code.google.com/p/dart/issues/detail?id=12254). |
| 68 If you really don't want to create an empty class, use: |
| 69 |
| 70 {% prettify dart %} |
| 71 registerPolymerElement('my-element', () => new PolymerElement()) |
| 72 {% endprettify %} |
| 73 |
| 74 * The Dart class for the custom element must _registered_. |
| 75 An easy way to register your class is to use the |
| 76 `@CustomTag('element-name')` annotation. |
| 77 Alternatively, you can register it manually by calling |
| 78 `registerPolymerElement`. |
| 79 |
| 80 * You **must** call `super` in your `created` lifecycle callback. |
| 81 It is recommended to do this from `inserted` and `removed` as well, if you |
| 82 are inheriting from another custom element. |
| 83 |
| 84 * Go through `shadowRoot` to find nodes inside of your custom element. |
| 85 |
| 86 * The `apply-author-styles` attribute (which used to be on the |
| 87 `<polymer-element>` tag) |
| 88 is now retrieved as a getter property on the class for the custom element. |
| 89 e.g.: |
| 90 |
| 91 class MyElement extends PolymerElement { |
| 92 bool get applyAuthorStyles => true; |
| 93 // ... |
| 94 } |
| 95 |
| 96 ### Data Binding |
| 97 |
| 98 * Objects **must** be Observable to have changes detected. See the |
| 99 [observe](http://api.dartlang.org/docs/releases/latest/observe.html) |
| 100 library for more information. |
| 101 |
| 102 * Data binding expressions are now |
| 103 [Polymer Expressions](http://pub.dartlang.org/packages/polymer_expressions) |
| 104 instead of Dart expressions. Polymer Expressions are a powerful data binding |
| 105 language which offers null safety and convenient filterting operations. |
| 106 |
| 107 * Getters are no longer observable. Instead, use |
| 108 [bindProperty](http://api.dartlang.org/docs/releases/latest/observe.html#bindP
roperty) and |
| 109 [notifyProperty](http://api.dartlang.org/docs/releases/latest/observe.html#not
ifyProperty) |
| 110 in the `created` callback to let the system know that the computed getter has |
| 111 changed whenever its dependencies have changed. You can use other helpers from |
| 112 the observe library too, such as |
| 113 [PathObserver](http://api.dartlang.org/docs/releases/latest/observe/PathObserv
er.html) |
| 114 and [ListPathObserver](http://api.dartlang.org/docs/releases/latest/observe/Li
stPathObserver.html). |
| 115 |
| 116 * When manually observing an object, the |
| 117 [PropertyChangeRecord](http://api.dartlang.org/docs/releases/latest/observe/Pr
opertyChangeRecord.html) |
| 118 only has the field name, not the old and new value. You have to use mirrors to |
| 119 get the new value. This is a bug, see |
| 120 [issue 12075](https://code.google.com/p/dart/issues/detail?id=12075). |
| 121 |
| 122 * The name of the modified |
| 123 [field](http://api.dartlang.org/docs/releases/latest/observe/PropertyChangeRec
ord.html#field) |
| 124 is now a Symbol instead of a String. |
| 125 |
| 126 * Null is treated as false in `template if` expressions. |
| 127 Non-null and non-false values are treated as true. |
| 128 There are known issues with this, please track |
| 129 [issue 13044](https://code.google.com/p/dart/issues/detail?id=13044). |
| 130 |
| 131 * The `iterate` attribute no longer exists on template, use `repeat` instead. |
| 132 |
| 133 * Polymer.dart does not support the `instantiate` attribute on the template |
| 134 tag. To instantiate a template, simply bind a model to it, and ensure the |
| 135 template has a `bind` attribute. |
| 136 |
| 137 If you were using `instantiate` with a conditional, use `if`. |
| 138 |
| 139 * All data binding expressions in Polymer.dart require `{{ }}`, including |
| 140 template `if` and `repeat`. |
| 141 - Old Web UI: `template instantiate="some boolean"`. |
| 142 - New Polymer.dart: `template if="{{some boolean}}"`. |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 23619013:
start talking about polymer.dart (Closed)
Base URL: git@github.com:dart-lang/dartlang.org.git@master