A Guide to Upgrading to Polymer 1.0

Share this article

At the recently concluded Google IO 2015, Google released the much awaited 1.0 version of Polymer and declared it production-ready. For those of you who have been using the Polymer library while it was still in developer preview, this article will serve as a guide to migrate your existing application to the latest version of Polymer.

A few important things to note about v1.0:

  1. It is incompatible with version 0.5, the previous version and the longest surviving so far.
  2. The new release is focused on performance and efficiency while dramatically reducing the overall size of the library.
  3. It has been completely rebuilt from the ground-up to make it easier and faster for developers to design custom elements that work more like standard DOM elements.
  4. Internal benchmark tests reveal that v1.0 is about 3x faster on Chrome and 4x faster on Safari compared to the previous version.

The steps to install the latest version of Polymer remain exactly the same as described in this article. To update an existing installation of Polymer, navigate to the app directory and run the following command in your terminal:

$ bower update

It’s important to be aware that this will certainly break your existing app, since, as mentioned, the two versions are incompatible. Hence, installing a fresh copy in a separate folder is recommended instead. To illustrate the changes since v0.5, we’ll use the credit card custom element from one of my previous articles on SitePoint as a reference to draw comparisons between the two versions.

Polyfilling non-supporting browsers

The new version of Polymer no longer needs the shadow DOM polyfill included in the webcomponents.js library. Instead use the much smaller webcomponents-lite.js library to polyfill older browsers.

Version 0.5:

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

Version 1.0:

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

The “lite” version offers a size gain of approximately 80kb over its predecessor, which could be significant when performance is a key factor.

Defining custom elements

The <polymer-element> tag has been replaced by the <dom-module> tag that holds the definition of a custom element. The custom element is now identified by the id attribute of the <dom-module> tag. The rules to name the custom element still remain the same.

Version 0.5:

<polymer-element name="credit-card">
  ...
</polymer-element>

Version 1.0:

<dom-module id="credit-card">
  ...
</dom-module>

Register custom elements

Previously, we could register the custom element by simply invoking the Polymer() constructor. Specifying the custom element name was optional if the <script> tag was inside the <polymer-element> tag. In this release, the custom element is now registered by using the is property on the prototype.

Version 0.5:

Polymer('credit-card', {});

Version 1.0:

Polymer({
  is: 'credit-card'
});

The value of the is property must match the id attribute of the <dom-module> tag of the custom element and, unlike the previous release, this is not optional.

The <script> tag can be inside or outside of the <dom-module> element, but the element’s template must be parsed before the call to the Polymer constructor.

Custom element attributes

Any attribute that is part of the <polymer-element> tag should now be declared on the properties object along with the data type.

Version 0.5:

<polymer-element name='credit-card' attributes='amount'>

Version 1.0:

