Overlay

Composant permettant d’afficher un contenu au‑dessus de la page web courante, limitant l’interaction sur cette page à ce contenu.

Démonstration

Description

Le script d'overlay peut être instantié de deux façons différentes :

Implémentation

CSS

Aucune classe CSS n'est requise pour faire fonctionner le script. Il est recommandé de s'assurer que les overlays ayant l'attribut aria-hidden à true soient invisibles :

.overlay-wrapper[aria-hidden="true"] {
  display: none;
}
  • Élément à encapsuler
  • Élément à afficher

En passant le HTML à encapsuler, le script se chargera de créer l'élément overlay englobant le contenu HTML et de gérer le focus et les actions au clavier.

HTML

<!-- exemple de contenu d'overlay -->
<section class="modal modal">
  <header class="modal-header">
    <button class="button-close">
      <span>Fermer</span>
    </button>
    <h2 class="modal-title">Fenêtre modale</h2>
  </header>
  <div class="modal-content">
    <p>Les popins sont des fenêtres qui apparaissent directement à l'intérieur de la fenêtre courante du navigateur, au-dessus de la page web qui les appelle.</p>
    <p>Il s'agit de fenêtres modales, c'est-à-dire de fenêtres qui prennent le <strong>contrôle de la page courante</strong> tant qu'elles sont affichées à l'écran.</p>
  </div>
</section>

JavaScript

// Il est possible de créer un overlay en lui passant le contenu souhaité…
var overlay = new Overlay( {
  content: document.querySelector( '.overlay' )
});

// … ou une string HTML
var overlay = new Overlay( {
  content: '<div><p>Bonjour</p></div>'
});

// Ouvre l'overlay
overlay.show();

// Ferme l'overlay
overlay.close();
Paramètre obligatoire
Nom Type Description
content HTMLElement ou String Contenu à encapsuler dans un overlay.
Paramètres optionnels
Nom Type Description
className String Classes HTML à ajouter à l'overlay. Ces classes sont séparées par des espaces.
closeOnCancel Boolean Booléen permettant d'autoriser ou non la fermeture de l'overlay via la touche « Echap » ou en cliquant en dehors de l'overlay. Est à « true » par défaut.
closeSelector String Sélecteur CSS permettant de cibler des boutons qui doivent déclencher la fermeture lorsqu'ils sont activés.
modal Boolean Permet de définir l'overlay comme non modal lorsque sa valeur est à false. Par défault les éléments en dehors de l'overlay sont inaccessibles (valeur à true).
opener HTMLElement Élément HTML qui va recevoir le focus une fois l'overlay fermé. Utilise l'élément ayant le focus lors de l'ouverture de l'overlay par défaut.
tagName String Nom de la balise à utiliser sur l'élément encapsulant le contenu de l'overlay. Utilise div par défaut.
role String Role ARIA à attribuer à l'overlay. Peut être dialog ou alertdialog.
titleSelector String Sélecteur CSS permettant de lier l'overlay ayant un role à son titre. Cherche un élément ayant l'attribut [data-label] par défaut.
label String Obligatoire lorsque l'overlay n'a pas de titre et a un role. Permet de définir le titre de l'overlay.

En passant le HTML complet de l'overlay, le script s'occupe de gérer le focus et les actions au clavier. Le script lit les attributs HTML de cet élément pour décider du comportement à appliquer. Suivant l'attribut role, l'overlay peut, ou non, se fermer via la touche « Echap » ou un clic extérieur.

HTML

<!-- exemple d'overlay complet -->
<div role="alertdialog" class="modal" aria-hidden="true" aria-labelledby="modalTitle" aria-describedby="modalDesc">
  <section class="modal">
    <header class="modal-header">
      <button class="button-close">
        <span>Fermer</span>
      </button>
      <h2 class="modal-title" id="modalTitle">Attention</h2>
    </header>
    <div class="modal-content">
      <p id="modalDesc">Pour continuer, vous devez vous assurer que vous avez reçu votre numéro de confirmation.</p>
    </div>
  </section>
</div>

JavaScript

var overlay = new Overlay( document.querySelector( '.modal' ), {
  closeOnCancel: false,
  opener: document.querySelector( 'button' ),
  closeSelector, // selecteur CSS permetant de cibler les élément qui fermeront l'overlay au clic
  modal // booléen `true`  par défaut
});

// Ouvre l'overlay
overlay.show();

