Cet article explique comment utiliser les éléments<template> et<slot> pour créer un modèle (template) flexible qui peut ensuite être utilisé pour alimenter le Shadow DOM d'un composant web.

La vérité sur les modèles

Lorsqu'une structure de balises se répète sur une page web, il est judicieux d'utiliser un modèle plutôt que d'écrire cette même structure encore et encore. Il était déjà possible de le faire, mais l'élément HTML<template> (pris en charge par les navigateurs modernes) nous facilite la tâche. Cet élément et ce qu'il renferme n'est pas directement retranscrit dans le DOM, mais peut par contre toujours être manipulé avec JavaScript.

Voyons un exemple simple :

<template>  <p>My paragraph</p></template>

Ceci restera invisible sur la page tant qu'aucune référence n'y sera faite dans le code JavaScript puis ajouté au DOM, en utilisant par exemple :

let template = document.getElementById("my-paragraph");let templateContent = template.content;document.body.appendChild(templateContent);

Quoique trivial, cet exemple vous permet d'entrevoir l'interêt d'utiliser des modèles.

Accorder modèles et composants web

Les modèles sont utiles en eux-mêmes, mais ils fonctionnent encore mieux avec des composants web. Créons un composant web qui utilise notre modèle comme contenu de son Shadow DOM. Nous l'appellerons<my-paragraph> :

customElements.define(  "my-paragraph",  class extends HTMLElement {    constructor() {      super();      let template = document.getElementById("my-paragraph");      let templateContent = template.content;      const shadowRoot = this.attachShadow({ mode: "open" }).appendChild(        templateContent.cloneNode(true),      );    }  },);

Le point important à noter est que l'on ajoute un clone du contenu du modèle à la racine du DOM, créé à l'aide de la méthodeNode.cloneNode().

Et parce que nous ajoutons son contenu à un Shadow DOM, on peut inclure des informations de mise en forme à l'intérieur de l'élément<template> dans un élément<style>, qui est ensuite encapsulé à l'intérieur de l'élément personnalisé. Cette procédure n'aurait pas fonctionné si on avait ajouté le contenu à un DOM standard.

Par exemple :

<template>  <style>    p {      color: white;      background-color: #666;      padding: 5px;    }  </style>  <p>My paragraph</p></template>

On peut maintenant utiliser le modèle dans le document HTML:

<my-paragraph></my-paragraph>

Plus de flexibilité avec les slots

Jusque-là, nous avons vu une première utilisation de l'élément<template>. Cette implémentation n'est pas très flexible ; elle ne permet d'afficher que du texte, c'est-à-dire qu'il est aussi utile qu'un paragraphe classique ! Il est possible d'insérer du texte dans chaque instance d'élément de façon déclarative grâce à<slot>. Cette fonction est moins bien prise en charge que<template>, disponible sur Chrome 53, Opera 40, Safari 10, Firefox 59 et Edge 79.

Les emplacements (slots) sont identifiés par leur attributname, et permettent de définir des emplacements dans le modèle qui peuvent être alimentés avec n'importe quelle structure HTML.

Donc, si on souhaite ajouter un emplacement dans le précédent exemple, on peut modifier l'élément de cette façon :

<p><slot name="my-text">Texte par défaut</slot></p>

Si le contenu de l'emplacement n'est pas défini quand l'élément est inclus dans la page, ou si les emplacements ne sont pas pris en charge par le navigateur,<my-paragraph> contiendra simplement le texte statique précisé dans le modèle.

Pour définir le contenu de l'emplacement, on insère une structure HTML dans<my-paragraph> avec un attributslot dont la valeur est égale au nom de l'emplacement que l'on veut alimenter. Comme précédemment, on peut utiliser n'importe quelle structure HTML, par exemple :

<my-paragraph>  <span slot="my-text">Voici un autre texte&nbsp;!</span></my-paragraph>

ou

<my-paragraph>  <ul slot="my-text">    <li>Voici un autre texte&nbsp;!</li>    <li>dans une liste!</li>  </ul></my-paragraph>

Et c'est tout pour ce premier exemple. Si vous souhaitez manipuler les emplacements, vous pouvezvoir la page sur GitHub (voir aussile résultat).

Un exemple plus complexe

Pour finir, voyons un exemple un peu moins trivial.

L'ensemble de fragments de code qui suit illustre comment utiliser<slot> avec<template> et un peu de JavaScript afin de :

• Créer un élément<element-details> avec desemplacements nommés àla racine virtuelle (ShadowRoot)
• Concevoir l'élément<element-details> afin que, lorsqu'il est utilisé dans les documents, il soit rendu en composant le contenu de l'élément avec le contenu dela racine virtuelle. Autrement dit, les parties du contenu de l'élément seront utilisées afin de remplirles emplacements nommés dans saracine virtuelle

Il est techniquement possible d'utiliser un élément<slot> sans élément<template> (par exemple au sein d'un<div> classique) tout en tirant parti des fonctionnalités d'emplacement fournies par<slot> pour le contenu du Shadow DOM. On peut ainsi éviter d'avoir à d'abord accéder à la propriétécontent du modèle (et de la cloner). Toutefois, il est souvent plus pratique d'ajouter des emplacements au sein d'un élément<template>, car il est peu probable de définir un composant à partir d'un élément déjà rendu.

