Exemples interactifs (EmbedLiveSample)

Comment fonctionnent les exemples interactifs ?

Les exemples interactifs regroupent les blocs de code, les fusionnent en HTML et affichent le HTML dans un <iframe>. Un exemple interactif se compose de deux parties :

• Un ou plusieurs blocs de code regroupés
• Un appel de macro qui affiche le résultat des blocs de code dans un <iframe>

Chaque bloc de code contenant le code pour le résultat possède un identifiant de langage — html, css ou js — qui précise s'il s'agit de code HTML, CSS ou JavaScript. Les identifiants de langage doivent être présents sur les blocs de code concernés, et un appel de macro (EmbedLiveSample) doit être présent dans la page pour afficher le résultat :

## Exemples

```html
<!-- HTML code -->
```

```css
/* CSS code */
```

{{EmbedLiveSample("Exemples")}}

Le système d'exemples interactifs permet de regrouper les blocs de code de différentes manières pour afficher efficacement le résultat. La section suivante décrit ces méthodes.

Regroupement des blocs de code

Les blocs de code peuvent être regroupés de deux manières :

1. En utilisant l'identifiant (ID) d'un titre ou d'un élément de bloc qui contient les blocs de code comme identifiant du groupe
2. En définissant une chaîne d'identification avec les blocs de code

Les blocs de code qui ne spécifient pas explicitement d'identifiant sont, par défaut, regroupés à l'aide de l'ID du titre ou de l'élément de bloc qui les contient. L'identifiant dans ce cas est l'ID d'un titre ou d'un élément de bloc (comme un <div>). Cela est illustré dans l'exemple ci-dessous, où les codes html et css du bloc « Mise en forme d'un paragraphe » sont utilisés pour générer le résultat de l'appel de macro EmbedLiveSample.

## Exemples

### Mise en forme d'un paragraphe

Dans cet exemple, nous utilisons du CSS pour mettre en forme les paragraphes ayant la classe `fancy`.

#### HTML

```html
<p>Je ne suis pas stylé.</p>

<p class="fancy">Mais moi oui&nbsp;!</p>
```

#### CSS

```css
p.fancy {
  color: red;
}
```

#### Résultat

{{EmbedLiveSample("Mise en forme d'un paragraphe")}}

Seul l'élément `<p>` avec `class="fancy"` sera affiché en rouge.

• Si l'ID appartient à un élément de bloc, le groupe inclut tous les blocs de code à l'intérieur de cet élément de bloc dont l'ID est utilisé.
• Si l'ID appartient à un titre, le groupe inclut tous les blocs de code qui suivent ce titre et précèdent le prochain titre du même niveau. Notez que les blocs de code sous les sous-titres du titre spécifié sont tous utilisés ; si ce n'est pas l'effet souhaité, utilisez un ID sur un élément de bloc ou une chaîne d'identification.

Pour regrouper des blocs de code à l'aide d'un identifiant, ajoutez une chaîne au format live-sample___{IDENTIFIANT} dans l'info string du bloc de code. L'identifiant doit être unique pour les blocs de code que vous souhaitez regrouper. Par exemple, live-sample___color-picker utilise color-picker comme identifiant pour le système d'exemples interactifs, et tous les blocs de code avec live-sample___color-picker dans leur info string sont combinés dans l'exemple interactif. L'exemple suivant regroupe un bloc CSS et un bloc JavaScript à l'aide de l'identifiant color-picker :

## Exemples

### Mise en forme d'un paragraphe

Dans cet exemple, nous utilisons du CSS pour mettre en forme les paragraphes ayant la classe `fancy`.

```html live-sample___mise-en-forme-dun-paragraphe
<p>Je ne suis pas stylé.</p>

<p class="fancy">Mais moi oui&nbsp;!</p>
```

```css live-sample___mise-en-forme-dun-paragraphe
p.fancy {
  color: red;
}
```

Seul l'élément `<p>` avec `class="fancy"` sera affiché en rouge&nbsp;:

{{EmbedLiveSample("mise-en-forme-dun-paragraphe")}}

```css live-sample___mise-en-forme-paragraphe
p.fancy {
  color: red;
}
```

Seul l'élément `<p>` avec `class="fancy"` sera affiché en rouge&nbsp;:

{{EmbedLiveSample("mise-en-forme-paragraphe")}}

La macro utilise une URL spéciale qui inclut l'ID pour récupérer le résultat d'un groupe de blocs de code donné. Vous ne devez jamais coder en dur cette URL dans le contenu : si vous devez créer un lien vers l'exemple, utilisez la macro LiveSampleLink.

