Polymer : “les mains dans le cambouis”, épisode 1

Nous parlerons de:

Les pré-requis et installation

Ecriture de 2 composants polymer

Communication entre composants polymer

Polymer est un nouveau framework javascript à base de composants web écrits par des développeurs de chez Google. Il s’appuie donc sur la norme des Web Components et parie sur les évolutions des navigateurs dans le futur (notamment sur l’implémentation du pattern Observer, comme le fait Angular). Polymer en attendant que ces évolutions “arrivent” fournit les polyfills nécessaires. Polymer est tout jeune et en plein développement (donc sujet à modifications fréquentes), mais il mérite que l’on s’y intéresse (ne serait-ce que parce qu’il vient de chez Google) car il est assez simple d’accès, aussi magique qu’Angular (mais probablement avec un temps d’apprentissage plus rapide). De plus Polymer est aussi porté côté Dart et pourrait devenir la partie “IHM” d’Angular (à vérifier).

Cet article ne va pas vous parler plus que ça du concept des “Web Components”. Je vous invite vivement à lire l’excellent article de @julienvey sur le sujet (en français en plus donc profitez-en) : http://www.infoq.com/fr/articles/polymer-nouveaux-standards-web.

Cet article va plutôt être “pratico-pratique” pour vous mettre le pied à l’étrier si vous avez envie de voir rapidement si Polymer est fait pour vous.

Tous les exemples présentés dans cet épisode et dans ceux à venir sont(seront) disponibles ici : https://github.com/k33g/polymer-les-mains-dans-le-cambouis.

Pour cet épisode vous trouverez tous les éléments ici : https://github.com/k33g/polymer-les-mains-dans-le-cambouis/tree/master/01-introduction

Pré-requis

1 serveur web

Tout d’abord, il vous faudra il vous faudra un serveur web. Pour ce 1er épisode, nul besoin de quelque chose de très compliqué. Si vous êtes sous OSX ou Linux, une simple commande python -m SimpleHTTPServer dans votre répertoire de travail fera l’affaire. Sinon vous pouvez aussi utiliser https://github.com/nodeapps/http-server, pour l’installer : npm install http-server -g et ensuite il suffit de lancer la commande http-server dans votre répertoire de travail.

Il ne vous reste plus qu’à créer un répertoire de travail que nous appellerons 01-introduction.

Néanmoins n’importe quel serveur http, serveur d’application convient, d’ailleurs dans un prochain épisode nous utiliserons Polymer avec Play 2 Scala.

Installation de Polymer

Pour installer Polymer, le plus simple pour le moment est d’utiliser Bower. Pour l’installer, rien de plus simple : npm install -g bower (vous aurez compris qu’il sera plus pratique d’avoir installé NodeJS sur votre poste, même si vous pouvez reproduire toutes ces manipulation à la main).

Pour “installer” Polymer :

cd 01-introduction
bower install polymer

Bower a crée un répertoire bower_components avec les librairies nécessaires dans 2 sous-répertoires platform et polymer.

Il ne vous reste plus qu’à créer une page index.html avec le code suivant :

<!DOCTYPE html>
<html>
<head>
  <title>01-introduction</title>
  <!-- Load Polymer -->
  <script src="bower_components/platform/platform.js"></script>
  <script src="bower_components/polymer/polymer.js"></script>

</head>
<body>

</body>
</html>

Nous sommes prêts.

Premier composant Polymer (Polymer element)

Un composant Polymer se compose généralement d’une portion de code html et d’une portion de code javascript sous cette forme :

<polymer-element name="mon-composant">
  <template>
    <!-- foo -->
  </template>
  <script>
    Polymer("mon-composant",{
      ready: function(){

      }
    });
  </script>
</polymer-element>

La méthode ready() est déclenchée à l’initialisation du composant. Maintenant, faisons le notre. Et ainsi vous disposez d’un nouveau tag html <mon-composant>.

Création du composant hello-john-doe

Dans votre répertoire de travail, créez un répertoire components puis dans ce sous-répertoire créez un fichier html hello-john-doe.html et saisissez le code suivant :

<polymer-element name="hello-john-doe">
  <template>
    <h1>Hello {{name}}</h1>
    <input value="{{name}}">
  </template>
  <script>
    Polymer("hello-john-doe",{
      ready: function(){
        this.name = "John Doe";
      }
    });
  </script>
</polymer-element>

Remarque : le nom d’un composant doit toujours être au minimum composé de 2 parties séparées par un -.

Déclaration et utilisation du composant