De plus, même si l'élément n'est pas déjà rendu, le rôle de conteneur porté par le modèle sera sémantiquement plus clair en utilisant<template>. De plus,<template> peut avoir des éléments qui lui sont directement rattachés comme<td>. Ce même élément disparaîtrait s'il était ajouté à un élément<div>.

Créer un modèle avec des emplacements

Tout d'abord, on utilise l'élément<slot> au sein d'un élément<template> afin de créer notre nouveaufragment de document "element-details-template" qui contient quelquesemplacements nommés :

<template>  <style>    details {      font-family: "Open Sans Light", Helvetica, Arial;    }    .name {      font-weight: bold;      color: #217ac0;      font-size: 120%;    }    h4 {      margin: 10px 0 -8px 0;    }    h4 span {      background: #217ac0;      padding: 2px 6px 2px 6px;    }    h4 span {      border: 1px solid #cee9f9;      border-radius: 4px;    }    h4 span {      color: white;    }    .attributes {      margin-left: 22px;      font-size: 90%;    }    .attributes p {      margin-left: 16px;      font-style: italic;    }  </style>  <details>    <summary>      <span>        <code          >&lt;<slot name="element-name">BESOIN D'UN NOM</slot>&gt;</code        >        <i          ><slot name="description">BESOIN D'UNE DESCRIPTION</slot></i        >      </span>    </summary>    <div>      <h4><span>Attributs</span></h4>      <slot name="attributes"><p>Aucun</p></slot>    </div>  </details>  <hr /></template>

Voyons les caractéristiques de cet élément<template> :

• Ce<template> contient un élément<style> avec un ensemble de règles CSS dont la portée est celle du fragment de document créé par l'élément<template>.

• Ce<template> utilise un élément<slot> et l'attributname correspondant afin d'avoir troisemplacements nommés :

  • <slot name="element-name">
  • <slot name="description">
  • <slot name="attributes">

• L'élément<template> intègre lesemplacements nommés slots dans un élément<details>.

Créer un nouvel élément element-details avec le modèle

Ensuite, voyons comment créer un nouvel élément personnalisé, intitulé<element-details>, et comment utiliserElement.attachShadow pour lui rattacher, commeracine virtuelle, le fragment de document créé avec l'élément<template> ci-dessus. Pour cela, on utilisera la même méthode qu'avec notre exemple plus simple.

customElements.define(  "element-details",  class extends HTMLElement {    constructor() {      super();      const template = document.getElementById(        "element-details-template",      ).content;      const shadowRoot = this.attachShadow({ mode: "open" }).appendChild(        template.cloneNode(true),      );    }  },);

Utiliser l'élément element-details avec les emplacements nommés

Prenons maintenant un élément<element-details> et utilisons le dans notre document :

<element-details>  <span slot="element-name">slot</span>  <span slot="description"    >Un emplacement dans un composant web que les utilisateurs pourront remplir    avec leur propre contenu pour composer plusieurs arbres DOM ensemble.</span  >  <dl slot="attributes">    <dt>name</dt>    <dd>Le nom de l'emplacement.</dd>  </dl></element-details><element-details>  <span slot="element-name">template</span>  <span slot="description"    >Un mécanisme pour stocker du contenu côté client qui n'est pas affiché    lorsque la page est chargée mais lors de l'exécution avec du code    JavaScript.</span  ></element-details>

En voyant ce fragment, notons quelques points :

• Ce fragment contient deux exemplaires<element-details> qui utilisent tous les deux l'attributslot afin de référencerles emplacements nommés"element-name" et"description" qui sont inscrits dansla racine virtuelle<element-details>.
• Seul le premier élément<element-details> fait référence àl'emplacement nommé"attributes". Le deuxième élément<element-details> n'y fait pas référence.
• Le premier élément<element-details> fait référence àl'emplacement nommé"attributes" en utilisant un élément<dl> contenant comme enfants un élément<dt> et un élément<dd>.

Mettre le tout en forme

Pour finir, ajoutons un peu de CSS pour les éléments<dl>,<dt> et<dd> de notre document :

dl {  margin-left: 6px;}dt {  font-weight: bold;  color: #217ac0;  font-size: 110%;}dt {  font-family: Consolas, "Liberation Mono", Courier;}dd {  margin-left: 16px;}

body {  margin-top: 47px;}

Résultat

Assemblons l'ensemble des fragments pour voir le résultat final.

Quelques notes à propos du résultat affiché :

• Bien que les exemplaires des éléments<element-details> du document n'utilisent pas directement d'élément<details>, ils sont rendus comme celui-ci, car<details>la racine virtuelle les peuple avec ceci.
• Au sein de l'élément<details> affiché, le contenu des éléments<element-details> remplitles emplacements nommés dela racine virtuelle. Autrement dit, l'arbre du DOM pour les éléments<element-details> est composé avec le contenude la racine virtuelle.
• Pour les deux éléments<element-details>, un titreAttributs est automatiquement ajouté à partir dela racine virtuelle avant la position de l'emplacement nommé"attributes".
• Étant donné que le premier élément<element-details> possède un élément<dl> qui référence explicitementl'emplacement nommé"attributes" depuissa racine virtuelle, les contenus de<dl> remplacent l'emplacement nommé"attributes" dela racine virtuelle.
• Comme le second élément<element-details> ne fait pas explicitement référence à l'emplacement nommé"attributes" depuissa racine virtuelle, le contenu de cetemplacement nommé est rempli avec le contenu par défaut fourni parla racine virtuelle.

Exemple complet

<!doctype html><html>  <head>    <title>slot example</title>    <style>      dl {        margin-left: 6px;      }      dt {        font-weight: bold;        color: #217ac0;        font-size: 110%;      }      dt {        font-family: Consolas, "Liberation Mono", Courier;      }      dd {        margin-left: 16px;      }    </style>  </head>  <body>    <template>      <style>        details {          font-family: "Open Sans Light", Helvetica, Arial;        }        .name {          font-weight: bold;          color: #217ac0;          font-size: 120%;        }        h4 {          margin: 10px 0 -8px 0;        }        h4 span {          background: #217ac0;          padding: 2px 6px 2px 6px;        }        h4 span {          border: 1px solid #cee9f9;          border-radius: 4px;        }        h4 span {          color: white;        }        .attributes {          margin-left: 22px;          font-size: 90%;        }        .attributes p {          margin-left: 16px;          font-style: italic;        }      </style>      <details>        <summary>          <span>            <code              >&lt;<slot name="element-name">BESOIN D'UN NOM</slot>&gt;</code            >            <i              ><slot name="description">BESOIN D'UNE DESCRIPTION</slot></i            >          </span>        </summary>        <div>          <h4><span>Attributs</span></h4>          <slot name="attributes"><p>Aucun</p></slot>        </div>      </details>      <hr />    </template>    <element-details>      <span slot="element-name">slot</span>      <span slot="description"        >Un emplacement dans un composant web que les utilisateurs pourront        remplir avec leur propre contenu pour composer plusieurs arbres DOM        ensemble.</span      >      <dl slot="attributes">        <dt>name</dt>        <dd>Le nom de l'emplacement.</dd>      </dl>    </element-details>    <element-details>      <span slot="element-name">template</span>      <span slot="description"        >Un mécanisme pour stocker du contenu côté client qui n'est pas affiché        lorsque la page est chargée mais lors de l'exécution avec du code        JavaScript.</span      >    </element-details>    <script>      customElements.define(        "element-details",        class extends HTMLElement {          constructor() {            super();            const template = document.getElementById(              "element-details-template",            ).content;            const shadowRoot = this.attachShadow({ mode: "open" }).appendChild(              template.cloneNode(true),            );          }        },      );    </script>  </body></html>