Instal & konfigurasi

Versi yang sudah dikonfigurasi

Instalasi kustom

Untuk membangun implementasi Anda sendiri, unduh salinan lokal (atau referensikan versi CDN) dari paket Bahasa, file JS min, dan file CSS min, lalu buat instance "Ed11y" baru.

Untuk impor modul ESM/JS:

Gunakan file JavaScript .umd untuk browser dan sistem lama:

Parameter

Implementasi lengkap hanya akan dipanggil untuk editor yang sudah login (Anda tidak ingin pengunjung situs melihat pemeriksa Anda!), dan dapat mengganti salah satu dari parameter default.

Perhatikan bahwa default disediakan untuk semua parameter; hanya sertakan hal-hal yang ingin Anda ganti.

Implementasi yang sangat dikustomisasi mungkin terlihat seperti ini:

Integrasi turnkey sering menetapkan variabel-variabel ini secara dinamis — mis., memuat halaman dalam mode "assertive" saat baru saja diedit, dan kembali ke "polite" setelah beberapa menit.

Tema

Beberapa parameter memungkinkan pemilihan tema, penggantian warna, dan injeksi CSS.

Hanya sertakan parameter yang perlu Anda ganti untuk memudahkan pembaruan di masa mendatang.

Acara JS yang berguna

Pembuat tema dapat memanfaatkan event-event ini untuk bereaksi dan memodifikasi halaman sesuai kebutuhan.

Dalam urutan kemunculan yang umum…

  • ed11yRunCustomTests: dikirimkan saat objek Results siap untuk menerima hasil kustom. Perhatikan bahwa parameter customTests harus diatur ke jumlah fungsi pengujian kustom yang akan Anda jalankan (…mungkin satu…) agar event ini dikirimkan. Detail di bagian berikut.
  • ed11yResults: dikirimkan saat semua pemeriksaan selesai. Integrasi API sekarang dapat mengambil data dari objek Ed11y.results.
  • ed11yPanelOpened: dikirimkan jika panel terbuka, secara otomatis atau manual.
  • ed11yShowHidden: menyediakan nomor data-ed11y-result dan boolean viaJump. Hanya dikirimkan jika parameter "ed11yShowHidden" diatur dan induk elemen cocok dengan selektor. Digunakan untuk menampilkan peringatan dalam kontainer yang belum terbuka, mis., akordion, tab, dan korsel. Contoh penggunaan di bagian berikutnya.
  • ed11yPop: menyediakan ID data-ed11y-result, serta referensi ke objek result dan tip. Dikirimkan saat tooltip muncul, memungkinkan Anda memodifikasi tips saat runtime.
  • ed11yShut: menyediakan ID data-ed11y-result. Dikirimkan saat tooltip ditutup.
  • ed11yDismissalUpdate: menyediakan informasi tambahan ketika pengguna menolak atau memulihkan peringatan. Digunakan untuk integrasi API. Objek event berisi:
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

Contoh dapat ditemukan di bagian berikut.

Memodifikasi tips

Jika yang ingin Anda lakukan hanya memodifikasi teks tip, item dalam global ed11yLang.en (sebelum memanggil perpustakaan) atau objek Ed11y.M (setelah memanggil perpustakaan) dapat langsung diganti. Mis., di modul Drupal di mana kami memberi alias paket bahasa ke Drupal.ed11yLang:

Drupal.ed11yLang.lang.testNames.title = "Please write shorter headings."

Hal ini berlaku untuk semua kunci default dalam file lokalisasi atau terjemahan khusus bahasa yang aktif.

Modul Drupal juga menambahkan tautan edit kustom ke tips, menggunakan parameter editLinks. Perhatikan "Page editor" dan "Layout editor:"

Tooltip dengan tautan "Page editor" dan "Layout editor" yang disisipkan.

Versi sederhana dari kode yang menetapkan parameter tersebut:

Modul Drupal kemudian menggunakan event ed11yPop untuk secara dinamis menampilkan dan menyembunyikan tautan edit berdasarkan konteks saat tips ditampilkan.

Event ini menyediakan referensi ke objek result dan tip:

Pengujian kustom

Jika parameter customTests adalah sebuah angka, Editoria11y akan mengirimkan event "ed11yRunCustomTests" saat memeriksa, lalu berhenti sejenak selama 500 md sambil mendengarkan event "ed11yResume" sebanyak angka tersebut.

Ini dapat dimanfaatkan untuk memanggil sebanyak mungkin skrip yang berisi pengujian kustom sesuai kebutuhan, yang dapat mendorong hasilnya ke dalam array hasil sebelum tips dirender.

Misalnya, jika Anda ingin membuat tip ini, untuk menandai tautan yang telah ditempel dari email dengan URL yang disamarkan:

Tip bertuliskan "URL is Safe Link Encoded"

Anda akan:

  1. Tambahkan listener untuk event ed11yRunCustomTests
  2. Temukan elemen yang cocok
  3. Tentukan pesan tip
  4. Kirimkan event "resume" agar Editoria11y merender tip:

Menangani peringatan pada konten tersembunyi atau terbatas ukuran

Banyak komponen interaktif (tab, slider, akordion) menyembunyikan konten. Panel info Editoria11y menyertakan tombol berikutnya/sebelumnya untuk langsung melompat ke isu. Jika Editoria11y berpikir tooltip isu saat ini tidak terlihat, ia akan memberi tahu pengguna bahwa ada yang salah, lalu menyorot elemen induk pertama yang terlihat — mis., div di sekitar akordion.

Idealnya, tema Anda akan membuat elemen-elemen tersebut terlihat sebelum pemeriksaan visibilitas Editoria11y berjalan, sehingga semuanya berfungsi seperti sulap bagi pengguna Anda — korsel maju otomatis dan akordion terbuka otomatis untuk menampilkan isu.

Untuk melakukan ini saat panel pertama kali terbuka (mis., membuka semua panel akordion dengan isu) tambahkan listener event JS untuk ed11yPanelOpened, lalu lakukan querySelectorAll untuk elemen ed11y-element-result yang relevan, dan kemudian picu fungsi apa pun yang digunakan tema Anda untuk menampilkan bagian halaman tersebut.

Berikut contoh berbasis jQuery. Ketika panel terbuka, ia menonaktifkan menu lengket (agar elemen tidak tertutup), lalu mencari elemen ed11y-element-result di dalam item akordion yang tertutup dan mensimulasikan klik pada tombol togglenya:

Untuk menampilkan konten hanya saat melompat ke tip tertentu melalui tombol "berikutnya" panel (mis., di tab tertutup atau slide korsel berikutnya), Anda perlu menetapkan hiddenHandlers ke selektor CSS yang relevan dan checkVisible ke TRUE dalam parameter Anda. Kemudian tambahkan listener untuk event ed11yShowHidden. Ini dilempar jika Editoria11y mengenali bahwa tip berada di dalam kontainer dengan salah satu selektor hiddenHandlers yang disediakan dalam daftar opsi. Event JS ini akan menyertakan ID tip yang akan dibuka. Editoria11y kemudian akan berhenti sejenak setelah mengirimkan event ini, untuk memberikan waktu bagi JS Anda agar elemen menjadi terlihat.

Berikut contoh dari implementasi Penn State. Ini mencari elemen yang cocok dengan ID yang disediakan, lalu menemukan kontainer komponen interaktif induknya, dan memicu event untuk mengaktifkan togglenya:

Catatan terakhir: beberapa tema tidak kompatibel dengan pemeriksaan visibilitas — mis., kontainer <main> memiliki tinggi 0px. Situs-situs tersebut harus menonaktifkan semua pemeriksaan visibilitas dengan menetapkan checkVisible ke false.