Dans votre page index.html, il faut déclare votre composant au niveau de <head></head> de cette façon : <link rel="import" href="components/hello-john-doe.html"> et ensuite il suffira d’utiliser <hello-john-doe></hello-john-doe> dans votre page html, comme ceci :

<!DOCTYPE html>
<html>
<head>
  <title>01-introduction</title>
  <!-- Load Polymer -->
  <script src="bower_components/platform/platform.js"></script>
  <script src="bower_components/polymer/polymer.js"></script>

  <!-- my components -->
  <link rel="import" href="components/hello-john-doe.html">
</head>
<body>
  <hello-john-doe></hello-john-doe>
</body>
</html>

Maintenant vous pouvez lancer votre serveur web (ie: http-server) et appeler votre page dans votre navigateur : http://localhost:numero_de_port :

Alt "001.png"

Vous pouvez voir que la valeur de name a bien été initialisée à John Doe avec la méthode render(). Et si vous saisissez un nouveau nom, le contenu du tag <h1></h1> change automatiquement :

Alt "002.png"

Tips : Accéder à un composant de l’extérieur :

Ce n’est pas forcément une bonne pratique, mais c’est bon à savoir. Une fois votre composant déclaré dans votre page html, c’est un composant du DOM à part entière, donc si vous souhaitez y accéder, vous pouvez procéder de la manière suivante pour obtenir une référence à celui-ci :

var helloJohn = document.querySelectorAll("hello-john-doe")[0]

Et ainsi, vous pouvez accéder à ses propriétés et les modifier, comme name dans notre exemple : helloJohn.name = "Actarus", et le changement dans le composant se fera automatiquement :

Alt "003.png"

Instances du composant hello-john-doe

Déclarez un 2 ème composant <hello-john-doe> dans votre page :

<body>
  <hello-john-doe></hello-john-doe>
  <hr>
  <hello-john-doe></hello-john-doe>
</body>

Ouvrez à nouveau la page avec votre navigateur, vous noterez que les 2 composants <hello-john-doe> fonctionnent de manière indépendante :

Alt "004.png"

`OnChange()` et autres petites choses …

A tout propriété d’un composant Polymer, vous pouvez associer une méthode qui sera déclenchée à chaque changement de la propriété, cette méthode prend comme nom, le nom de la propriété + Changed, donc dans le cas qui nous concerne ce sera nameChanged. Modifiez donc le code de notre composant de la manière suivante :

ajout d’un id au tag h1 : <h1 id="hello">Hello {{name}} </h1>
ajout d’une méthode nameChanged()

<polymer-element name="hello-john-doe">
  <template>
    <h1 id="hello">Hello {{name}}</h1>
    <input value="{{name}}">
  </template>
  <script>
    Polymer("hello-john-doe",{
      ready: function(){
        this.name = "John Doe";
      },
      nameChanged : function() {
        if(this.name != "John Doe") {
          this.$.hello.style.color = "red";
        } else {
          this.$.hello.style.color = "green";
        }
      }
    });
  </script>
</polymer-element>

Ouvrez à nouveau la page avec votre navigateur :

Alt "005.png"

Vous noterez l’utilisation de $ qui permet d’accéder automatiquement à l’élément d’id hello.

Ajoutons un “OnClick”

Proposons un peu plus d’action à notre composant en lui ajoutant un bouton, et une méthode associée au “click” sur le bouton :

dans la partie “html” (donc à l’intérieur de <template></template>), on ajoute : <button on-click=" {{clickMe}} ">Click Me!</button> où clickMe dans ` {{clickMe}} ` est le nom de la méthode appelé lorsque l’on clique sur le bouton
dans la partie “javascript”, on ajoute une méthode clickMe()

Nous obtiendrons le code suivant :

<polymer-element name="hello-john-doe">
  <template>
    <h1 id="hello">Hello {{name}}</h1>
    <input value="{{name}}">
    <button on-click="{{clickMe}}">Click Me!</button>
  </template>
  <script>
    Polymer("hello-john-doe",{
      ready: function(){
        this.name = "John Doe";
      },
      nameChanged : function() {
        if(this.name != "John Doe") {
          this.$.hello.style.color = "red";
        } else {
          this.$.hello.style.color = "green";
        }
      },
      clickMe : function() {
        this.$.hello.innerHTML="CLICKED";
      }
    });
  </script>
</polymer-element>

Ouvrez à nouveau la page avec votre navigateur :

Alt "006.png"

Deuxième composant Polymer : une liste

Nous allons créer une 2ème composant destiné à afficher une liste d’éléments, nous appellerons ce nouveau composant : <buddies-list></buddies-list>. Donc créez un nouveau fichier buddie-list.html dans le répertoire components avec le code suivant :