Le cadre (ou la page) résultant est sandboxé, sécurisé, et peut techniquement faire tout ce qui fonctionne sur le web. Bien sûr, en pratique, le code doit être pertinent pour le contenu de la page ; tout contenu non pertinent pourra être supprimé par la communauté éditoriale de MDN.

Le système d'exemples interactifs propose de nombreuses options, que nous allons détailler point par point.

Macros d'exemples interactifs

Il existe deux macros que vous pouvez utiliser pour afficher des exemples interactifs :

• EmbedLiveSample ^(angl.) insère un exemple interactif dans une page
• LiveSampleLink ^(angl.) crée un lien qui ouvre l'exemple interactif dans une nouvelle page

Dans de nombreux cas, vous pouvez ajouter la macro EmbedLiveSample ou LiveSampleLink à des pages sans travail supplémentaire ! Tant que l'exemple peut être identifié par l'ID d'un titre ou se trouve dans un bloc avec un ID utilisable, l'ajout de la macro suffit.

Macro EmbedLiveSample

{{EmbedLiveSample(sample_id, width, height, screenshot_URL, page_slug, class_name, allow, sandbox)}}

sample_id

Obligatoire : il peut s'agir de la chaîne identifiant l'exemple ou de l'ID du titre ou du bloc englobant à partir duquel extraire le code. Pour vérifier si vous avez le bon ID de titre, regardez l'URL de la section dans la table des matières de la page ; vous pouvez aussi le vérifier en consultant le code source de la page.

width Obsolète

L'attribut width pour le <iframe>, définit en px. Obsolète car il n'a plus d'effet : les exemples interactifs occupent toujours toute la largeur de la zone de contenu.

height

L'attribut height du <iframe>, définit en px. Doit être au moins 60. Ce paramètre est optionnel ; une hauteur par défaut raisonnable sera utilisée si vous l'omettez.

screenshot_URL Obsolète

L'URL d'une capture d'écran montrant à quoi doit ressembler l'exemple interactif. Obsolète ; n'ajoutez des exemples interactifs que s'il existe un support navigateur raisonnable.

page_slug Obsolète

Le slug de la page contenant l'exemple ; ce paramètre est optionnel, et s'il n'est pas fourni, l'exemple est extrait de la même page que celle où la macro est utilisée. Obsolète ; n'incluez des exemples interactifs que si le code est sur la même page.

class_name Obsolète

Le nom de classe à appliquer au <iframe>. Obsolète ; il n'y a aucune raison d'utiliser un autre nom de classe.

allow

L'attribut allow pour le <iframe>. Ce paramètre est optionnel ; par défaut, aucune fonctionnalité n'est autorisée.

sandbox

Une chaîne contenant les attributs sandbox que l'exemple doit inclure. Les valeurs autorisées sont allow-modals, allow-forms et allow-popups. Plusieurs valeurs peuvent être fournies, comme "allow-modals allow-popups".

Macro LiveSampleLink

{{LiveSampleLink(block_ID, link_text)}}

block_ID

L'ID du titre ou du bloc englobant à partir duquel extraire le code. Pour être sûr d'avoir le bon ID, regardez l'URL de la section dans la table des matières de la page ; vous pouvez aussi le vérifier en consultant le code source de la page.

link_text

Une chaîne de caractères à utiliser comme texte du lien.

Utiliser le système d'exemples interactifs

Les sections ci-dessous décrivent quelques cas d'usage courants du système d'exemples interactifs.

Mise en forme des exemples interactifs

Si vous écrivez un exemple interactif dans la section « Exemples », fournissez un titre H3 descriptif (###) pour cet exemple. Idéalement, écrivez une courte description de l'exemple expliquant le scénario et ce que vous souhaitez démontrer. Ajoutez ensuite des sous-sections avec les titres H4 suivants (####), dans l'ordre indiqué :

• HTML
• CSS
• JavaScript
• Résultat

Écrivez les blocs de code dans les sous-sections correspondantes ci-dessus.

Dans la sous-section Résultat, ajoutez l'appel à la macro EmbedLiveSample. De préférence, ajoutez aussi du texte pour décrire le résultat.

Si vous n'utilisez pas un certain type de langage (par exemple, si vous n'utilisez pas JavaScript) ou si vous masquez le bloc de code, vous devez omettre le titre correspondant.

Masquer du code

Parfois, vous souhaitez simplement afficher le bloc de code statique pertinent pour l'exemple rendu dans la page. Cependant, vous avez toujours besoin des blocs de code HTML, CSS et JavaScript pour générer cet exemple.

