Installation & Konfiguration

Vorkonfigurierte Versionen

Benutzerdefinierte Installation

Um Ihre eigene Implementierung zu erstellen, laden Sie eine lokale Kopie herunter (oder verweisen Sie auf eine CDN-Version) eines Sprachpakets, der minimierten JS-Datei und der CSS-Datei herunter und erstellen Sie dann eine neue „Ed11y”-Instanz.

Für ESM/JS-Modulimporte:

Verwenden Sie die .umd-JavaScript-Dateien für ältere Browser und Systeme:

Parameter

Eine vollständige Implementierung wird nur für angemeldete Redakteure aufgerufen (Ihre Website-Besucher sollen den Prüfer ja nicht sehen!) und kann alle Standardparameter überschreiben.

Beachten Sie, dass für alle Parameter Standardwerte vorhanden sind; geben Sie nur an, was Sie überschreiben möchten.

Eine stark angepasste Implementierung könnte so aussehen:

Schlüsselfertige Integrationen setzen diese Variablen oft dynamisch -- z. B. werden Seiten im „assertive”-Modus geladen, wenn sie kürzlich bearbeitet wurden, und wechseln nach einigen Minuten wieder in den „polite”-Modus.

Theming

Mehrere Parameter ermöglichen die Auswahl eines Themes, das Überschreiben von Farben und das Einbinden von CSS.

Geben Sie nur die Parameter an, die Sie überschreiben müssen, um zukünftige Updates zu erleichtern.

Nützliche JS-Ereignisse

Theme-Entwickler können diese Ereignisse nutzen, um auf Änderungen zu reagieren und die Seite bei Bedarf anzupassen.

In typischer Reihenfolge ihres Auftretens:

  • ed11yRunCustomTests: wird ausgelöst, wenn das Results-Objekt bereit ist, benutzerdefinierte Ergebnisse zu empfangen. Beachten Sie, dass der customTests-Parameter auf die Anzahl der auszuführenden benutzerdefinierten Testfunktionen gesetzt sein muss (vermutlich eine), damit dieses Ereignis ausgelöst wird. Details im folgenden Abschnitt.
  • ed11yResults: wird ausgelöst, wenn alle Prüfungen abgeschlossen sind. API-Integrationen können nun Daten aus dem Ed11y.results-Objekt abrufen.
  • ed11yPanelOpened: wird ausgelöst, wenn das Panel automatisch oder manuell geöffnet wird.
  • ed11yShowHidden: liefert eine data-ed11y-result-Nummer und einen viaJump-Boolean. Wird nur ausgelöst, wenn der Parameter „hiddenHandlers” gesetzt ist und ein übergeordnetes Element des Elements mit einem Selektor übereinstimmt. Dient zur Anzeige von Hinweisen in noch nicht geöffneten Containern, z. B. Akkordeons, Tabs und Karussells. Verwendungsbeispiele im nächsten Abschnitt.
  • ed11yPop: liefert die data-ed11y-result-ID sowie Referenzen auf die result- und tip-Objekte. Wird ausgelöst, wenn ein Tooltip erscheint, sodass Sie die Hinweise zur Laufzeit ändern können.
  • ed11yShut: liefert die data-ed11y-result-ID. Wird ausgelöst, wenn ein Tooltip geschlossen wird.
  • ed11yDismissalUpdate: liefert erweiterte Informationen, wenn ein Benutzer einen Hinweis ausblendet oder wiederherstellt. Wird für API-Integrationen verwendet. Das Ereignisobjekt enthält:
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

Beispiele finden Sie in den folgenden Abschnitten.

Hinweise anpassen

Wenn Sie lediglich den Text eines Hinweises ändern möchten, können Einträge im globalen ed11yLang.en-Objekt (vor dem Aufruf der Bibliothek) oder in Ed11y.M (nach dem Aufruf) direkt überschrieben werden. Z. B. im Drupal-Modul, wo das Sprachpaket als Drupal.ed11yLang referenziert wird:

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

Dies gilt für alle Standard-Schlüssel in der Lokalisierungsdatei sowie für die aktive sprachspezifische Übersetzung.

Das Drupal-Modul fügt den Hinweisen auch benutzerdefinierte Bearbeitungslinks hinzu, mithilfe des editLinks-Parameters. Beachten Sie „Page editor” und „Layout editor”:

Tooltip mit eingefügten Links „Page editor

Eine vereinfachte Version des Codes, der diesen Parameter verwendet:

