Installazione e configurazione

Versioni preconfigurate

• Programma di installazione Drupal
• Programma di installazione WordPress
• Programma di installazione Kirby (contrib)
• Programma di installazione CraftCMS (contrib)

Installazione personalizzata

Per creare una propria implementazione, scarica una copia locale (o fai riferimento a una versione CDN) di un pacchetto linguistico, del file JS min e del file CSS min, quindi crea una nuova istanza “Ed11y”.

Per l’importazione di moduli ESM/JS:

Usa i file JavaScript .umd per browser e sistemi legacy:

Parametri

Un’implementazione completa verrà richiamata solo per gli editor che hanno effettuato l’accesso (non vuoi che i visitatori del sito vedano il tuo verificatore!), e può sovrascrivere qualsiasi parametro predefinito.

Tieni presente che i valori predefiniti sono forniti per tutti i parametri; includi solo quelli che vuoi sovrascrivere.

Un’implementazione fortemente personalizzata potrebbe apparire così:

Le integrazioni chiavi in mano impostano spesso queste variabili al volo — ad esempio, caricando le pagine in modalità “assertive” quando sono state modificate di recente, e tornando alla modalità “polite” dopo qualche minuto.

Temi

Diversi parametri consentono di selezionare un tema, sovrascrivere i colori e iniettare CSS.

Includi solo i parametri che devi sovrascrivere per facilitare i futuri aggiornamenti.

Eventi JS utili

Gli sviluppatori di temi possono collegare questi eventi per reagire e modificare la pagina secondo necessità.

Nell'ordine tipico di comparsa:

• ed11yRunCustomTests: inviato quando l’oggetto Results è pronto per ricevere risultati personalizzati. Tieni presente che il parametro customTests deve essere impostato sul numero di funzioni di test personalizzate che verranno eseguite (…probabilmente una…) affinché questo evento venga inviato. Dettagli nella sezione seguente.
• ed11yResults: inviato quando tutti i controlli sono terminati. Le integrazioni API possono ora raccogliere dati dall’oggetto Ed11y.results.
• ed11yPanelOpened: inviato se il pannello si apre, automaticamente o manualmente.
• ed11yShowHidden: fornisce un numero data-ed11y-result e un booleano viaJump. Inviato solo se il parametro “ed11yShowHidden” è impostato e un elemento padre corrisponde a un selettore. Utilizzato per rivelare avvisi in contenitori non ancora aperti, ad es. accordion, schede e caroselli. Esempi di utilizzo nella sezione successiva.
• ed11yPop: fornisce l’ID data-ed11y-result, nonché riferimenti agli oggetti result e tip. Inviato quando appare un tooltip, permettendo di modificare i suggerimenti in fase di esecuzione.
• ed11yShut: fornisce l’ID data-ed11y-result. Inviato quando un tooltip si chiude.
• ed11yDismissalUpdate: fornisce informazioni estese quando un utente ignora o ripristina un avviso. Utilizzato per le integrazioni API. L’oggetto evento contiene:
  • dismissPage
  • dismissTest
  • dismissKey
  • dismissAction

Esempi sono disponibili nelle sezioni seguenti.

Modificare i suggerimenti

Se vuoi solo modificare il testo di un suggerimento, gli elementi nell’oggetto globale ed11yLang.en (prima di richiamare la libreria) o in Ed11y.M (dopo aver richiamato la libreria) possono essere direttamente sovrascritti. Ad esempio, nel modulo Drupal dove abbiamo creato un alias del pacchetto linguistico come Drupal.ed11yLang:

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

Questo vale per qualsiasi chiave predefinita nel file di localizzazione o nella traduzione specifica della lingua attiva.

Il modulo Drupal aggiunge anche link di modifica personalizzati ai suggerimenti, usando il parametro editLinks. Nota “Page editor” e “Layout editor:”

Una versione semplificata del codice che imposta quel parametro:

Il modulo Drupal usa quindi l’evento ed11yPop per mostrare e nascondere dinamicamente il link di modifica in base al contesto quando vengono visualizzati i suggerimenti.

Questo evento fornisce riferimenti agli oggetti result e tip:

Test personalizzati

Se il parametro customTests è un numero, Editoria11y invierà un evento “ed11yRunCustomTests” durante il controllo, e poi si metterà in pausa fino a 500ms in attesa di quel numero di eventi “ed11yResume”.

Questo può essere sfruttato per richiamare quanti script contenenti test personalizzati si desidera, che possono inserire i propri risultati nell’array dei risultati prima che i suggerimenti vengano disegnati.

Ad esempio, se volessi creare questo suggerimento, per segnalare i link incollati da email con URL offuscati:

Dovresti:

1. Aggiungere un listener per l’evento ed11yRunCustomTests
2. Trovare gli elementi corrispondenti
3. Definire il messaggio del suggerimento
4. Inviare l’evento “resume” per consentire a Editoria11y di disegnare il suggerimento:

Gestire gli avvisi su contenuti nascosti o a dimensione vincolata

Molti componenti interattivi (schede, slider, accordion) nascondono i contenuti. Il pannello informativo di Editoria11y include pulsanti avanti/indietro per passare direttamente ai problemi. Se Editoria11y ritiene che il tooltip del problema sia attualmente invisibile, avviserà l’utente che qualcosa non va, evidenziando quindi il primo antenato visibile — ad es. il div attorno a un accordion.

Idealmente, il tema renderà visibili quegli elementi prima che il controllo di visibilità di Editoria11y venga eseguito, in modo che tutto funzioni come per magia per gli utenti — i caroselli avanzano automaticamente e gli accordion si aprono automaticamente per mostrare il problema.

Per fare questo quando il pannello si apre per la prima volta (ad es. aprendo tutti i pannelli accordion con problemi), aggiungi un listener di eventi JS per ed11yPanelOpened, poi esegui un querySelectorAll per gli elementi ed11y-element-result rilevanti, e infine attiva qualsiasi funzione del tema che riveli quella parte della pagina.

Ecco un esempio basato su jQuery. Quando il pannello si apre, disabilita un menu fisso (in modo che gli elementi non siano coperti), poi cerca eventuali elementi ed11y-element-result all’interno di voci accordion chiuse e simula un clic sul relativo pulsante di apertura:

Per rivelare il contenuto solo quando si salta a un suggerimento specifico tramite il pulsante “avanti” del pannello (ad es. in una scheda chiusa o nella diapositiva successiva del carosello), dovrai impostare sia hiddenHandlers su selettori CSS rilevanti sia checkVisible su TRUE nei parametri. Quindi aggiungi un listener per l’evento ed11yShowHidden. Questo viene generato se Editoria11y riconosce che un suggerimento si trova all’interno di un contenitore con uno dei selettori hiddenHandlers elencati nelle opzioni. Questo evento JS includerà l’ID del suggerimento che sta per aprire. Editoria11y si metterà quindi brevemente in pausa dopo l’invio di questo evento, per dare al tuo JS il tempo di rendere visibile l’elemento.

Ecco un esempio da un’implementazione della Penn State. Cerca l’elemento corrispondente all’ID fornito, trova il suo contenitore componente interattivo padre e attiva il suo evento per attivarne il toggle:

Nota finale: alcuni temi non sono semplicemente compatibili con il controllo della visibilità — ad es. il contenitore <main> ha un’altezza di 0px. Tali siti dovrebbero disabilitare tutti i controlli di visibilità impostando checkVisible su false.