Polymer({
  is: 'credit-card',
  properties: {
    amount: {
      type: Number
    }
  }

Custom element styles

The element styles are now defined outside the <template> tag.

Version 0.5:

<polymer-element name="credit-card" attributes="amount">
  <template>
    <style>
      ...
    </style>
  </template>
</polymer-element>

Version 1.0:

<dom-module id="credit-card">
  <style>
    ...
  </style>

  <template>
    ...
  </template>
</dom-module>

External stylesheets are supported using HTML Imports.

Data binding

Polymer 1.0 offers two types of data bindings:

  • Square brackets [[]] create one-way bindings. Data flow is downward, host-to-child, and the binding never modifies the host property.
  • Curly brackets {{}} create automatic bindings. Data flow is one-way or two-way, depending whether the target property is configured for two-way binding or not.

In this release, a binding must replace the entire text content of a node, or the entire value of an attribute. So string concatenation is not supported. For attribute values, it is recommended to use computed bindings instead of string concatenation.

Version 0.5:

<input type="submit" value="Donate {{amount}}">

Version 1.0:

<template>
  <input type="submit" value="[[computeValue(amount)]]">
</template>
Polymer({
  is: "inline-compute",
  computeValue: function(amount) {
    return 'Donate ' + amount;
  }
});

Note that this means a node can’t include any white space around the binding annotation.

The new shady DOM

Polymer v0.5 used shadow DOM to provide a simpler element interface to the developer and abstracts all the complexities by hiding the subtrees behind a shadow root. This forms the basis of encapsulation, which works well in browsers that supports shadow DOM.

For browsers that do not yet support shadow DOM, implementing a polyfill that works exactly like native shadow DOM is difficult, often slower than the native implementation, and needs a lot of code. For these reasons, the Polymer team decided to do away with the shadow DOM polyfill and instead built a much lighter version of the local DOM that offers encapsulation similar to shadow DOM.

It’s important to note that shady DOM and shadow DOM are compatible with each other, which means that the shady DOM API uses the native shadow DOM in browsers when it’s available and falls back to the shady DOM in non-supporting browsers.

Conclusion

Upgrading your app to Polymer v1.0 could be a painfully slow process depending on the complexity of your app, but offers great benefits in terms of faster load time and significantly smaller payload. The official migration guide available on the Polymer project website covers a bunch of the other changes to the internal APIs in greater depth so be sure to check that out.

Additionally, Chuck Horton has set up a Github repository called Road to Polymer 1.0 that offers a code convert tool to update your code to v1.0 from v0.5. This could serve as a starting point for your migration if you’re not up to making some of the cosmetic changes manually.

Frequently Asked Questions about Upgrading to Polymer 1.0

What are the key differences between Polymer 0.5 and Polymer 1.0?

Polymer 1.0 is a complete rewrite of the previous version, Polymer 0.5. The new version is more efficient, with a smaller footprint and faster performance. It also introduces a new, streamlined syntax that is easier to understand and use. The data binding system has been overhauled for better performance and more intuitive behavior. Additionally, Polymer 1.0 has better support for creating custom elements, which are a key part of the Web Components standard.

How do I upgrade my project from Polymer 0.5 to Polymer 1.0?

Upgrading from Polymer 0.5 to Polymer 1.0 involves several steps. First, you need to update your Bower dependencies to point to the new Polymer 1.0 elements. Then, you need to update your HTML imports to load the new elements. You also need to update your element definitions and data bindings to use the new Polymer 1.0 syntax. Finally, you need to test your project thoroughly to ensure that everything works as expected.

What is the Shadow DOM and how does it work in Polymer 1.0?

The Shadow DOM is a key part of the Web Components standard. It provides a way to encapsulate the implementation details of a custom element, hiding its internal structure and styles from the rest of the page. In Polymer 1.0, you can use the Shadow DOM to create custom elements that are fully encapsulated and reusable.

How do I style elements in the Shadow DOM?

Styling elements in the Shadow DOM can be a bit tricky, because they are encapsulated and isolated from the rest of the page. However, Polymer 1.0 provides several ways to style Shadow DOM elements. You can use CSS custom properties to define styles that can be applied inside the Shadow DOM. You can also use the ::shadow and /deep/ selectors to pierce the Shadow DOM and style elements inside it.

What are the new features in Polymer 1.0?

Polymer 1.0 introduces several new features and improvements. It has a new, streamlined syntax that is easier to understand and use. It has a more efficient data binding system, with better performance and more intuitive behavior. It has better support for creating custom elements, with a simpler API and more powerful capabilities. It also has improved support for mobile devices, with better touch event handling and smoother animations.

How does data binding work in Polymer 1.0?

Data binding in Polymer 1.0 is more efficient and intuitive than in the previous version. You can bind data to properties and attributes of elements, and the bindings are automatically updated when the data changes. You can also use computed properties and observers to react to changes in the data.

How do I create custom elements in Polymer 1.0?

Creating custom elements in Polymer 1.0 is easier and more powerful than in the previous version. You can define a custom element by creating a new Polymer element prototype, specifying its properties, methods, and event handlers. You can also define the element’s internal structure and styles using the Shadow DOM.

What are the performance improvements in Polymer 1.0?

Polymer 1.0 is more efficient than the previous version, with a smaller footprint and faster performance. It has a more efficient data binding system, which reduces the amount of work needed to update the DOM. It also has better support for mobile devices, with better touch event handling and smoother animations.

How do I use Polymer 1.0 with other libraries and frameworks?

Polymer 1.0 is designed to be compatible with other libraries and frameworks. You can use it alongside jQuery, Angular, React, or any other library or framework you like. You can also use Polymer elements as part of a larger application, or you can build an entire application using Polymer.

What are the best practices for using Polymer 1.0?

When using Polymer 1.0, it’s important to follow best practices to ensure that your code is efficient, maintainable, and easy to understand. You should use the new Polymer 1.0 syntax, which is more streamlined and intuitive. You should encapsulate the implementation details of your elements using the Shadow DOM. You should use data binding to keep your UI in sync with your data. And you should test your elements thoroughly to ensure that they work correctly in all supported browsers.

Pankaj ParasharPankaj Parashar
View Author

Pankaj Parashar is a frontend designer and web developer from Mumbai, India. He is extremely passionate about the web, loves experimenting with new web technologies, and occasionally writes about them on his blog.

custom elementsLouisLpolymerpolymer 1.0shadow dom
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week