Instalar & Configurar

Versões pré-configuradas

Instalação personalizada

Para criar sua própria implementação, baixe uma cópia local (ou referencie uma versão via CDN) do pacote de idiomas, do arquivo JS minificado e do arquivo CSS minificado e, em seguida, crie uma nova instância “Ed11y”.

Para importações de módulos ESM/JS:

Use os arquivos JavaScript .umd para navegadores e sistemas legados:

Parâmetros

Uma implementação completa será acionada somente para editores autenticados (você não quer que os visitantes do seu site vejam o verificador!), e pode substituir qualquer um dos parâmetros padrão.

Observe que valores padrão são fornecidos para todos os parâmetros; inclua apenas o que deseja substituir.

Uma implementação altamente personalizada pode ter esta aparência:

Integrações prontas para uso costumam definir essas variáveis dinamicamente — por exemplo, carregando páginas no modo “assertive” quando foram editadas recentemente e voltando para o modo “polite” após alguns minutos.

Tematização

Diversos parâmetros permitem selecionar um tema, substituir cores e injetar CSS.

Inclua apenas os parâmetros que deseja substituir para facilitar atualizações futuras.

Eventos JS úteis

Desenvolvedores de temas podem escutar esses eventos para reagir e modificar a página conforme necessário.

Na ordem típica em que ocorrem...

  • ed11yRunCustomTests: disparado quando o objeto Results está pronto para receber resultados personalizados. Observe que o parâmetro customTests deve ser definido com o número de funções de teste personalizadas que você executará (…provavelmente uma…) para que este evento seja disparado. Detalhes na seção seguinte.
  • ed11yResults: disparado quando todas as verificações são concluídas. Integrações com API podem agora extrair dados do objeto Ed11y.results.
  • ed11yPanelOpened: disparado quando o painel abre, automática ou manualmente.
  • ed11yShowHidden: fornece um número data-ed11y-result e um booleano viaJump. Disparado apenas se o parâmetro “ed11yShowHidden” estiver definido e um elemento pai corresponder a um seletor. Usado para revelar alertas em contêineres ainda não abertos, como acordeões, abas e carrosséis. Exemplos de uso na próxima seção.
  • ed11yPop: fornece o ID de data-ed11y-result, bem como referências aos objetos result e tip. Disparado quando uma dica de ferramenta aparece, permitindo modificar as dicas em tempo de execução.
  • ed11yShut: fornece o ID de data-ed11y-result. Disparado quando uma dica de ferramenta é fechada.
  • ed11yDismissalUpdate: fornece informações estendidas quando um usuário descarta ou restaura um alerta. Usado para integrações com API. O objeto do evento contém:
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

Exemplos podem ser encontrados nas seções seguintes.

Modificar dicas de ferramenta

Se tudo o que você deseja é modificar o texto de uma dica, os itens nos objetos globais ed11yLang.en (antes de chamar a biblioteca) ou Ed11y.M (após chamar a biblioteca) podem ser substituídos diretamente. Por exemplo, no módulo Drupal, onde criamos um alias do pacote de idiomas para Drupal.ed11yLang:

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

Isso se aplica a qualquer uma das chaves padrão no arquivo de localização ou na tradução específica do idioma ativo.

O módulo Drupal também adiciona links de edição personalizados às dicas, usando o parâmetro editLinks. Observe “Page editor” e “Layout editor:”

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

Uma versão simplificada do código que define esse parâmetro:

O módulo Drupal usa então o evento ed11yPop para mostrar e ocultar dinamicamente o link de edição com base no contexto quando as dicas são exibidas.

Este evento fornece referências aos objetos result e tip:

Testes personalizados

Se o parâmetro customTests for um número, o Editoria11y irá disparar um evento “ed11yRunCustomTests” durante a verificação e, em seguida, pausar por até 500ms aguardando esse número de eventos “ed11yResume”.

Isso pode ser utilizado para chamar quantos scripts com testes personalizados você quiser, que podem inserir seus resultados no array de resultados antes que as dicas sejam renderizadas.

Por exemplo, se você quisesse criar esta dica para sinalizar links colados de e-mails com URLs ofuscadas:

Tip reading "URL is Safe Link Encoded"

Você precisaria:

  1. Adicionar um listener para o evento ed11yRunCustomTests
  2. Encontrar os elementos correspondentes
  3. Definir a mensagem da dica
  4. Disparar o evento “resume” para o Editoria11y renderizar a dica:

Lidando com alertas em conteúdo oculto ou com restrição de tamanho

Muitos componentes interativos (abas, sliders, acordeões) ocultam conteúdo. O painel de informações do Editoria11y inclui botões de próximo/anterior para ir diretamente aos problemas. Se o Editoria11y detectar que a dica de ferramenta do problema está invisível no momento, ele alertará o usuário sobre o problema e destacará o primeiro ancestral visível — por exemplo, a div ao redor de um acordeão.

O ideal é que o seu tema torne esses elementos visíveis antes que a verificação de visibilidade do Editoria11y seja executada, para que tudo funcione como mágica para seus usuários — carrosséis avançam automaticamente e acordeões se abrem sozinhos para exibir o problema.

Para fazer isso quando o painel é aberto pela primeira vez (por exemplo, desdobrando todos os painéis de acordeão com problemas), adicione um listener de evento JS para ed11yPanelOpened, faça um querySelectorAll para os elementos ed11y-element-result relevantes e acione a função que o seu tema usa para revelar essa parte da página.

Aqui está um exemplo baseado em jQuery. Quando o painel abre, ele desativa um menu fixo (para que os elementos não fiquem encobertos) e depois procura por quaisquer elementos ed11y-element-result dentro de itens de acordeão fechados e simula um clique no botão de alternância:

Para revelar conteúdo apenas ao pular para uma dica específica pelo botão “próximo” do painel (por exemplo, em uma aba fechada ou no próximo slide do carrossel), você precisará definir hiddenHandlers com os seletores CSS relevantes e checkVisible como TRUE nos seus parâmetros. Em seguida, adicione um listener de evento para o evento ed11yShowHidden. Ele é disparado quando o Editoria11y reconhece que uma dica está dentro de um contêiner com um dos seletores hiddenHandlers listados nas opções. Este evento JS incluirá o ID da dica que está prestes a ser aberta. O Editoria11y pausará brevemente após disparar esse evento, para dar tempo ao seu JS de tornar o elemento visível.

Aqui está um exemplo de uma implementação da Penn State. Ele procura o elemento correspondente ao ID fornecido, encontra seu contêiner de componente interativo pai e aciona seu evento para ativar o alternador:

Observação final: alguns temas simplesmente não são compatíveis com a verificação de visibilidade — por exemplo, o contêiner <main> tem altura de 0px. Esses sites devem desativar toda a verificação de visibilidade definindo checkVisible como false.