// Ferme l'overlay
overlay.close();
Paramètres optionnels
Nom Type Description
closeOnCancel Boolean Booléen permettant d'autoriser ou non la fermeture de l'overlay via la touche « Echap » ou en cliquant en dehors de l'overlay. Est à « true » par défaut.
closeSelector String Sélecteur CSS permetant de cibler des boutons qui doivent déclencher la fermeture lorsqu'ils sont activés.
modal Boolean Permet de définir l'overlay comme non modal lorsque sa valeur est à false. Par défault les éléments en dehors de l'overlay sont inaccessibles (valeur à true).
opener HTMLElement Élément HTML qui va recevoir le focus une fois l'overlay fermé. Utilise l'élément ayant le focus lors de l'ouverture de l'overlay par défaut.

Méthodes

Nom Description
show() Change l'attribut aria-hidden à false et désactive le reste le document (si le paramètre modal est à true).
close( returnValue ) Change l'attribut aria-hidden à true et réactive le reste du document si besoin. Envoi un évènement close depuis l'élément overlay. Cette méthode est aussi disponible sur l'élément racine de l'overlay. La propriété returnValue peut être déclarée en passant sa valeur en paramètre.
reset() Lorsqu’un élément est passé au constructeur, la méthode .reset() permet de replacer cet élément à son emplacement d’origine dans le DOM.
addEventListener(eventName, callback) Raccourci pour écouter les évènements close ou cancel events.
removeEventListener(eventName, callback) Raccourci pour ne plus écouter les évènements close ou cancel events.

Propriétés

Name Description
el L'élément HTML racine de l'overlay.
returnValue Aussi disponible sur l'élément racine de l'overlay. Permet de passer des données entre l'overlay et le reste du document.

Propriétés statiques

Contrairement aux propriétés des instances, les propriétés statiques sont disponibles sur le constructeur.

Name Description
stack File d'attente des overlays. Un tableau de tous les overlays actuellement ouverts.

Évènements

Lors de la fermeture d'un overlay, un évènement close est déclenché sur l'élément.

overlay.addEventListener( 'close', function( e ){
  // script utilisateur pour gérer la fermeture de l'overlay

  // remet l’élément dans son emplacement d’origine dans le DOM
  overlay.reset();
});

Dans le cas où l'utilisateur utilise la touche « Echap » ou bien clique en dehors de l'overlay lorsque celui-ci n'a pas le role alertdialog, un évènement cancel est déclenché sur l'overlay. Cet évènement permet d'annuler la fermeture de l'overlay en utilisant .preventDefault().

overlay.addEventListener( 'cancel', function( e ){
  // script utilisateur pour gérer la touche « Echap » ou le clic extérieur.

  // annule la fermeture de l'overlay
  e.preventDefault();
});

Script

Le script est disponible sur npm :

$ npm install @accede-web/overlay

Il ne reste alors qu'à l'appeler dans le script souhaité :

import Overlay from '@accede-web/overlay';

var overlay = new Overlay({…});

Dans le cas où ce script est utilisé avec babel et Webpack ou Rollup, il faut configurer babel afin qu'il compile ce plugin. Cela est possible via le fichier .babelrc ou dans les configurations de Webpack et Rollup :

{
  "exclude": "node_modules/!(@accede-web)/**",
}

Cette ligne continura d'exclure les scripts contenus dans le répertoire node_modules sauf ceux s'appelant @accede-web.

Le plugin est aussi téléchargeable depuis Github :
https://github.com/AcceDe-Web/overlay.

Le fichier est disponible en version minifiée ou non-minifiée dans le répertoire dist. Il est ensuite disponible sur l'objet window :

<script src="overlay.min.js"></script>

<script>
  var overlay = new window.Overlay({…});
</script>

Compatibilité

Ce composant a été testé sur les navigateurs suivants :

Pour fonctionner dans les navigateurs Internet Explorer, l'ajout d'un polyfill pour les Custom Event est requis. Vous pouvez utiliser celui se trouvant sur la page MDN de CustomEvent().

Aller plus loin

Le script de cette page est basé sur les notices d’accessibilité pour les composants d’interface riche des fenêtres modales (popins), boîtes de dialogue modales (popins de dialogue), et boîtes d’alerte modales (popins d’alerte), AcceDe Web d’Atalan.

N’hésitez pas à aller faire un tour chez eux pour approfondir le sujet.