Simple Component

Let’s consider a very simple example. The project consists of two files: index.html and alert-button.html.

  • alert-button.html defines a Polymer component.

  • index.html uses this component.

See the source code and the result below.

Tip

You can play with the example in an application created and deployed by Studio by copying the below files to your deploy/tomcat/webapps/app-front folder keeping the relative paths. That is index.html should replace the existing file in the web application root, and alert-button.html must be created in the new src/polymer-basic/simple-component subdirectory.

index.html
<html>
<!-- index.html is an entry point of our application. -->
<!-- Usually it loads one root Polymer element which contains all other components. -->
<head>
    <!-- Import of a web component we want to use. -->
	<link rel="import" href="src/polymer-basic/simple-component/alert-button.html">
	<!-- Polyfills. -->
    <!-- Natively web-components work only in Google Chrome. -->
    <!-- For all other browsers polyfills are required. -->
	<script src="bower_components/webcomponentsjs/webcomponents-loader.js"></script>
</head>
<body>
  <alert-button>
    <!-- This text goes to the <slot/> element of the Polymer component. -->
    Our first simple component - alert button!
  </alert-button>
</body>
</html>
src/polymer-basic/simple-component/alert-button.html
<!-- polymer-element.html contains a base class for all our custom web components -->
<link rel="import" href="../../../bower_components/polymer/polymer-element.html">

<dom-module id="alert-button">
  <template>
    <style>
      /* CSS put here is applicable only to this particular component. */
      /* Other HTML in the application won't be affected by it. */
      /* That is, if some other Polymer element will use .cuba-btn class, this CSS block won't affect it. */
      .cuba-btn {
        background: #006ba9;
        border: 1px solid #006ba9;
        border-radius: 5%;
        color: #ffffff;
        padding: 5px 10px;
      }
    </style>

    <h3>
      <!-- Here goes any HTML passed to Polymer component -->
      <slot></slot>
    </h3>

    <!-- onClick handler will call a function declared inside our Polymer element -->
    <button class="cuba-btn" on-click="greetUser">Push me please!</button>

  </template>
  <script>
    // Our web component has to extend Polymer.Element class
    class AlertButton extends Polymer.Element {
      // Return value of 'is' has to match the value specified in dom-module[id]
      static get is() {
        return 'alert-button';
      }

      // We can declare functions here and call them from handlers in HTML
      greetUser() {
        alert('Hello, User!');
      }
    }

    // customElements is a global object used to register all our custom web components
    customElements.define(AlertButton.is, AlertButton);
  </script>
</dom-module>

Result

Our first simple component - alert button!

So, alert-button is a component that is represented by a button and an optional caption. On click, the button shows the "Hello, User!" message. The code using this component provides a content in the <alert-button/> tag. This content is displayed by the slot element inside the component. However, the slot element is not required and can be omitted.

These are the basics that allow you to write and use simple Polymer components.

Tip

index.html in our example contains a polyfill script. This script checks what exactly our browser doesn’t support (HTML imports, shadow DOM, custom elements) and loads only polyfills that are really required. See details here.

What we have learned so far
  • Polymer components are declared in HTML files inside the dom-module tag.

  • Each Polymer component file can contain CSS (optional), HTML (optional) and JavaScript (mandatory).

  • A Polymer component is declared by creating a class that extends Polymer.Element and registering it with customElements object. Our web component must contain the is static property which has to match the id of the dom-module element. This id is used to refer to the component afterwards.

  • Polymer component class can contain an arbitrary number of functions that can be called in handlers from HTML.

  • CSS declared in Polymer components don’t affect the rest of the application.

  • Polymer components can import and use other Polymer components.