Polymer Custom Elements

Polymer.js framework facilitates you to create custom elements using standard HTML elements.

Features of custom elements:

It facilitates you to name custom elements with associating class.
When you change the state of custom element instance, it will request the lifecycle callbacks.
If you change the attributes on an instance, then callback will be requested.

You can define the custom element using ES6 class. Class can be associated with the custom element like this:

//ElementDemo class is extending the HTMLElement 
class ElementDemo extends HTMLElement { 
   // code here
};
//link the new class with an element name
window.customElements.define('element-demo', ElementDemo);

We can use custom element as standard element:

Note: Custom element name should start with a lower case letter and contain a dash between the names.

Custom Element Lifecycle

Custom element lifecycle provides a set of custom element reactions which are responsible for changing in element lifecycle

Following is a list of those custom element reactions:

Table:

Index	Reactions	Description
1)	constructor	This element's reaction is called when you create an element or define the previously-created element.
2)	connectedCallback	This element's reaction is called when you add an element to a document.
3)	disconnectedCallback	This element's reaction is called when you remove an element from a document.
4)	attributeChangedCallback	This element's reaction is called whenever you change, append, remove, or replace an element from a document.

Element Upgrades

We can use custom elements before defining them by specification and any existing instances of an element will be upgraded to the custom class by adding a definition to that element.

The custom element state contains the following values -

Uncustomized: The valid custom element name is either a built-in element or an unknown element, which cannot become a custom element.

Undefined: The element can have a valid custom element name, but it cannot be defined.

Custom: The element can have a valid custom element name, which can be defined and upgraded.

Failed: Trying to upgrade the failed element of an invalid class.

Define an Element

We can define a custom elements by creating a class which extends Polymer.Element and it passes the class to customElements.define method. The class contains is getter method that returns a HTML tag name of the custom element.

For example:

//ElementDemo class is extending the Polymer.Element 
class ElementDemo extends Polymer.Element {
   static get is() { return 'element-demo'; }
   static get properties() {
      . . .
      . . .
   }
   constructor(){
      super();
      . . .
      . . .
   }
   . . .
   . . .
}
//Associate the new class with an element name
window.customElements.define(ElementDemo.is, ElementDemo);
// create an instance with createElement
var el1 = document.createElement('element-demo');

Import And APIs

We can define Polymer elements by specifying the three HTML imports:

polymer-element.html: It is used to specify the Polymer Element base class.

legacy-element.html: It is used to extend Polymer.Element using Polymer. Legacy Element base class and adds 1.x compatible legacy API. It also creates hybrid elements by defining the legacy Polymer() factory method.

polymer.html: It is used to comprise the Polymer base classes along with helper elements, which were included in the 1.x polymer.html.

Define an Element in the Main HTML Document

The HTMLImports.whenReady() function is used to define an element in the main HTML document.

Example

Let's take an example to define an element in the main HTML document. Create an index.html file and use the following code:

<!doctype html>
<html lang = "en">
   <head>
      <title>Polymer Example</title>
      <script src = "bower_components/webcomponentsjs/webcomponents-lite.js"></script>
      <link rel = "import" href = "bower_components/polymer/polymer.html">
      <link rel = "import" href = "define-element.html">
   </head> 
   <body>
      <define-element></define-element>
   </body>
</html>

Now create a custom element called define-element.html and use the following code.

<dom-module id = "define-element">
   <template>
      <h2>Hello JavaTpoint!!</h2>
   </template>
   <script>
      HTMLImports.whenReady(function(){
         Polymer ({
            is: "define-element"
         })
      })  
   </script>
</dom-module>

Output: