Polymère - Éléments personnalisés

Polymer est un framework qui permet de créer des éléments personnalisés à l'aide d'éléments HTML standard. Les éléments Web personnalisés offrent les fonctionnalités suivantes:

• Il fournit un nom d'élément personnalisé avec la classe associée.

• Lorsque vous modifiez l'état de l'instance d'élément personnalisé, il demandera les rappels de cycle de vie.

• Si vous modifiez les attributs sur une instance, un rappel sera demandé.

Vous pouvez définir l'élément personnalisé à l'aide de la classe ES6 et la classe peut être associée à l'élément personnalisé comme indiqué dans le code suivant.

//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);

L'élément personnalisé peut être utilisé comme élément standard comme indiqué ci-dessous -

<element-demo></element-demo>

Note - Le nom d'élément personnalisé doit commencer par une lettre minuscule et contenir un tiret entre les noms.

Cycle de vie des éléments personnalisés

Le cycle de vie des éléments personnalisés fournit un ensemble de réactions d'élément personnalisées qui sont responsables de la modification du cycle de vie des éléments et sont définies dans le tableau suivant.

N ° Sr.	Réactions et description
1	constructor Lorsque vous créez un élément ou définissez l'élément créé précédemment, cette réaction d'élément sera appelée.
2	connectedCallback Lorsque vous ajoutez un élément à un document, cette réaction d'élément sera appelée.
3	disconnectedCallback Lorsque vous supprimez un élément d'un document, cette réaction d'élément est appelée.
4	attributeChangedCallback Chaque fois que vous modifiez, ajoutez, supprimez ou remplacez un élément d'un document, cette réaction d'élément sera appelée.

Mises à niveau des éléments

Nous pouvons utiliser des éléments personnalisés avant de les définir par spécification et toutes les instances existantes d'un élément seront mises à niveau vers la classe personnalisée en ajoutant une définition à cet élément.

L'état de l'élément personnalisé contient les valeurs suivantes -

• uncustomized - Le nom d'élément personnalisé valide est soit un élément intégré, soit un élément inconnu, qui ne peut pas devenir un élément personnalisé.

• undefined - L'élément peut avoir un nom d'élément personnalisé valide, mais il ne peut pas être défini.

• custom - L'élément peut avoir un nom d'élément personnalisé valide, qui peut être défini et mis à niveau.

• failed - Tentative de mise à niveau de l'élément défaillant d'une classe non valide.

Définition d'un élément

Un élément personnalisé peut être défini en créant une classe qui étend Polymer.Element et qui transmet la classe à la méthode customElements.define. La classe contient une méthode getter qui renvoie un nom de balise HTML de l'élément personnalisé. Par exemple -

//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');

Imports and APIs

The Polymer elements can be defined by specifying the following three HTML imports −

• polymer-element.html − It specifies the Polymer.Element base class.

• legacy-element.html − It extends Polymer.Element using Polymer.LegacyElement base class and adds 1.x compatible legacy API. It also creates hybrid elements by defining the legacy Polymer() factory method.

• polymer.html − It comprises 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

You can define an element in the main HTML document using HTMLImports.whenReady() function.

Example

The following example shows how to define an element in the main HTML document. Create an index.html file and add 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 include the following code.

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

Output

To run the application, navigate to the created project directory and run the following command.

polymer serve

Now open the browser and navigate to http://127.0.0.1:8081/. Following will be the output.

Define a Legacy Element

Legacy element can be used to register an element using the Polymer function, which takes the prototype for a new element. The prototype should contain is which defines the HTML tag name for a custom element.

Example

//registering an element
ElementDemo = Polymer ({
   is: 'element-demo',
   
   //it is a legecy callback, called when the element has been created
   created: function() {
     this.textContent = 'Hello World!!!';
   }
});

//'createElement' is used to create an instance
var myelement1 = document.createElement('element-demo');

//use the constructor create an instance
var myelement2 = new ElementDemo();

Lifecycle Callbacks

Lifecycle callbacks are used to accomplish the tasks for built-in features of Polymer.Element class. Polymer uses ready callback, which will be invoked when Polymer completes creating and initializing DOM elements.

Following is a list of legacy callbacks in Polymer.js.

• created − It is called when you create an element before setting the property values and initializing local DOM.

• ready − It is called when you create an element after setting the property values and initializing local DOM.

• attached − It is called after attaching the element to the document and can be called more than one time throughout the lifetime of an element.

• detached − It is called after detaching the element from the document and can be called more than once throughout the lifetime of an element.

• attributeChanged − It is called when there are changes in an element's attributes and it holds the attribute changes, which are not compatible with the declared properties.

Declaring Properties

The properties can be declared on an element to add default value and other specific features in the data system and they can be used to specify the following features −

• It specifies the property type and default value.

• It calls the observer method, when there are changes in the property value.

• It specifies the read-only status to stop the unexpected changes to the property value.

