Instalacja i konfiguracja

Wersje ze wstępną konfiguracją

Instalacja niestandardowa

Aby zbudować własną implementację, pobierz lokalną kopię (lub odwołaj się do wersji CDN) paczki językowej, pliku JS min i pliku CSS min, a następnie utwórz nową instancję „Ed11y”.

Dla importów modułów ESM/JS:

Użyj plików JavaScript .umd dla starszych przeglądarek i systemów:

Parametry

Kompletna implementacja będzie wywoływana tylko dla zalogowanych redaktorów (odwiedzający nie powinni widzieć narzędzia sprawdzającego!) i może nadpisywać dowolne z domyślnych parametrów.

Pamiętaj, że wartości domyślne są dostępne dla wszystkich parametrów; uwzględniaj tylko te, które chcesz nadpisać.

Mocno dostosowana implementacja może wyglądać następująco:

Gotowe integracje często ustawiają te zmienne dynamicznie – np. ładując strony w trybie „assertive”, gdy zostały niedawno edytowane, i przełączając z powrotem na „polite” po kilku minutach.

Stylizacja

Kilka parametrów pozwala na wybór motywu, zmianę kolorów i wstrzykiwanie CSS.

Dołączaj tylko te parametry, które chcesz nadpisać, aby ułatwić przyszłe aktualizacje.

Przydatne zdarzenia JS

Twórcy motywów mogą podpiąć się pod te zdarzenia, aby reagować na nie i modyfikować stronę w razie potrzeby.

W typowej kolejności występowania:

  • ed11yRunCustomTests: wywoływane, gdy obiekt Results jest gotowy na wstrzyknięcie niestandardowych wyników. Należy pamiętać, że parametr customTests musi być ustawiony na liczbę niestandardowych funkcji testowych, które będą uruchamiane (…prawdopodobnie jedna…), aby to zdarzenie zostało wywołane. Szczegóły w następnej sekcji.
  • ed11yResults: wywoływane po zakończeniu wszystkich sprawdzeń. Integracje API mogą teraz pobierać dane z obiektu Ed11y.results.
  • ed11yPanelOpened: wywoływane, gdy panel otwiera się automatycznie lub ręcznie.
  • ed11yShowHidden: dostarcza liczbę data-ed11y-result i wartość logiczną viaJump. Wywoływane tylko wtedy, gdy parametr „ed11yShowHidden” jest ustawiony i element nadrzędny pasuje do selektora. Służy do odsłaniania alertów w jeszcze nieotwartych kontenerach, np. akordeonach, kartach i karuzelach. Przykłady użycia w następnej sekcji.
  • ed11yPop: dostarcza identyfikator data-ed11y-result, a także odwołania do obiektów result i tip. Wywoływane gdy pojawia się podpowiedź, umożliwiając modyfikację wskazówek w czasie rzeczywistym.
  • ed11yShut: dostarcza identyfikator data-ed11y-result. Wywoływane gdy podpowiedź jest zamykana.
  • ed11yDismissalUpdate: dostarcza rozszerzone informacje, gdy użytkownik odrzuca lub przywraca alert. Używane do integracji API. Obiekt zdarzenia zawiera:
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

Przykłady można znaleźć w następnych sekcjach.

Modyfikowanie podpowiedzi

Jeśli chcesz jedynie zmodyfikować tekst podpowiedzi, elementy w obiekcie globalnym ed11yLang.en (przed wywołaniem biblioteki) lub Ed11y.M (po wywołaniu biblioteki) mogą być bezpośrednio nadpisywane. Np. w module Drupal, gdzie aliasowaliśmy paczkę językową jako Drupal.ed11yLang:

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

Dotyczy to każdego z domyślnych kluczy w pliku lokalizacyjnym lub aktywnego tłumaczenia dla danego języka.

Moduł Drupal dodaje również niestandardowe linki do edycji w podpowiedziach, używając parametru editLinks. Zwróć uwagę na „Page editor” i „Layout editor”:

Podpowiedź z wstawionymi linkami „Page editor

Uproszczona wersja kodu ustawiającego ten parametr:

