-
Notifications
You must be signed in to change notification settings - Fork 5
Polymer 2.0 breaking changes #4
Comments
@rictic Is the polymer-upgrade tool usable? I'd like to upgrade my project for use with polymer 2.0.0-rc2 |
In the process of developing the upgrader we realized that it had a ton of overlap with the new linter (registry, configuration, etc). So the plan is to be able to run You can try out the new linter by running |
|
It looks I gave it a try, resulting a broken site. I noticed the problems were related to The site is hosted on https://github.com/techyizu/techyizu.github.io, the attempt of the upgrade is at branch techyizu/techyizu.github.io@8bbf336 @rictic Can you point me to which change on https://www.polymer-project.org/2.0/docs/upgrade that I need to fix manually? |
@skyred Please file a new bug with more information about what specific problems you're seeing at https://github.com/Polymer/polymer-linter |
polymer-upgrade's first project is to be a helpful companion when upgrading from Polymer v1 to Polymer v2. For every breaking change listed in the readme we should either automatically transform to the correct new code or provide a warning with an explanation of what needs to change and provide more info.
This issue will act as a tracking bug for tools support for handling those changes needed to convert from a Polymer v1 element to a hybrid Polymer v1 & v2 element.
The gold standard fix is an automatic and transformation of code here in polymer-upgrade. Next best is a lint warning or error. The remaining changes will need to be documented particularly visibly and thoroughly.
Polymer.dom
Polymer.dom
will no longer returnArray
s for API's where the platform returns e.g.NodeList
's, so code may need to be updated to avoid direct use of array methods.V1 Shadow DOM
Distribution
<content>
insertion points must be changed to<slot>
<content select="...">
must be changed to named slots:<slot name="...">
slot="..."
rather than tag/class/attributes selected by<content>
<slot>
into an element that itself has named slots requires placing aname
attribute on the<slot>
to indicate what content it selects from its host children, and placing aslot
attribute to indicate where its selected content should be slotted into its parent<slot>
is asynchronous (microtask) to creating theshadowRoot
, meaning distribution occurs after observers/ready
(in Polymer 1.0's shim, initial distribution occurred beforeready
). In order to force distribution synchronously, callShadyDOM.flush()
.Scoped styling
::content
CSS pseudo-selectors must be changed to::slotted
:host-context()
pseudo-selectors have been removed. These were primarily useful for writing bidi rules (e.g.:host-context([dir=rtl])
); these should be replaced with the new:dir(rtl)
selector, which we plan to polyfill in the styling shim soon/deep/
and::shadow
selectors have been completely removed from V1 native support and must not be used (use CSS custom properties to customize styling instead)Scoped events
Polymer.dom(event).localTarget
should change to the V1 standard APIevent.target
Polymer.dom(event).path
(aka V0event.path
) should change to the V1 standard APIevent.composedPath()
Polymer.dom(event).rootTarget
(aka V0event.path[0]
) should change to the V1 standard APIevent.composedPath()[0]
V1 Custom Elements
The V1 Custom Elements spec forbids reading attributes, children, or parent information from the DOM API in the
constructor
(orcreated
when using the legacy API). Likewise, attributes and children may not be added in theconstructor
. Any such work must be deferred (e.g. untilconnectedCallback
or microtask/setTimeout
/requestAnimationFrame
).Polymer will no longer produce type-extension elements (aka
is="..."
). Although they are still included in the V1 Custom Elements spec and scheduled for implementation in Chrome, because Apple has stated it will not implementis
, we will not be encouraging its use to avoid indefinite reliance on the Custom Elements polyfill. Instead, a wrapper custom element can surround a native element, e.g.<a is="my-anchor">...</a>
could become<my-anchor><a>...</a></my-anchor>
. Users will need to change existingis
elements where necessary.All template type extensions provided by Polymer have now been changed to standard custom elements that take a
<template>
in their light dom, e.g.should change to
Polymer()
will automatically wrap template extensions used in Polymer element templates during template processing for backward-compatibility, although we may decide to remove this auto-wrapping in the future.The
custom-style
element has also been changed to a standard custom element that must wrap a style element e.g.should change to
CSS Custom Property Shim
:root {}
:host > * {}
(in a shadow root)html {}
(in main document):root
styles for use in both main document and shadow rootvar(--a, --b)
var(--a, var(--b))
@apply(--foo)
@apply --foo;
@apply(--foo)
to@apply --foo
#3element.customStyle
as an object that can be assigned to has been removed; useelement.updateStyles({...})
instead.<style>
inside of a<dom-module>
, but outside of<template>
is no longer supporteddocument.createElement('style', 'custom-style')
) are no longer supported.Data system
set
/notifyPath
. Although theset
API remains and will often be the more efficient way to make changes, this change removes users of Polymer elements from needing to use this API, making it more compatible with alternate data-binding and state management libraries.setProperties({...})
API on Polymer elements that can be used to propagate multiple values as a coherent set.undefined
for any undefined arguments)undefined
for undefined arguments)‘notify’ events not fired when value changes as result of binding from host
properties
metadata objectPolymer.Collection
and associated key-based path and splice notification for arrays has been eliminated. See explanation here for more details.Removed API
Polymer.instanceof
andPolymer.isInstance
: no longer needed, useinstanceof
andinstanceof Polymer.Element
instead.dom-module
: Removed ability to useis
andname
attribute toconfigure the module name. The only supported declarative way set the module
id is to use
id
.element.getPropertyInfo
: This api returned unexpected information some of the time and was rarely used.element.getNativePrototype
: Removed because it is no longer needed for internal code and was unused by users.element.beforeRegister
: This was originally added for metadata compatibility with ES6 classes. We now prefer users create ES6 classes by extendingPolymer.Element
, specifying metadata in the staticconfig
property. For legacy use viaPolymer({...})
, dynamic effects may now be added using theregistered
lifecycle method.element.attributeFollows
: Removed due to disuse.element.classFollows
: Removed due to disuse.listeners
: Removed ability to useid.event
to add listeners to elements in local dom. Use declarative template event handlers instead._
are not guaranteed to exist (most have been removed)Other
created
callback is no longer called before default values inproperties
have been set. As such, you should not rely on properties set increated
from withinvalue
functions that define property defaults. However, you can now set any property defaults within thecreated
callback (in 1.0 this was forbidden for observed properties) in lieu of using thevalue
function inproperties
.false
via an attribute binding to a boolean property will not override a defaulttrue
property of the target, due to the semantics of boolean attributes. In general, property binding should always be used when possible, and will avoid such situations.lazyRegister
option removed and all meta-programming (parsing template, creating accessors on prototype, etc.) is deferred until the first instance of the element is createdNot yet implemented
<array-selector>
not yet implementedPolymer.dom
: currently most of this is emulated, but some api's may be missing. Please file issues to determine if the missing behavior is an intended breaking change.The text was updated successfully, but these errors were encountered: