Installation et configuration

Versions préconfigurées

Installation personnalisée

Pour créer votre propre implémentation, téléchargez une copie locale (ou référencez une version CDN) d'un pack de langue, du fichier JS minifié et du fichier CSS minifié, puis créez une nouvelle instance “Ed11y”.

Pour les imports de modules ESM/JS :

Utilisez les fichiers JavaScript .umd pour les navigateurs et systèmes anciens :

Paramètres

Une implémentation complète ne sera appelée que pour les éditeurs connectés (vous ne voulez pas que vos visiteurs voient le vérificateur !), et peut remplacer n’importe lequel des paramètres par défaut.

Notez que des valeurs par défaut sont fournies pour tous les paramètres ; n’incluez que ceux que vous souhaitez remplacer.

Une implémentation très personnalisée pourrait ressembler à ceci :

Les intégrations clés en main définissent souvent ces variables à la volée – par exemple, en chargeant les pages en mode “assertive” lorsqu'elles ont été récemment modifiées, puis en repassant en mode “polite” après quelques minutes.

Personnalisation du thème

Plusieurs paramètres permettent de sélectionner un thème, de remplacer les couleurs et d'injecter du CSS.

Pour faciliter les mises à jour futures, n'incluez que les paramètres que vous devez remplacer.

Événements JavaScript utiles

Les développeurs de thèmes peuvent écouter ces événements pour réagir et modifier la page selon les besoins.

Par ordre typique d'apparition…

  • ed11yRunCustomTests : déclenché lorsque l'objet Results est prêt à recevoir des résultats personnalisés. Notez que le paramètre customTests doit être défini sur le nombre de fonctions de tests personnalisés que vous allez exécuter (…probablement un seul…) pour que cet événement soit déclenché. Détails dans la section suivante.
  • ed11yResults : déclenché lorsque toutes les vérifications sont terminées. Les intégrations API peuvent alors récupérer les données de l'objet Ed11y.results.
  • ed11yPanelOpened : déclenché si le panneau s'ouvre, automatiquement ou manuellement.
  • ed11yShowHidden : fournit un numéro data-ed11y-result et un booléen viaJump. Déclenché uniquement si le paramètre “ed11yShowHidden” est défini et qu'un parent de l'élément correspond à un sélecteur. Utilisé pour révéler les alertes dans des conteneurs non encore ouverts, par exemple les accordéons, onglets et carrousels. Exemples d'utilisation dans la section suivante.
  • ed11yPop : fournit l'identifiant data-ed11y-result, ainsi que des références aux objets result et tip. Déclenché lorsqu'une infobulle apparaît, ce qui vous permet de modifier les infobulles en temps réel.
  • ed11yShut : fournit l'identifiant data-ed11y-result. Déclenché lorsqu'une infobulle se ferme.
  • ed11yDismissalUpdate : fournit des informations étendues lorsqu'un utilisateur masque ou rétablit une alerte. Utilisé pour les intégrations API. L'objet événement contient :
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

Des exemples sont disponibles dans les sections suivantes.

Modifier les infobulles

Si vous souhaitez simplement modifier le texte d'une infobulle, les éléments de l'objet global ed11yLang.en (avant l'appel de la bibliothèque) ou Ed11y.M (après l'appel de la bibliothèque) peuvent être directement remplacés. Par exemple, dans le module Drupal où nous avons créé un alias du pack de langue vers Drupal.ed11yLang :

Drupal.ed11yLang.lang.testNames.title = “Please write shorter headings.”

Cela est vrai pour toutes les clés par défaut du fichier de localisation ou la traduction active spécifique à la langue.

Le module Drupal ajoute également des liens d'édition personnalisés aux infobulles, à l'aide du paramètre editLinks. Notez “Page editor” et “Layout editor” :

Infobulle avec les liens « Page editor » et « Layout editor » insérés.

Une version simplifiée du code qui définit ce paramètre :