<polymer-element name="buddies-list">
  <template>
    <ul>
      <template repeat="{{buddies}}">
        <li>{{name}}</li>
      </template>
    </ul>
  </template>
  <script>
    Polymer("buddies-list",{
      ready: function(){
        this.buddies = [
          {name:"Bob Morane"},
          {name:"Doctor No"},
          {name:"Fox Mulder"},
          {name:"Lady Penelope"}
        ];
      }
    });
  </script>
</polymer-element>

Ensuite, déclarez votre composant dans index.html : <link rel="import" href="components/buddies-list.html"> et vous pouvez maintenant utiliser directement le nouveau tag : <buddies-list></buddies-list> :

<!DOCTYPE html>
<html>
<head>
  <title>01-introduction</title>
  <!-- Load Polymer -->
  <script src="bower_components/platform/platform.js"></script>
  <script src="bower_components/polymer/polymer.js"></script>

  <!-- my components -->
  <link rel="import" href="components/hello-john-doe.html">
  <link rel="import" href="components/buddies-list.html">
</head>
<body>
  <hello-john-doe></hello-john-doe>
  <hr>
  <buddies-list></buddies-list>
</body>
</html>

Ouvrez à nouveau la page avec votre navigateur :

Alt "007.png"

Comme avec le composant précédent, nous pouvons accéder “de l’extérieur” à notre composant pour par exemple lui ajouter des éléments :

document.querySelector("buddies-list").buddies.push({name : "Emma Peel"})

Alt "008.png"

Tips : jouons avec les attributs

Imaginez que vous déclarez votre nouveau composant de la manière suivante :

<buddies-list title="Buddies List"></buddies-list>

Le simple fait d’avoir ajouter un attribut title dans la définition du tag a créé un propriété title pour notre composant buddies-list, accessible aussi bien au niveau du code html (au sein de la balise <template></template>) qu’au niveau du code javascript. Modifiez le composant buddies-list de la façon suivante :

ajout de <h2> {{title}} </h2>dans la section template
lecture de la valeur de title dans la méthode ready() : console.log("Title is ", this.title);

<polymer-element name="buddies-list">
  <template>
    <h2>{{title}}</h2>
    <ul>
      <template repeat="{{buddies}}">
        <li>{{name}}</li>
      </template>
    </ul>
  </template>
  <script>
    Polymer("buddies-list",{
      ready: function(){
        console.log("Title is ", this.title);
        this.buddies = [
          {name:"Bob Morane"},
          {name:"Doctor No"},
          {name:"Fox Mulder"},
          {name:"Lady Penelope"}
        ];
      }
    });
  </script>
</polymer-element>

Ouvrez à nouveau la page avec votre navigateur :

Alt "009.png"

Nous avons donc maintenant un titre pour notre liste, que l’on peut paramétrer à partir d’un attribut dans le tag html correspondant au composant (<buddies-list title="Buddies List"></buddies-list>).

Les composants parlent au composants