Pour cela, vous pouvez masquer les blocs de code non pertinents en ajoutant l'info string hidden à l'identifiant de langage. Si vous faites cela, omettez les titres ### HTML/CSS/JavaScript pour les blocs de code masqués.

En reprenant l'exemple ci-dessus mais en masquant le code HTML, cela donnerait :

## Exemples

### Mise en forme d'un paragraphe

Dans cet exemple, nous utilisons du CSS pour mettre en forme les paragraphes ayant la classe `fancy`.

```html hidden
<p>Je ne suis pas stylé.</p>

<p class="fancy">Mais moi oui&nbsp;!</p>
```

#### CSS

```css
p.fancy {
  color: red;
}
```

#### Résultat

Seul l'élément `<p>` avec `class="fancy"` sera affiché en rouge.

{{EmbedLiveSample("Mise en forme d'un paragraphe")}}

Transformer des extraits en exemples interactifs

Un cas d'usage courant consiste à prendre des extraits de code déjà présents sur MDN et à les transformer en exemples interactifs. La première étape consiste à ajouter des extraits de code ou à s'assurer que les extraits existants sont prêts à être utilisés comme exemples interactifs, tant sur le fond que sur la forme. Les extraits de code, pris ensemble, doivent constituer un exemple complet et exécutable. Par exemple, si l'extrait existant ne montre que du CSS, il peut être nécessaire d'ajouter un extrait HTML pour que le CSS s'applique.

Chaque morceau de code doit être dans un bloc de code, avec un bloc séparé pour chaque langage, correctement marqué selon le langage. La plupart du temps, cela a déjà été fait, mais il est toujours utile de vérifier que chaque bloc de code est bien configuré avec la bonne coloration syntaxique. Cela se fait avec un identifiant de langage sur le bloc de code de type type-langage, où type-langage est le type de langage du bloc, par exemple html, css ou js.

Assurez-vous donc que les blocs de code HTML, CSS et/ou JavaScript sont bien configurés pour la coloration syntaxique du langage, et c'est tout bon.

Exemples

Cette section contient des exemples montrant comment le système d'exemples interactifs peut être utilisé, y compris les différentes façons de regrouper les blocs de code qui composent un exemple, et comment afficher la sortie de journalisation dans vos exemples.

Notez que les titres des blocs de code (« HTML », « CSS » ou « JavaScript ») sont utilisés par convention dans la plupart des exemples MDN, mais ne sont pas obligatoires pour la macro d'exemple interactif.

Regroupement des blocs de code par titre

HTML

Ce code HTML crée un paragraphe et des blocs pour nous aider à positionner et à styliser un message.

<p>Un exemple simple du système d'exemples interactifs en action.</p>
<div class="box">
  <div id="item">Bonjour le monde&nbsp;! Bienvenue sur MDN</div>
</div>

CSS

Le code CSS met en forme la boîte ainsi que le texte à l'intérieur.

.box {
  width: 200px;
  border-radius: 6px;
  padding: 20px;
  background-color: #ffaabb;
}

#item {
  font-weight: bold;
  text-align: center;
  font-family: sans-serif;
  font-size: 1.5em;
}

JavaScript

Dans l'exemple JavaScript, nous attachons un gestionnaire d'événement au texte « Bonjour le monde ! » qui le bascule lorsqu'il est cliqué.

const el = document.getElementById("item");
let toggleClick = false;
el.onclick = function () {
  this.textContent = toggleClick
    ? "Bonjour le monde ! Bienvenue sur MDN"
    : "Aïe, arrêtez de me cliquer dessus !";
  toggleClick = !toggleClick;
};

Résultat

Voici le résultat de l'exécution des blocs de code ci-dessus via {{EmbedLiveSample('grouping_code_blocks_by_heading')}} :

Voici un lien généré en appelant ces blocs de code via {{LiveSampleLink('grouping_code_blocks_by_heading', 'Lien de démonstration d\'exemple interactif')}} :

Regroupement des blocs de code par identifiant

Ce code HTML crée un paragraphe et des blocs pour nous aider à positionner et à styliser un message. La chaîne live-sample___hello-world a été ajoutée à l'identifiant de langage html pour ce bloc de code.

<p>Un exemple simple du système d'exemples interactifs en action.</p>
<div class="box">
  <div id="item">Bonjour le monde ! Bienvenue sur MDN</div>
</div>

Le code CSS met en forme la boîte ainsi que le texte à l'intérieur. La chaîne live-sample___hello-world a été ajoutée à l'identifiant de langage css pour ce bloc de code.

