Web UI

Polymer Guide

Updated: January 16, 2017 Page Information Edit on GitHub

Why Polymer?

Polymer presents itself as a simple JavaScript library that enables using and creating Web Components in modern browsers. It leverage the browser as the platform, and offers polyfills to enable features not yet available in all browsers.

We recommend reading our blog posts Web Components - a Great Standard for a Platform Approach and Web Components - Getting started which provides a good overview about Web Components and why we've decided to use Polymer.

If you're new to Polymer the best place to start is at www.polymer-project.org. The Polymer documentation provides some simple guides and tutorials to help you build an element or even build an app from the ground.

Best Practices

"Everything is an element" being Polymer's mantra, we should think of elements as our building blocks when creating an application (and even custom elements themselves). The challenging part is to decide how to break down our application into meaningful elements.

Generally an element should be:

  • Simple
  • Reusable
  • Composable
  • Self-contained and ready to use out of the box
  • Stylable and responsive

The overall idea is to spend less time writing complex JavaScript, and rely on composition to create our applications and elements in a more declarative way. The communication between those elements is generally accomplished using data binding and events.

Fortunately Polymer already provides a solid Elements Catalog that follows these general rules and also addresses the most common patterns used in web development with Web Components. The source code of these elements is available on GitHub and is well documented, making this one of the best resources to learn how to use Polymer.

When developing applications with lots of elements and/or involving complex data flows, data binding can become a nightmare very quickly (especially when using two-way binding). There's a nice pattern that we recommend which is well described in this book sample.

"Data rains down from parent to child via attribute binding. Data then evaporates back up in the form of events. And just as in real life, something is very wrong if this cycle is reversed."

In summary, as a rule of thumb, an element should communicate (pass data) to children elements using one-way binding through properties, and the other way around child elements should fire events that parent elements can listen to.

Once you become more familiar with Polymer we strongly recommend reading our Polymer blog post series. They provide useful information, code samples, and insights through the journey of migrating our UI from server side to client side. Some examples that might be useful:

Other Useful Resources

  • Codelabs "Google codelabs provide guided, tutorial, hands-on coding experiences. Most codelabs will step you through the process of building a small application, or adding a new feature to an existing application."
  • Polycasts "Learn about the basic building blocks that make up a Polymer application, and see how to compose those elements into buttery smooth mobile experiences. The future of front end development is all here, on the Polycasts playlist!"
  • Web Component Tester "Makes testing your web components a breeze!"
  • Polymer Themes "Free Polymer Themes & Templates"
  • Polymer Projects "List of projects made with Polymer"
3 months ago Karin Touchie NXDOC-1034: Review Web UI documentation
4 months ago GitHub Update review date
4 months ago Guillaume Renard NXDOC-1012: move polymer guide at the root
History: Created by Guillaume Renard