Das Drupal-Modul nutzt dann das ed11yPop-Ereignis, um den Bearbeitungslink je nach Kontext dynamisch ein- und auszublenden, wenn Hinweise angezeigt werden.

Dieses Ereignis stellt Referenzen auf die result- und tip-Objekte bereit:

Benutzerdefinierte Tests

Wenn der customTests-Parameter eine Zahl ist, löst Editoria11y beim Prüfen ein „ed11yRunCustomTests”-Ereignis aus und wartet dann bis zu 500 ms auf diese Anzahl von „ed11yResume”-Ereignissen.

Dies kann genutzt werden, um beliebig viele Skripte mit benutzerdefinierten Tests aufzurufen, die ihre Ergebnisse in das Ergebnis-Array einfügen, bevor die Hinweise dargestellt werden.

Wenn Sie beispielsweise diesen Hinweis erstellen möchten, um Links zu markieren, die aus E-Mails mit verschleierten URLs eingefügt wurden:

Tip reading "URL is Safe Link Encoded"

Dazu würden Sie:

  1. Einen Listener für das ed11yRunCustomTests-Ereignis hinzufügen
  2. Passende Elemente finden
  3. Die Hinweismeldung definieren
  4. Das „resume”-Ereignis auslösen, damit Editoria11y den Hinweis darstellt:

Umgang mit Hinweisen auf verborgenen oder größenbeschränkten Inhalten

Viele interaktive Komponenten (Tabs, Schieberegler, Akkordeons) verbergen Inhalte. Das Editoria11y-Infopanel enthält Vor-/Zurück-Schaltflächen, um direkt zu Problemen zu springen. Wenn Editoria11y vermutet, dass der Tooltip eines Problems aktuell unsichtbar ist, informiert es den Benutzer und hebt dann das erste sichtbare Elternelement hervor -- z. B. das Div um ein Akkordeon.

Idealerweise macht Ihr Theme diese Elemente sichtbar, bevor die Sichtbarkeitsprüfung von Editoria11y läuft, sodass alles wie von selbst funktioniert -- Karussells scrollen automatisch weiter und Akkordeons klappen sich automatisch auf, um das Problem anzuzeigen.

Um dies beim ersten Öffnen des Panels zu tun (z. B. alle Akkordeon-Panels mit Problemen aufzuklappen), fügen Sie einen JS-Ereignislistener für ed11yPanelOpened hinzu, führen Sie dann ein querySelectorAll für relevante ed11y-element-result-Elemente durch und rufen Sie die Funktion auf, die Ihr Theme verwendet, um diesen Teil der Seite anzuzeigen.

Hier ein jQuery-basiertes Beispiel. Wenn das Panel geöffnet wird, deaktiviert es ein fixiertes Menü (damit Elemente nicht verdeckt werden), sucht dann nach ed11y-element-result-Elementen innerhalb geschlossener Akkordeon-Elemente und simuliert einen Klick auf deren Toggle-Schaltfläche:

Um Inhalte nur dann anzuzeigen, wenn über die „Weiter”-Schaltfläche des Panels zu einem bestimmten Hinweis gesprungen wird (z. B. in einem geschlossenen Tab oder zur nächsten Karussellfolie), müssen Sie in Ihren Parametern sowohl hiddenHandlers auf relevante CSS-Selektoren als auch checkVisible auf TRUE setzen. Fügen Sie dann einen Ereignislistener für das ed11yShowHidden-Ereignis hinzu. Dieses wird ausgelöst, wenn Editoria11y erkennt, dass sich ein Hinweis in einem Container mit einem der aufgelisteten hiddenHandlers-Selektoren befindet. Das JS-Ereignis enthält die ID des Hinweises, der geöffnet werden soll. Editoria11y pausiert dann kurz nach dem Auslösen dieses Ereignisses, um Ihrem JS Zeit zu geben, das Element sichtbar zu machen.

Hier ein Beispiel aus einer Penn-State-Implementierung. Es sucht das Element mit der angegebenen ID, findet dann den übergeordneten Container der interaktiven Komponente und löst dessen Ereignis aus, um den Toggle zu aktivieren:

Abschließend: Manche Themes sind schlicht nicht mit der Sichtbarkeitsprüfung kompatibel -- z. B. wenn der <main>-Container eine Höhe von 0px hat. Solche Websites sollten alle Sichtbarkeitsprüfungen deaktivieren, indem sie checkVisible auf false setzen.