.box {
  width: 200px;
  border-radius: 6px;
  padding: 20px;
  background-color: #ffaabb;
}

#item {
  font-weight: bold;
  text-align: center;
  font-family: sans-serif;
  font-size: 1.5em;
}

Ce code JavaScript attache un gestionnaire d'événement au texte « Bonjour le monde ! » qui le bascule lorsqu'il est cliqué. La chaîne live-sample___hello-world a aussi été ajoutée à l'identifiant de langage js pour ce bloc de code.

const el = document.getElementById("item");
let toggleClick = false;
el.onclick = function () {
  this.textContent = toggleClick
    ? "Bonjour le monde ! Bienvenue sur MDN"
    : "Aïe, arrêtez de me cliquer dessus !";
  toggleClick = !toggleClick;
};

On obtient ce résultat en exécutant les blocs de code ci-dessus en utilisant l'identifiant de chaîne hello-world dans l'appel de macro {{EmbedLiveSample('hello-world')}} :

Affichage d'un <iframe> d'une certaine taille

Utilisez le paramètre height pour spécifier la taille de l'élément <iframe> qui contient le résultat de l'exemple interactif.

<p>Juste un texte simple ici.</p>

Résultat de {{EmbedLiveSample("iframe_size", "", "60")}} :

Résultat de {{EmbedLiveSample("iframe_size", "", "120")}} :

Autoriser des fonctionnalités

Le paramètre allow peut être utilisé pour spécifier les fonctionnalités autorisées dans l'élément <iframe> qui contient le résultat de l'exemple interactif. Les valeurs disponibles proviennent de la syntaxe de la politique d'autorisations pour les frames.

<div id="fullscreen-content">
  <button id="toggle-btn">Basculer en plein écran</button>
</div>

const toggleBtn = document.getElementById("toggle-btn");
const fullscreenContent = document.getElementById("fullscreen-content");

toggleBtn.addEventListener("click", () => {
  if (document.fullscreenElement) {
    document.exitFullscreen();
  } else {
    fullscreenContent.requestFullscreen();
  }
});

Résultat de {{EmbedLiveSample("allowing_features", "", "60", "", "", "", "fullscreen")}} :

Résultat de {{EmbedLiveSample("allowing_features", "", "60")}} :

Affichage d'un journal à entrée unique

Cet exemple montre comment implémenter un journal à entrée unique dans votre exemple interactif, où la valeur précédente est remplacée à chaque nouvelle entrée de journal.

Pour plus de clarté, cet exemple sépare le code de journalisation et le code qui l'utilise, et affiche d'abord le code de journalisation. En général, lors de l'implémentation de vos propres exemples, placez les éléments de journalisation sous les autres éléments d'interface utilisateur.

HTML

Créez un élément <pre> avec un id de "log" pour afficher la sortie du journal.

<pre id="log"></pre>

JavaScript

Définissez ensuite la fonction de journalisation log(). Elle prend le texte à journaliser en argument et l'utilise pour remplacer le journal existant.

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = text;
}

Notez que le contenu de l'élément de journal est défini en utilisant la propriété innerText, ce qui est plus sûr que d'utiliser innerHTML car le texte journalisé n'est pas interprété comme du HTML (ce qui pourrait potentiellement injecter du code malveillant).

CSS

Le CSS définit la hauteur de l'élément de journalisation.

#log {
  height: 20px;
}

Code de test du journal

Cet exemple est conçu pour montrer « comment journaliser », donc « ce qui est journalisé » n'a pas d'importance. C'est donc trivialement implémenté comme un bouton que l'utilisateur·ice peut cliquer pour incrémenter une valeur.

<button id="increment" type="button">Cliquez-moi plusieurs fois</button>

const incrementButton = document.querySelector("#increment");
let incrementValue = 0;
incrementButton.addEventListener("click", () => {
  incrementValue++;
  log(`Le bouton a été cliqué ${incrementValue} fois`);
});

Résultat

Cliquez sur le bouton pour ajouter une nouvelle entrée au journal.

Affichage d'un journal qui ajoute des éléments

Cet exemple montre comment implémenter une « console de journalisation » simple dans votre exemple interactif. La console ajoute une nouvelle ligne à la fin de la sortie à chaque fois qu'une entrée de journal est ajoutée, en faisant défiler le nouvel élément dans la vue.

Pour plus de clarté, cet exemple sépare le code de journalisation et le code qui l'utilise, et affiche d'abord le code de journalisation. En général, lors de l'implémentation de vos propres exemples, placez les éléments de journalisation sous les autres éléments d'interface utilisateur.

