Встановлення та налаштування

Готові версії

Власне встановлення

Щоб створити власну реалізацію, завантажте локальну копію (або вкажіть посилання на версію з CDN) мовного пакету, мінімізованого JS-файлу та мінімізованого CSS-файлу, а потім створіть новий екземпляр “Ed11y”.

Для імпорту ESM/JS-модулів:

Використовуйте .umd JavaScript-файли для застарілих браузерів і систем:

Параметри

Повна реалізація викликатиметься лише для авторизованих редакторів (відвідувачі вашого сайту не повинні бачити перевірку!), і може перевизначати будь-який з параметрів за замовчуванням.

Зверніть увагу, що для всіх параметрів передбачені значення за замовчуванням; вказуйте лише те, що хочете перевизначити.

Реалізація з широким налаштуванням може виглядати так:

Готові інтеграції часто встановлюють ці змінні динамічно — наприклад, завантажують сторінки в режимі “assertive”, якщо їх нещодавно редагували, і повертаються до режиму “polite” через кілька хвилин.

Оформлення

Кілька параметрів дозволяють вибрати тему, змінити кольори та вставити CSS.

Включайте лише ті параметри, які потрібно перевизначити, щоб спростити майбутні оновлення.

Корисні JS-події

Розробники тем можуть підписуватися на ці події, щоб реагувати на них і змінювати сторінку за потреби.

У типовому порядку появи…

  • ed11yRunCustomTests: надсилається, коли об’єкт Results готовий до додавання власних результатів. Зверніть увагу: параметр customTests має бути встановлений рівним кількості функцій власних тестів, які ви запускатимете (…мабуть, одна…), щоб ця подія надсилалася. Докладніше — в наступному розділі.
  • ed11yResults: надсилається після завершення всіх перевірок. API-інтеграції тепер можуть отримувати дані з об’єкта Ed11y.results.
  • ed11yPanelOpened: надсилається, якщо панель відкривається — автоматично або вручну.
  • ed11yShowHidden: надає число data-ed11y-result та булеве значення viaJump. Надсилається лише якщо параметр “ed11yShowHidden” встановлено і батьківський елемент відповідає вказаному селектору. Використовується для показу сповіщень у ще не відкритих контейнерах, наприклад, акордеонах, вкладках і каруселях. Приклади використання — в наступному розділі.
  • ed11yPop: надає ідентифікатор data-ed11y-result, а також посилання на об’єкти result і tip. Надсилається при появі підказки, дозволяючи змінювати підказки під час виконання.
  • ed11yShut: надає ідентифікатор data-ed11y-result. Надсилається при закритті підказки.
  • ed11yDismissalUpdate: надає розширену інформацію, коли користувач відхиляє або відновлює сповіщення. Використовується для API-інтеграцій. Об’єкт події містить:
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

Приклади можна знайти в наступних розділах.

Зміна підказок

Якщо вам потрібно лише змінити текст підказки, елементи глобального об’єкта ed11yLang.en (до виклику бібліотеки) або Ed11y.M (після виклику бібліотеки) можна перевизначати безпосередньо. Наприклад, у модулі Drupal, де ми зробили псевдонім мовного пакету як Drupal.ed11yLang:

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

Це стосується будь-якого з ключів за замовчуванням у файлі локалізації або активного мовного перекладу.

Модуль Drupal також додає власні посилання для редагування до підказок за допомогою параметра editLinks. Зверніть увагу на “Page editor” і “Layout editor:”

Tooltip with "Page editor" and "Layout editor" links inserted.

Спрощена версія коду, що встановлює цей параметр:

Потім модуль Drupal використовує подію ed11yPop, щоб динамічно показувати та приховувати посилання для редагування залежно від контексту при відображенні підказок.

Ця подія надає посилання на об’єкти result і tip:

Власні тести

Якщо параметр customTests є числом, Editoria11y надішле подію “ed11yRunCustomTests” під час перевірки, а потім зробить паузу до 500 мс, очікуючи відповідну кількість подій “ed11yResume”.

Це можна використати для виклику довільної кількості скриптів із власними тестами, які можуть додавати свої результати до масиву результатів до того, як будуть відображені підказки.

Наприклад, якщо ви хочете створити таку підказку, щоб позначати посилання, вставлені з електронних листів із замаскованими URL-адресами:

Tip reading "URL is Safe Link Encoded"

Вам потрібно:

  1. Додати слухач події ed11yRunCustomTests
  2. Знайти відповідні елементи
  3. Визначити текст підказки
  4. Надіслати подію “resume”, щоб Editoria11y відобразив підказку:

Робота зі сповіщеннями на прихованому або обмеженому за розміром вмісті

Багато інтерактивних компонентів (вкладки, слайдери, акордеони) приховують вміст. Інформаційна панель Editoria11y містить кнопки “наступне/попереднє” для переходу безпосередньо до проблем. Якщо Editoria11y вважає, що підказка до проблеми зараз невидима, він повідомить користувача про це, а потім виділить першого видимого предка — наприклад, блок навколо акордеона.

В ідеалі ваша тема зробить ці елементи видимими до того, як Editoria11y запустить перевірку видимості, і тоді все працюватиме як за помахом чарівної палички — каруселі автоматично прокручуватимуться, а акордеони відкриватимуться, щоб показати проблему.

Щоб зробити це при першому відкритті панелі (наприклад, розгорнути усі панелі акордеона з проблемами), додайте слухач JS-події для ed11yPanelOpened, виконайте querySelectorAll для відповідних елементів ed11y-element-result, а потім викличте функцію вашої теми для відображення потрібної частини сторінки.

Ось приклад на основі jQuery. При відкритті панелі вимикається закріплене меню (щоб елементи не перекривалися), а потім здійснюється пошук елементів ed11y-element-result всередині закритих елементів акордеона та імітується клік на їх кнопці перемикання:

Щоб показувати вміст лише при переході до конкретної підказки за допомогою кнопки “наступне” на панелі (наприклад, у закритій вкладці або наступному слайді каруселі), потрібно встановити hiddenHandlers з відповідними CSS-селекторами та checkVisible зі значенням TRUE у параметрах. Потім додайте слухач події ed11yShowHidden. Ця подія надсилається, якщо Editoria11y визначає, що підказка знаходиться всередині контейнера з одним із зазначених селекторів hiddenHandlers. Ця JS-подія міститиме ідентифікатор підказки, яку ось-ось буде відкрито. Після надсилання події Editoria11y зробить коротку паузу, щоб ваш JS-код встиг зробити елемент видимим.

Ось приклад з реалізації Penn State. Він знаходить елемент за вказаним ідентифікатором, потім шукає батьківський контейнер інтерактивного компонента і викликає подію для активації перемикача:

Остання примітка: деякі теми просто несумісні з перевіркою видимості — наприклад, контейнер <main> має висоту 0px. На таких сайтах слід повністю вимкнути перевірку видимості, встановивши checkVisible у значення false.