Les éléments personnalisés

HTML nous offre un excellent outil pour structurer un document, mais son vocabulaire est limité aux éléments définis dans les spécifications HTML.

À quoi ressemblerait GMail si son balisage n'était pas horrible ? Comment pourrait-on le rendre plus beau :

<hangout-module>
  <hangout-chat from="Paul, Addy">
    <hangout-discussion>
      <hangout-message from="Paul" profile="profile.png"
          profile="118075919496626375791" datetime="2013-07-17T12:02">
        <p>Feelin' this Web Components thing.</p>
        <p>Heard of it?</p>
      </hangout-message>
    </hangout-discussion>
  </hangout-chat>
  <hangout-chat>...</hangout-chat>
</hangout-module>

C'est beaucoup plus élégant ! Surtout, cette application a du sens. Elle est éloquente, facile à comprendre et surtout, maintenable. N'importe quel utilisateur futur saura exactement ce qu'elle fait juste en regardant son ossature.

Les éléments personnalisés sont créés avec document.register() :

var XFoo = document.register('x-foo');
document.body.appendChild(new XFoo());

Le premier paramètre de document.register() correspond au nom de la balise créée. Ce nom doit obligatoirement contenir un tiret (-). Par exemple, <x-tags>, <my-element> et <my-awesome-app> sont des noms valides, alors que <tabs> et <foo_bar> ne le sont pas. Cette restriction permet au parseur de différencier les éléments personnalisés des éléments natifs, mais permet surtout d'assurer une compatibilité ascendante lorsque de nouvelles balises sont ajoutées au HTML.

Le second paramètre (optionnel) est un objet décrivant le prototype de l'élément. C'est ici qu'il faudra définir les fonctionnalités (par exemple ses propriétés et méthodes publiques) de vos éléments. Nous y reviendronsAjouter des propriétés et des méthodes JavaScript.

Par défaut, les nouveaux éléments héritent de l'objet HTMLElement. Ainsi, l'exemple précédent est équivalent à :

var XFoo = document.register('x-foo', {
  prototype: Object.create(HTMLElement.prototype)
});

Un appel à document.register('x-foo') permet au navigateur de reconnaître le nouvel élément et retourne un constructeur que vous pouvez utiliser pour créer des instances de <x-foo>. Vous pouvez également utiliser d'autres techniques pour instancier des élémentsInstancier les éléments si vous ne souhaitez pas utiliser le constructeur.

Imaginons que vous ne soyez pas particulièrement satisfait de la balise <button>. En fait, vous aimeriez l'enrichir pour la faire devenir un « mega bouton ». Pour étendre l'élément <button>, il suffit de créer un élément personnalisé qui hérite du prototype de HTMLButtonElement :

var MegaButton = document.register('mega-button', {
  prototype: Object.create(HTMLButtonElement.prototype)
});

Cette catégorie d'éléments personnalisés s'appelle « élément personnalisé par extension de type » (type extension custom elements). Ils héritent d'une version spécifique de HTMLElement comme si on disait « l'élément X est un Y ».

Exemple :

<button is="mega-button">

Ne vous êtes-vous jamais demandé pourquoi les parseurs HTML des navigateurs ne sont pas perturbés lorsqu'ils rencontrent des éléments non standards ? Par exemple, vous pouvez mettre une balise <randomtag> dans votre code et le navigateur ne s'en portera pas plus mal. En fait, la spécification HTML prévoit ce cas :

The HTMLUnknownElement interface must be used for HTML elements that are not defined by this specification.

Ce qui peut se traduire par :

L'interface HTMLUnknownElement doit être utilisée pour les éléments HTML non définis par cette spécification.

Désolé <randomtag>, tu es inconnu des standards et hériteras de HTMLUnknownElement.

Mais cela ne s'applique pas aux éléments personnalisés. Les éléments personnalisés ayant un nom valide héritent de HTMLElement. Vous pouvez vérifier cela en activant votre console JavaScript et en exécutant le code ci-après, les exemples renvoient true :

// "tabs" n'est pas un nom d'élément personnalisé valide
document.createElement('tabs').__proto__ === HTMLUnknownElement.prototype

// "x-tabs" est un nom d'élément personnalisé valide
document.createElement('x-tabs').__proto__ == HTMLElement.prototype

II-C-1. Éléments non résolus▲

Déclarez-les :

<x-foo></x-foo><x-foo></x-foo>

Créez un objet DOM en JavaScript :

var xFoo = document.createElement('x-foo');
xFoo.addEventListener('click', function(e) {
  alert('Thanks!');
});

Utilisez l'opérateur new :

var xFoo = new XFoo();
document.body.appendChild(xFoo);