• It provides support for two-way data binding, which triggers an event when you change the property values.

• It is a computed property, which calculates a value dynamically depending on the other properties.

• It updates and reflects the corresponding attribute value, when you change the property values.

The following table shows keys for each property, which are supported by the properties object.

Sr.No.	Key & Description	Type
1	type It deserializes from an attribute whose property type is determined using the type's constructor.	constructor (Boolean, Date, Number, String, Array or Object)
2	value It specifies the default value for the property and if it is a function, then it uses the return value as the default value of the property.	boolean, number, string or function.
3	reflectToAttribute If this key sets to true, then it sets the corresponding attribute on the host node. The attribute can be created as a standard HTML boolean attribute, if you set the property value as Boolean.	boolean
4	readOnly You cannot set the property directly by assignment or data binding, if this key is set to true.	boolean
5	notify You can use the property for two-way data binding, if this key is set to true and when you change the property, property-name-changed event will get triggered.	boolean
6	computed You can calculate the value of an argument whenever it changes, by invoking the method and value will be simplified as method name and argument list.	string
7	observer Invoke the method name, which is simplified by a value, when the property value changes.	string

Attribute Deserialization

Deserialize the property name that matches an attribute on instance according to the type specified and the same property name on the element instance, if the property is configured in the properties object.

You can set the specified type directly as the value of the property, if there are no other properties options defined in the properties object; otherwise, it will provide the value to the type key in the properties configuration object.

Configuring Boolean Properties

The Boolean property can be configured from markup, by setting it to false and if it is set to true, then you cannot configure from markup because the attribute with or without a value is equalized to true. Therefore, it is known as a standard behavior for attributes in the web platform.

The object and array properties can be configured by passing them in JSON format as −

<element-demo player = '{ "name": "Sachin", "country": "India" }'></element-demo>

Configuring Default Property Values

The default property can be configured using the value field in the properties object and it may be either primitive value, or a function which returns a value.

Example

The following example depicts how to configure the default property values in properties object.

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

//it specifies the start of an element's local DOM
<dom-module id="polymer-app">
   <template>
      <style>
         :host {
            color:#33ACC9;
         }
      </style>
      <h2>Hello...[[myval]]!</h2>	
   </template>

   <script>
      //cusom element extending the Polymer.Element class
      class PolymerApp extends Polymer.Element {
         static get is() { return 'polymer-app'; }
         static get properties() {
            return {
               myval: {
                  type: String,
                  //displaying this value on screen
                  value: 'Welcome to Tutorialspoint;!!!'
               },
               data: {
                  type: Object,
                  notify: true,
                  value: function() { return {}; }
               }
            }
         }
      }
      window.customElements.define(PolymerApp.is, PolymerApp);
   </script>
</dom-module>

Output

Run the application as shown in the previous example, and navigate to http://127.0.0.1:8000/. Following will be the output.

Read-only Properties

You can avoid unexpected changes on produced data by setting the readOnly flag to true, in the properties object. Element uses the setter of the convention _setProperty(value), in order to change the property value.

Example

Following example depicts the use of read-only properties in the properties object. Create an index.html file and add the following code in it

<!doctype html>
<html>
   <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 = "my-element.html">
   </head>
   
   <body>
      <my-element></my-element>
   </body>
</html>

Now, create another file called my-element.html and include the following code.

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

//it specifies the start of an element's local DOM
<dom-module id = "my-element">
   <template>
      <prop-element my-prop = "{{demoProp}}"></prop-element>
      <p>Present value: <span>{{demoProp}}</span></p>
   </template>

   <script>
      Polymer ({
         is: "my-element", properties: {
            demoProp: String
         }
      });
   </script>
</dom-module>

Next, create one more file called prop-element.html and add the following code.

//it specifies the start of an element's local DOM
<dom-module id="prop-element">
   <template>
      <button on-click="onClickFunc">Change value</button>
   </template>
   
   <script>
      Polymer ({
         is: "prop-element", properties: {
            myProp: {
               type: String,
               notify: true,
               readOnly: true,
               value: 'This is initial value...'
            }
         },
         onClickFunc: function(){
            this._setMyProp('This is new value after clicking the button...');
         }
      });
   </script>
</dom-module>

Output

Run the application as shown in the previous example, and navigate to http://127.0.0.1:8081/. Following will be the output.

After clicking the button, it will change the value as shown in the following screenshot.

Reflecting Properties to Attributes

HTML attribute can be synchronized with the property value by setting the reflectToAttribute to true on a property in the properties configuration object.

Attribute Serialization

The property value can be serialized to the attribute, while reflecting or binding a property to an attribute, and by default values can be serialized depending on the value's current type.

• String − There is no need of serialization.

• Date or Number − Use the toString to serialize the values.

• Boolean − Set the displayed non-valued attribute as either true or false.

• Array or Object − Use the JSON.stringify to serialize the value.