Upgrade Guide for Polymer Elements from 1.x to 2.0

Upgrade guide from Polymer 1.x to Polymer 2.0 class-based element

This guide does not replace the Polymer Upgrade Guide but tries to extend it or highlight some parts. It is based on my experiences with upgrading the Polymer-based webcomponents flexible-rating and mammooc-rating-widget.

Take care of the versions in the bower.json

Some dependencies have the same version number 2.0 for Polymer 2.0, but others have different ones (especially the web-component-tester or the iron-component-page). Check these!

Change all "is"-Elements to full elements with their nested anchor

Before:

<style is="custom-stlye">
    <!-- ... -->
</style>

After:

<custom-style>
    <style>
        <!-- ... -->
    </style>
</custom-style>

Replace loading the webcomponents-lite.js with the webcomponents-loader.js

Before:

<script src="../../webcomponentsjs/webcomponents-lite.min.js"></script>

After:

<script src="../../webcomponentsjs/webcomponents-loader.js"></script>

Replace imports of polymer.html with polymer-element.html and other parts as required.

If you use additional components, such as <dom-repeat>, <dom-if>, <dom-module>, <dom-bind> or <custom-style>, you must include these separatly.

Before:

<link rel="import" href="../../polymer/polymer.html">

After:

<link rel="import" href="../polymer/polymer-element.html">
<!-- Additional imports -->
<link rel="import" href="../polymer/lib/elements/dom-repeat.html">

CSS Selectos changed, add paranthesis!

Before:

:host:focus {
    outline-color: red;
}

After:

:host(:focus) {
    outline-color: red;
}

CSS selector ::content is no longer available, remove or replace

Before:

:host:not(:disabled) .star-wrapper:hover ::content > span {
    cursor: pointer;
}

After:

:host(:not([disabled])) .star-wrapper:hover > span {
    cursor: pointer;
}

CSS mixins no longer use paranthesis

Before:

@apply(--paper-font-headline);

After:

@apply --paper-font-headline;

CSS mixins no require shim import

After:

<link rel="import" href="../shadycss/apply-shim.html">

Add "use strict";

Before:

<script>
    <!-- ... -->
</script>

After:

<script>
    "use strict";
    <!-- ... -->
</script>

Polymer no longer holds a dictionary, but is a class with functions. Adapt as follows:

is: to is()

Before:

is: 'flexible-rating',

After:

static get is() {
    return 'flexible-rating';
}

behaviors: to mixinBehaviors[...]

The behaviors are now included at the very begining, when the class is declared. Choose a custom name for your class (ususally simiar to is(), but with CamelCase)!

Before:

behaviors:
    [
        Polymer.IronFormElementBehavior,
        Polymer.IronValidatableBehavior,
        Polymer.IronA11yKeysBehavior,
        Polymer.IronControlState
    ],

After:

class FlexibleRating extends Polymer.mixinBehaviors([
    Polymer.IronFormElementBehavior,
    Polymer.IronValidatableBehavior,
    Polymer.IronA11yKeysBehavior,
    Polymer.IronControlState
], Polymer.Element) {

properties: to properties

Before:

properties: {
    /**
     *   The maximum number of stars possible.
     */
    max: {
        type: Number,
        value: 5,
        notify: true
    }
}

After:

static get properties() {
    return {
        /**
         *   The maximum number of stars possible.
         */
        max: {
            type: Number,
            value: 5,
            notify: true
        }
    }
}

observers: to observers()

Before:

observers: [
    '_updateAria(value, max)'
]

After:

static get observers() {
    return [
        '_updateAria(value, max)'
    ]
}

keyBindings: to keyBindings()

Before:

keyBindings: {
    'left down pagedown home': '_decrementKey',
    'right up pageup end': '_incrementKey'
}

After:

static get keyBindings() {
    return {
        'left down pagedown home': '_decrementKey',
        'right up pageup end': '_incrementKey'
    }
}

Update to ES6 sytle JS code

Before:

_increment: function() {
    this._updateValue(Math.floor(this.value) + 1);
},

After:

_increment() {
    this._updateValue(Math.floor(this.value) + 1);
}

hostAttributes: to be included in ready() (see below for more details)

Before:

hostAttributes: {
    role: 'slider',
    tabindex: 0,
    'aria-hidden': 'true'
},

After:

ready() {
    this._ensureAttribute('role', 'slider');
    this._ensureAttribute('tabindex', 0);
    this._ensureAttribute('area-hidden', 'true');
    super.ready();
}

listeners: to be included in ready() (see below for more details)

Before:

listeners: {
    'api-load': '_apiLoaded',
    'post-sent': '_postSent'
},

After:

ready() {
    this.addEventListener('api-load', this._apiLoaded.bind(this));
    this.addEventListener('post-sent', this._postSent.bind(this));
    super.ready()
}

Add ready() function, your element won't show up otherwise!

This is added to the class definition. It could be empty or call super:

After:

ready() {
    super.ready();
}

Register custom elemen, your element won't show up otherwise!

This registration is done outside of the class definition because functions of the class are used.

After:

    <!-- ... -->
    // Register custom element definition using standard platform API
    customElements.define(FlexibleRating.is, FlexibleRating);
</script>

Remove Polymer.dom(...) wrapper

Before:

Polymer.dom(editableFixture.root).querySelectorAll('.star-wrapper > span');

After:

editableFixture.root.querySelectorAll('.star-wrapper > span');

A Implementation ot the LocalizeBehavior is changed as followed

Before:

MammoocLocalizeBehaviorImpl = {
    properties: {
        language: {
            // ...
        }
    }
}

MammoocLocalizeBehavior = [Polymer.AppLocalizeBehavior, MammoocLocalizeBehaviorImpl];

After:

class MammoocLocalizeBehaviorImpl {
    static get properties() {
        return {
            language: {
                // ...
            }
        }
    }
}

MammoocLocalizeBehavior = [Polymer.AppLocalizeBehavior, MammoocLocalizeBehaviorImpl];