Instancier des extensions d'éléments existants se fait de façon similaire.

Déclarez-les :

<!-- <button> "est un" mega bouton -->
<button is="mega-button">

Créez un objet DOM en JavaScript :

var megaButton = document.createElement('button', 'mega-button');
// megaButton instanceof MegaButton === true

Comme vous pouvez le voir, il existe maintenant une version enrichie de document.createElement() qui prend en second paramètre la valeur de l'attribut is="".

Utilisez l'opérateur new :

var megaButton = new MegaButton();
document.body.appendChild(megaButton);

Jusqu'à présent, nous n'avons utilisé que document.register() pour ajouter de nouveaux éléments, mais cela ne va pas très loin… alors ajoutons des propriétés et des méthodes.

Les éléments permettent de définir des méthodes spéciales liées aux moments importants de leur mise en œuvre. Ces méthodes sont appelées de façon avisée « fonctions de rappel au cours du cycle de vie » (lifecycle callbacks). Chacune a un nom et une utilité spécifique.

Dans l'exemple suivant, nous valorisons les fonctions de rappel createdCallback() et enteredDocumentCallback() sur la balise <x-foo> :

var proto = Object.create(HTMLElement.prototype);

proto.createdCallback = function() {...};
proto.enteredDocumentCallback = function() {...};

var XFoo = document.register('x-foo', {prototype: proto});

Chacune de ces fonctions de rappel est optionnelle, ne les définissez que si cela est utile. Par exemple, imaginons un élément particulièrement complexe qui ouvre une connexion à IndexedDB dans createdCallback(). Dans ce cas, n'oubliez pas, s'il doit être retiré du DOM, de faire le ménage nécessaire dans leftDocumentCallback().

Un autre cas classique d'utilisation est de définir des gestionnaires d'événements par défaut :

proto.createdCallback = function() {
  this.addEventListener('click', function(e) {
    alert('Thanks!');
  });
};

En soi, le DOM fantôme (Shadow DOM) est un outil puissant pour encapsuler du contenu. Utilisé en conjonction avec les éléments personnalisés et la magie prend forme !

Le DOM fantôme permet aux éléments personnalisés :

• de cacher leurs entrailles, permettant ainsi de masquer le cambouis de l'implémentation aux utilisateurs ;
• d'encapsuler les styles… et gratuitement.

Créer un élément dans le DOM fantôme lui permet de s'afficher selon un balisage de base. La différence se faisant dans createdCallback() :

var XFooProto = Object.create(HTMLElement.prototype);

XFooProto.createdCallback = function() {
  // 1. Attacher une racine fantôme à l'élément.
  var shadow = this.createShadowRoot();

  // 2. Le remplir avec le bon balisage.
  shadow.innerHTML = "<b>Je suis dans le DOM fantôme de l'élément !</b>";
};

var XFoo = document.register('x-foo-shadowdom', {prototype: XFooProto});

Au lieu d'affecter le .innerHTML de l'élément, j'ai créé une racine fantôme (Shadow Root) pour <x-foo-shadowdom> et y ai ajouté le balisage. En activant l'option « Show Shadow DOM » dans les outils de développeur de Chrome (NdT : seul navigateur supportant cette API au moment de l'écriture de l'article), vous verrez un #document-fragment que vous pouvez déplier :

&#9660;<x-foo-shadowdom>
   &#9660;#document-fragment
     <b>Je suis dans le DOM fantôme de l'élément !</b>
 </x-foo-shadowdom>

C'est cela la racine fantôme !

Les gabarits HTML (HTML Templates) sont une autre nouvelle API qui convient parfaitement au monde des éléments personnalisés.

Pour ceux qui ne seraient pas familiers avec la balise <template>, celle-ci permet de déclarer des fragments de DOM qui sont parsés, inactifs au chargement de la page et destinés à être instanciés ultérieurement. Elles sont donc l'emplacement idéal pour déclarer la structure d'un élément personnalisé.

Dans cet exemple, nous enregistrons un élément créé à partir d'un <template> dans le DOM fantôme :

<template id="sdtemplate">
  <style>
    p { color: orange; }
  </style>
  <p>Je suis dans le DOM fantôme. Mon balisage provient d'un <template>.</p>
</template>

<script>
var proto = Object.create(HTMLElement.prototype, {
  createdCallback: {
    value: function() {
      var t = document.querySelector('#sdtemplate');
      this.createShadowRoot().appendChild(t.content.cloneNode(true));
    }
  }
});
document.register('x-foo-from-template', {prototype: proto});
</script>

Cette portion de code contient beaucoup de choses. Essayons de détailler tout ce qu'il s'y passe.