HTML

Créez un élément <pre> avec un id de "log" pour afficher la sortie du journal.

<pre id="log"></pre>

JavaScript

Définissez ensuite la fonction de journalisation log(). Elle prend le texte à journaliser en argument et l'ajoute au contenu de l'élément de journal comme une nouvelle ligne. La fonction définit aussi la propriété scrollTop de l'élément à la valeur de scrollHeight, ce qui force la nouvelle ligne à défiler dans la vue.

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

Comme dans l'exemple précédent, nous utilisons la propriété innerText pour définir le contenu, car cela est moins susceptible d'introduire du code malveillant que d'utiliser innerHTML.

CSS

Le CSS ajoute des barres de défilement si le contenu de l'élément déborde, définit la hauteur de l'élément de journalisation et ajoute une bordure. Notez que le JavaScript ci-dessus garantit que si le contenu déborde, l'ajout d'une nouvelle ligne de journal fera défiler le texte dans la vue.

#log {
  height: 100px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

Code de test du journal

Cet exemple est conçu pour montrer « comment journaliser », donc « ce qui est journalisé » n'a pas d'importance. C'est donc trivialement implémenté comme un bouton que l'utilisateur·ice peut cliquer pour incrémenter une valeur.

<button id="increment" type="button">Cliquez-moi plusieurs fois</button>

const incrementButton = document.querySelector("#increment");
let incrementValue = 0;
incrementButton.addEventListener("click", () => {
  incrementValue++;
  log(`Le bouton a été cliqué ${incrementValue} fois`);
});

Résultat

Cliquez sur le bouton pour ajouter une nouvelle entrée au journal.

Affichage d'un bouton de réinitialisation

Un bouton de réinitialisation peut être utile pour les exemples qui ne peuvent pas être restaurés à leur état initial sans recharger la page. Par exemple, l'exemple « paramètre priority » de Highlight.priority nécessite un bouton de réinitialisation, car une fois que vous avez défini l'une ou l'autre priorité, l'état initial n'est plus disponible.

Cet exemple montre comment ajouter un bouton de réinitialisation à l'exemple Affichage d'un journal qui ajoute des éléments ci-dessus. Notez que le JavaScript et le CSS pour le code de journalisation sont les mêmes que dans l'exemple précédent, donc ce code est masqué.

HTML

Le HTML de l'exemple inclut maintenant un bouton de réinitialisation.

<button id="increment" type="button">Cliquez-moi plusieurs fois</button>
<button id="reset" type="button">Réinitialiser</button>
<pre id="log"></pre>

JavaScript

Le code du bouton ajoute un gestionnaire d'événement click qui recharge simplement le cadre contenant l'exemple courant.

const reload = document.querySelector("#reset");

reload.addEventListener("click", () => {
  window.location.reload(true);
});

#log {
  height: 100px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

const incrementButton = document.querySelector("#increment");
let incrementValue = 0;
incrementButton.addEventListener("click", () => {
  incrementValue++;
  log(`Le bouton a été cliqué ${incrementValue} fois`);
});

Résultat

Cliquez sur le bouton « Cliquez-moi plusieurs fois » un certain nombre de fois. Réinitialisez l'exemple en appuyant sur le bouton « Réinitialiser ».

Conventions concernant les exemples interactifs

Ordre des blocs de code

Lors de l'ajout d'un exemple interactif, les blocs de code doivent être triés de sorte que le premier corresponde au langage principal de l'exemple (s'il y en a un). Par exemple, pour un exemple interactif dans la référence HTML, le premier bloc doit être HTML ; pour la référence CSS, il doit s'agir de CSS, etc.

Nom des titres

Lorsqu'il n'y a pas d'ambiguïté (par exemple, si l'exemple est dans une section « Exemples »), les titres doivent être simples, avec uniquement le nom du langage correspondant : HTML, CSS, JavaScript, SVG, etc. (voir ci-dessus). Des titres comme « Contenu HTML » ou « Contenu JavaScript » ne doivent pas être utilisés. Cependant, si un titre court rend le contenu peu clair, un titre plus explicite peut être utilisé.

Utilisation d'un bloc « Résultat »

Après les différents blocs de code, veuillez utiliser un dernier bloc « Résultat » avant d'utiliser la macro EmbedLiveSample (voir ci-dessus). Cela permet de clarifier la sémantique de l'exemple pour les lecteur·ice·s et les outils qui analysent la page (par exemple, lecteur d'écran, robot d'indexation).