Moduł Drupal używa następnie zdarzenia ed11yPop, aby dynamicznie pokazywać i ukrywać link do edycji w zależności od kontekstu podczas wyświetlania podpowiedzi.

To zdarzenie dostarcza odwołania do obiektów result i tip:

Niestandardowe testy

Jeśli parametr customTests jest liczbą, Editoria11y wywoła zdarzenie „ed11yRunCustomTests” podczas sprawdzania, a następnie wstrzyma się na maksymalnie 500 ms, nasłuchując takiej liczby zdarzeń „ed11yResume”.

Można to wykorzystać do wywołania dowolnej liczby skryptów zawierających niestandardowe testy, które mogą przesyłać swoje wyniki do tablicy wyników, zanim podpowiedzi zostaną wyświetlone.

Na przykład, jeśli chcesz utworzyć taką podpowiedź, aby oznaczyć linki wklejone z e-maili z zaciemnionymi adresami URL:

Podpowiedź z treścią „URL is Safe Link Encoded

Należy:

  1. Dodać nasłuchiwanie zdarzenia ed11yRunCustomTests
  2. Znaleźć pasujące elementy
  3. Zdefiniować treść podpowiedzi
  4. Wywołać zdarzenie „resume”, aby Editoria11y narysował podpowiedź:

Obsługa alertów na ukrytej lub ograniczonej rozmiarowo treści

Wiele interaktywnych komponentów (karty, suwaki, akordeony) ukrywa treść. Panel informacyjny Editoria11y zawiera przyciski następny/poprzedni, umożliwiające przejście bezpośrednio do problemów. Jeśli Editoria11y uzna, że podpowiedź dotycząca problemu jest aktualnie niewidoczna, powiadomi użytkownika o problemie, a następnie podświetli pierwszego widocznego przodka – np. div wokół akordeonu.

W idealnym przypadku motyw sprawi, że te elementy staną się widoczne, zanim zostanie uruchomione sprawdzenie widoczności Editoria11y, dzięki czemu wszystko działa automatycznie — karuzele automatycznie przechodzą dalej, a akordeony automatycznie otwierają się, aby wyświetlić problem.

Aby to zrobić przy pierwszym otwarciu panelu (np. rozwijając wszystkie panele akordeonu z problemami), dodaj nasłuchiwanie zdarzenia JS ed11yPanelOpened, następnie wykonaj querySelectorAll dla odpowiednich elementów ed11y-element-result, a potem wywołaj funkcję motywu używaną do ujawnienia tej części strony.

Oto przykład oparty na jQuery. Gdy panel się otwiera, wyłącza przyklejone menu (aby elementy nie były zasłonięte), a następnie szuka elementów ed11y-element-result wewnątrz zamkniętych pozycji akordeonu i symuluje kliknięcie przycisku przełącznika:

Aby odsłonić treść tylko przy przeskakiwaniu do konkretnej podpowiedzi za pomocą przycisku „następny” w panelu (np. w zamkniętej karcie lub na następnym slajdzie karuzeli), należy ustawić w parametrach zarówno hiddenHandlers na odpowiednie selektory CSS, jak i checkVisible na TRUE. Następnie dodać nasłuchiwanie zdarzenia ed11yShowHidden. Jest ono wywoływane, gdy Editoria11y rozpoznaje, że podpowiedź jest wewnątrz kontenera pasującego do jednego z selektorów hiddenHandlers podanych na liście opcji. To zdarzenie JS będzie zawierać identyfikator podpowiedzi, którą zaraz otworzy. Editoria11y wstrzyma się wtedy na chwilę po wywołaniu tego zdarzenia, aby dać JS-owi czas na uwidocznienie elementu.

Oto przykład z implementacji Penn State. Szuka elementu pasującego do podanego identyfikatora, następnie znajduje jego nadrzędny kontener interaktywnego komponentu i wywołuje zdarzenie aktywujące jego przełącznik:

Ostatnia uwaga: niektóre motywy są po prostu niekompatybilne ze sprawdzaniem widoczności — np. kontener <main> ma wysokość 0px. Takie strony powinny wyłączyć całe sprawdzanie widoczności, ustawiając checkVisible na false.