• Nous enregistrons un nouvel élément HTML, <x-foo-from-template>.
• Le contenu DOM de cet élément est créé à partir d'un <template>.
• La partie interne est masquée à l'aide du DOM fantôme.
• Le DOM fantôme encapsule le style de l'élément (la règle CSS p {color: orange;} ne rend pas tous les paragraphes orange).

C'est beau !

Le terrier du lapin devient beaucoup plus profond lorsque le DOM fantôme entre en jeu et les éléments personnalisés qui l'utilisentEncapsuler le contenu dans le DOM fantôme profitent de ses larges avantages.

Le DOM fantôme est parfaitement cloisonné, y compris ses déclarations de style. Les styles CSS définis à partir de la racine fantôme ne peuvent pas s'appliquer sur le reste de la page, de même, les styles de la page n'ont pas d'effet sur le DOM fantôme. Dans le cas des éléments personnalisés, l'élément lui-même est la racine. L'encapsulation des styles permet aussi à un élément personnalisé de définir ses propres styles par défaut.

La mise en forme du DOM fantôme est un immense sujet ! Si vous souhaitez en savoir plus à ce propos, je vous recommande certains de mes articles :

• A Guide to Styling Elements dans la documentation de Polymer ;
• Shadow DOM 201 : CSS & Styling sur HTML5 Rocks.

Pour limiter le FOUCFlash of unstyled content, la spécification des éléments personnalisés introduit le nouveau pseudoélément :unresolved. Vous pouvez l'utiliser pour cibler les éléments non résolusÉléments non résolus jusqu'à ce que le navigateur n'invoque votre fonction createdCallback() (voir Les fonctions de rappel au cours du cycle de vieLes fonctions de rappel au cours du cycle de vie). Une fois cette fonction appelée, l'élément n'est plus « non résolu », le processus de mise à jour est achevé et l'élément est transformé conformément à sa déclaration.

Exemple : faire apparaître progressivement les balises <x-foo>

x-foo {
    opacity: 1;
    transition: opacity 300ms;
}
x-foo:unresolved {
    opacity: 0;
}

Gardez bien à l'esprit que le pseudoélément :unresolved s'applique uniquement aux éléments non résolusÉléments non résolus, pas aux éléments héritant de l'interface HTMLUnknownElement (voir Comment sont gérés les élémentsComment sont gérés les éléments).

<style>
  /* appliquer une bordure pointillée aux éléments non résolus */
  :unresolved {
    border: 1px dashed red;
    display: inline-block;
  }
  /* les éléments x-panel non résolus sont en rouge */
  x-panel:unresolved {
    color: red;
  }
  /* les éléments x-panel enregistrés sont en vert */
  x-panel {
    color: green;
    display: block;
    padding: 5px;
  }
</style>

<panel>
  Je suis en noir, car le pseudoélément :unresolved ne s'applique pas à "panel".
  Ce n'est pas un nom valide pour un élément personnalisé.
</panel>

<x-panel>Je suis en rouge, car x-panel:unresolved s'applique à moi.</x-panel>

Pour en savoir plus sur :unresolved, voir A Guide to styling elements sur Polymer.

Détecter la disponibilité de l'API revient à vérifier l'existence de document.register() :

function supportsCustomElements() {
  return 'register' in document;
}

if (supportsCustomElements()) {
  // C'est bon, on peut y aller !
} else {
  // Utiliser une solution de remplacement.
}

document.register() a été implémenté dans Chrome 27 et Firefox 23 en activant une option. Cependant, la spécification a quelque peu évolué entre temps et Chrome 31 est le premier à assurer un réel support de la version actuelle de la spécification.

En attendant un support plus significatif, vous pouvez utiliser ces solutions de remplacement :

• Polymer, de Google propose une solution ;
• les x-tags de Mozilla.

Ceux qui ont suivi le travail de standardisation savent qu'il a existé la balise <element>. C'était vraiment la panacée. Vous pouviez les utiliser pour enregistrer les nouveaux éléments de façon déclarative :

<element name="my-element">
  ...
</element>

Malheureusement, il y avait trop de problèmes de performances au niveau du processus de mise à jourComment sont gérés les éléments, des effets de bord et des scénarios catastrophe qui ont empêché cela de fonctionner correctement. Ainsi, <element> a dû être abandonné. En août 2013, Dimitri Glazkov annonça sa suppression dans un message du public-webapps, en tout cas pour le moment…

Il est toutefois intéressant de noter que Polymer implémente une approche déclarative pour l'enregistrement d'éléments avec <polymer-element>. Comment cela est-il mis en place ? En utilisant document.register('polymer-element') et les techniques présentées dans Créer des éléments à partir d'un gabaritCréer des éléments à partir d'un gabarit