// Tutorial //

Getting Started with Polymer

Published on January 3, 2018
    Default avatar
    By Nipuna Gunathilake
    Developer and author at DigitalOcean.
    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

    We will be using the Polymer 2 library for this article. With some changes, these instructions can be applied to Polymer 3 once it has been released.

    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:

    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.


    Want to learn more? Join the DigitalOcean Community!

    Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

    Sign up
    About the authors
    Default avatar
    Developer and author at DigitalOcean.

    Still looking for an answer?

    Was this helpful?
    Leave a comment