Il serait intéressant maintenant que les éléments saisis dans le 1er composant puissent être ajoutés dans la liste du 2ème composant lorsque l’on clique sur le bouton (j’imagine que vous m’aviez vu venir de loin …). Il existe différentes méthodes pour communiquer entre composants de Polymer (Un peu de lecture par ici si vous le souhaitez : http://www.polymer-project.org/articles/communication.html), et ma préférée est celle qui fonctionne à base de signaux grâce au composant <polymer-signals>. Pour l’utiliser nous allons devoir installer les “polymer elements” qui sont des composant Polymer supplémentaires, dont notamment <polymer-signals>.

Pour se faire, nous utiliserons Bower une fois de plus :

bower install polymer-elements

Une fois les nouveaux éléments installés, nous pouvons donc utiliser <polymer-signals>. Nous aurons donc un composant qui sera “l’emetteur de signal”, dans notre cas le composant <hello-john-doe></hello-john-doe> qui enverra le signal newbuddy et le récepteur sera notre composant <buddies-list></buddies-list>.

Avant toute chose n’oublions pas de référencer <polymer-signals>:

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

Puis transformons <hello-john-doe></hello-john-doe> en emetteur.

L’emetteur

Modifiez le code de hello-john-doe.html de la façon suivante :

Nous ajoutons l’envoi d’un signal newbuddy à l’aide de asyncFire() dans la méthode clickMe() :

<polymer-element name="hello-john-doe">
  <template>
    <h1 id="hello">Hello {{name}}</h1>
    <input value="{{name}}">
    <button on-click="{{clickMe}}">Click Me!</button>
  </template>
  <script>
    Polymer("hello-john-doe",{
      ready: function(){
        this.name = "John Doe";
      },
      nameChanged : function() {
        if(this.name != "John Doe") {
          this.$.hello.style.color = "red";
        } else {
          this.$.hello.style.color = "green";
        }
      },
      clickMe : function() {
        this.$.hello.innerHTML="CLICKED";

        this.asyncFire(
          'polymer-signal',
          {
            name : "newbuddy",
            data : { name : this.name }
          }
        );
      }
    });
  </script>
</polymer-element>

Nous passons donc à asyncFire() le nom du signal (name : "newbuddy") et les données à envoyer (data : { name : this.name }).

Il nous faut maintenant un récepteur, donc transformons <buddies-list></buddies-list>.

Le récepteur

Ajoutons dans la partie html du composant la déclaration suivante <polymer-signals on-polymer-signal-newbuddy=" {{onNewBuddySignal}} "></polymer-signals> qui signifie que notre récepteur s’abonne au signal newbuddyet qu’il déclenchera la méthode onNewBuddySignal() s’il “entend” le signal. Important : il faut bien respecter la notation on-polymer-signal-newbuddy avec le nom du signal bien orthographié, en 1 seul mot et en minuscules. Pour le nom de la méthode onNewBuddySignal() par contre vous faites comme vous le sentez.
Ajoutons la méthode onNewBuddySignal() déclenchée par le signal

Nous aurons donc le code suivant pour buddies-list :

<polymer-element name="buddies-list">
  <template>
    <polymer-signals on-polymer-signal-newbuddy="{{onNewBuddySignal}}"></polymer-signals>
    <h2>{{title}}</h2>
    <ul>
      <template repeat="{{buddies}}">
        <li>{{name}}</li>
      </template>
    </ul>
  </template>
  <script>
    Polymer("buddies-list",{
      ready: function(){
        console.log("Title is ", this.title);
        this.buddies = [
          {name:"Bob Morane"},
          {name:"Doctor No"},
          {name:"Fox Mulder"},
          {name:"Lady Penelope"}
        ];
      },
      onNewBuddySignal : function(e, data, sender) {
        this.buddies.push(data)
        console.log("Sender : ", sender)
      }
    });
  </script>
</polymer-element>

Donc, à la réception du signal newbuddy nous ajouterons les données envoyées par l’émetteur : this.buddies.push(data) (au passage remarquez que vous pouvez récupérer une référence de l’émetteur via l’argument sender).

Il ne vous reste plus qu’à tester. Ouvrez à nouveau la page avec votre navigateur :

Alt "010.png"

Voilà!. Et de cette manière vous n’êtes pas obligés d’accéder aux composants “par l’extérieur” puisqu’ils peuvent communiquer par “signaux”.

Bien sûr, un composant peut être à la fois émetteur et récepteur, s’abonner à différents signaux, etc. …

C’est tout pour aujourd’hui. Cela vous laisse le temps de vous amuser un peu avec. Au prochain épisode, nous verrons comment “discuter” avec le serveur (nous parlerons d’ajax, json, REST, …) mais aussi nous vérifierons si Polymer reste compatible avec les autres frameworks javascript (la question étant, puis-je continuer à utiliser jQuery, Backbone, Underscore, …).

Bonne Lecture (et bon WE à tous) ;).

Polymer : “les mains dans le cambouis”, épisode 1

Pré-requis

1 serveur web

Installation de Polymer

Premier composant Polymer (Polymer element)

Création du composant hello-john-doe

Déclaration et utilisation du composant

Tips : Accéder à un composant de l’extérieur :

Instances du composant hello-john-doe

`OnChange()` et autres petites choses …

Ajoutons un “OnClick”

Deuxième composant Polymer : une liste

Tips : jouons avec les attributs

Les composants parlent au composants

L’emetteur

Le récepteur

Related posts

Last 6 posts

@k33g_org

Polymer : “les mains dans le cambouis”, épisode 1

Pré-requis

1 serveur web

Installation de Polymer

Premier composant Polymer (Polymer element)

Création du composant hello-john-doe

Déclaration et utilisation du composant

Tips : Accéder à un composant de l’extérieur :

Instances du composant hello-john-doe

OnChange() et autres petites choses …

Ajoutons un “OnClick”

Deuxième composant Polymer : une liste

Tips : jouons avec les attributs

Les composants parlent au composants

L’emetteur

Le récepteur

Related posts

Last 6 posts

@k33g_org

`OnChange()` et autres petites choses …