Getting Started with Polymer

Web Components offer a great way of creating, using and sharing custom components for the web. Polymer is a lightweight library that lets us take advantage of these elements right now. Polymer simplifies Web Components implementation and adds some useful features on top.

Polymer is made up of two main parts:

• Polymer Library, which offers a set of features that make it easier to create, use and share Web Components
• Polymer Toolkit which offers an additional collection of tools, components, and templates to make it easier to build full applications using Web Components

In this article, we’ll look at creating a simple custom web component using the Polymer Library and the Polymer CLI.

We will start by re-creating <my-title> element that was created in this intro to custom elements

Prerequisites

You will need to have the following setup in order to install and use Polymer:

• npm - Node and the node package manager, required to install the Polymer CLI
• bower - Required to manage the frontend dependencies

Polymer CLI

The Polymer CLI is a command line tool that helps with multiple aspects of Polymer-based app development. Some of the commands it offers are as follows:

• polymer init - Boilerplate generation for apps and elements
• polymer serve - Development server for live development
• polymer lint - Polymer-specific linting
• polymer test - Test runner
• polymer build - Build production ready apps

We’ll be using the boilerplate generation and development server in this article.

Installing the CLI

The Polymer CLI can be installed using the following command:

$ npm install -g polymer-cli

To confirm that the tool has been installed successfully and the see a list of all available commands, use:

$ polymer --help

Start Polymer Element Project

Create a new directory and navigate into it:

$ mkdir my-title
$ cd my-title

Use the Polymer CLI to initialize an element project. This will start the process of generating the Polymer element.

$ polymer init

This command will ask for some configurations. We will be using the following settings:

• Select the first option, polymer-2-element, to generate a custom element
• We can use the default name of my-title for the element
• Leave the description empty
• The Polymer CLI will automatically install the bower dependencies for the project

Generated folder structure

This will generate a folder structure as follows:

/bower.json         // List of front-end dependencies
/bower_components/  // The bower dependencies are saved here
/demo/              // Demo folder containing a working example of our component
/index.html         // Starting point (re-directs to demo/index.html)
/my-title.html      // Web component definition
/polymer.json       // Polymer settings
/README.md          // Automatically generated Readme
/test/              // Tests for the component

The Polymer CLI does most of the heavy lifting for creating a custom component. As we’ll find out, this file structure already includes the basic setup we need for a Web Component as well as the polyfills that are needed.

Generated element

We can look at the Polymer element that has been generated by opening up ./my-title.html:

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

<dom-module id="my-title">
  <template>
    <style>
      :host {
        display: block;
      }
    </style>
    <h2>Hello [[prop1]]!</h2>
  </template>

  <script>
    class MyTitle extends Polymer.Element {
      static get is() { return 'my-title'; }
      static get properties() {
        return {
          prop1: {
            type: String,
            value: 'my-title'
          }
        };
      }
    }

    window.customElements.define(MyTitle.is, MyTitle);
  </script>
</dom-module>

This generated component is somewhat similar what we would build as a native Web Component. But there are a few key differences here:

• We are using HTML imports instead of ES6 imports. (In polymer 3.0, ES6 Imports will be replacing the HTML imports)
• Polymer automatically creates a Shadow DOM for the <template> supplied. This helps isolate the element.
• The class extends from Polymer.Element instead of HTMLElement. The Polymer.Element adds new functionality to Web Components such as data binding.

View element in action

In order to demo the custom component, we can use the following command:

$ polymer serve --open

This command will serve the demo page on a local development server.

Customizing our Element

Finally, we can customize the element to look similar to the one created in the web component custom element article.

For this, first we need to add the styles:

<style>
  :host {
    display: block;
  }

  h1 {
    font-size: 2.5rem;
    color: hotpink;
    font-family: monospace;
    text-align: center;
    text-decoration: pink solid underline;
    text-decoration-skip: ink;
  }
</style>

Then we can set the text value:

<h1>Hello Alligator!</h1>

That’s it! We now have an almost identical element. This element can be used in a Polymer application using html imports.

Conclusion

As you can see, Polymer makes the process of generating Web Components much simpler that it otherwise would be. In addition to that, Polymer adds features on top of to the already very useful Web Components.

Finally, since the Polymer CLI handles the build process, we will not have to manually handle the polyfills and other browser support concerns when it comes to distributing the application.