Le module Drupal utilise ensuite l'événement ed11yPop pour afficher et masquer dynamiquement le lien d'édition en fonction du contexte lorsque les infobulles sont affichées.

Cet événement fournit des références aux objets result et tip :

Tests personnalisés

Si le paramètre customTests est un nombre, Editoria11y déclenchera un événement “ed11yRunCustomTests” pendant la vérification, puis se mettra en pause pendant 500 ms maximum en attendant ce nombre d'événements “ed11yResume”.

Cela peut être exploité pour appeler autant de scripts contenant des tests personnalisés que vous le souhaitez, qui peuvent ajouter leurs résultats dans le tableau de résultats avant que les infobulles ne soient affichées.

Par exemple, si vous souhaitiez créer cette infobulle pour signaler des liens collés depuis des e-mails avec des URL obscurcies :

Infobulle affichant « URL is Safe Link Encoded »

Vous devriez :

  1. Ajouter un écouteur pour l'événement ed11yRunCustomTests
  2. Trouver les éléments correspondants
  3. Définir le message de l'infobulle
  4. Déclencher l'événement “resume” pour qu'Editoria11y affiche l'infobulle :

Gérer les alertes sur du contenu masqué ou à taille limitée

De nombreux composants interactifs (onglets, carrousels, accordéons) masquent du contenu. Le panneau d’information d’Editoria11y inclut des boutons précédent/suivant pour accéder directement aux problèmes. Si Editoria11y estime que l’infobulle du problème est actuellement invisible, il avertira l’utilisateur que quelque chose ne va pas, puis mettra en surbrillance le premier ancêtre visible – par exemple, le div autour d’un accordéon.

Idéalement, votre thème rendra ces éléments visibles avant que la vérification de visibilité d’Editoria11y ne s’exécute, afin que tout fonctionne comme par magie pour vos utilisateurs — les carrousels avancent automatiquement et les accordéons s’ouvrent automatiquement pour afficher le problème.

Pour ce faire lorsque le panneau s’ouvre pour la première fois (par exemple, déplier tous les panneaux d’accordéon contenant des problèmes), ajoutez un écouteur d’événement JavaScript pour ed11yPanelOpened, puis effectuez un querySelectorAll pour les éléments ed11y-element-result concernés, et déclenchez la fonction que votre thème utilise pour révéler cette partie de la page.

Voici un exemple basé sur jQuery. Lorsque le panneau s’ouvre, il désactive un menu fixe (pour que les éléments ne soient pas recouverts), puis recherche tous les éléments ed11y-element-result à l’intérieur d’éléments d’accordéon fermés et simule un clic sur leur bouton de bascule :

Pour révéler du contenu uniquement lors du passage à une infobulle spécifique via le bouton “suivant” du panneau (par exemple, dans un onglet fermé ou la diapositive suivante du carrousel), vous devrez définir à la fois hiddenHandlers avec les sélecteurs CSS concernés et checkVisible à TRUE dans vos paramètres. Ajoutez ensuite un écouteur pour l’événement ed11yShowHidden. Celui-ci est déclenché si Editoria11y détecte qu’une infobulle se trouve dans un conteneur correspondant à l’un des sélecteurs hiddenHandlers fournis dans la liste d’options. Cet événement JavaScript inclura l’identifiant de l’infobulle qu’il est sur le point d’ouvrir. Editoria11y marquera ensuite une brève pause après avoir déclenché cet événement, pour laisser à votre JavaScript le temps de rendre l’élément visible.

Voici un exemple issu d’une implémentation de Penn State. Il recherche l’élément correspondant à l’identifiant fourni, puis trouve le conteneur parent du composant interactif et déclenche son événement pour activer sa bascule :

Dernière remarque : certains thèmes ne sont tout simplement pas compatibles avec la vérification de visibilité — par exemple, le conteneur <main> a une hauteur de 0px. Ces sites doivent désactiver toute vérification de visibilité en définissant checkVisible à false.