Instalar e Configurar

Versões pré-configuradas

Instalação personalizada

Para criar a sua própria implementação, descarregue uma cópia local (ou referencie uma versão CDN) de um pacote de idiomas, do ficheiro JS minificado e do ficheiro CSS minificado, e depois crie uma nova instância “Ed11y”.

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

Utilize os ficheiros JavaScript .umd para navegadores e sistemas mais antigos:

Parâmetros

Uma implementação completa só deve ser carregada para editores com sessão iniciada (não vai querer que os visitantes do seu sítio vejam o verificador!), e pode substituir qualquer um dos parâmetros predefinidos.

Note que todos os parâmetros têm valores predefinidos; inclua apenas os que pretende alterar.

Uma implementação muito personalizada poderá ter este aspeto:

As integrações prontas a usar definem frequentemente estas variáveis de forma dinâmica — por exemplo, carregando páginas em modo “assertive” quando foram editadas recentemente, e regressando ao modo “polite” após alguns minutos.

Tematização

Vários parâmetros permitem selecionar um tema, substituir cores e injetar CSS.

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

Eventos JS úteis

Os tematizadores podem associar-se a estes eventos para reagir e modificar a página conforme necessário.

Por ordem típica de ocorrência…

  • ed11yRunCustomTests: emitido quando o objeto Results está pronto para receber resultados personalizados. Note que o parâmetro customTests deve ser definido com o número de funções de teste personalizadas que irá executar (…provavelmente uma…) para que este evento seja emitido. Mais detalhes na secção seguinte.
  • ed11yResults: emitido quando todas as verificações estão concluídas. As integrações API podem agora extrair dados do objeto Ed11y.results.
  • ed11yPanelOpened: emitido se o painel abrir, automaticamente ou manualmente.
  • ed11yShowHidden: fornece um número data-ed11y-result e um booleano viaJump. Apenas emitido se o parâmetro “ed11yShowHidden” estiver definido e um elemento ancestral corresponder a um seletor. Utilizado para revelar alertas em contentores ainda fechados, como acordeões, separadores e carrosséis. Exemplos de utilização na secção seguinte.
  • ed11yPop: fornece o ID de data-ed11y-result, bem como referências aos objetos result e tip. Emitido quando uma dica de contexto aparece, permitindo modificar as dicas em tempo de execução.
  • ed11yShut: fornece o ID de data-ed11y-result. Emitido quando uma dica de contexto fecha.
  • ed11yDismissalUpdate: fornece informação detalhada quando um utilizador dispensa ou restaura um alerta. Utilizado para integrações API. O objeto do evento contém:
    • dismissPage
    • dismissTest
    • dismissKey
    • dismissAction

Exemplos podem ser encontrados nas secções seguintes.

Modificar dicas de contexto

Se apenas pretender modificar o texto de uma dica, os itens nos objetos globais ed11yLang.en (antes de chamar a biblioteca) ou Ed11y.M (depois de chamar a biblioteca) podem ser substituídos diretamente. Por exemplo, no módulo Drupal onde aliámos o pacote de idiomas a Drupal.ed11yLang:

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

Isto aplica-se a qualquer uma das chaves predefinidas no ficheiro de localização ou na tradução específica do idioma ativo.

O módulo Drupal também adiciona hiperligações de edição personalizadas às dicas, utilizando o parâmetro editLinks. Veja “Page editor” e “Layout editor”:

Dica de contexto com hiperligações "Page editor" e "Layout editor" inseridas.

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

O módulo Drupal utiliza depois o evento ed11yPop para mostrar e ocultar dinamicamente a hiperligação 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 emitirá um evento “ed11yRunCustomTests” durante a verificação, e aguardará até 500ms enquanto escuta esse número de eventos “ed11yResume”.

Isto pode ser aproveitado para chamar tantos scripts de testes personalizados quantos desejar, que podem inserir os seus resultados na matriz de resultados antes de as dicas serem desenhadas.

Por exemplo, se quisesse criar esta dica para assinalar hiperligações coladas de mensagens de correio eletrónico com URLs ofuscados:

Dica com o texto "URL is Safe Link Encoded"

Deverá:

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

Lidar com alertas em conteúdo oculto ou com restrições de tamanho

Muitos componentes interativos (separadores, controlos de deslize, acordeões) ocultam conteúdo. O painel de informação do Editoria11y inclui botões de próximo/anterior para saltar diretamente para os problemas. Se o Editoria11y considerar que a dica de contexto do problema está atualmente invisível, alertará o utilizador de que algo está errado e destacará o primeiro ancestral visível — por exemplo, o div em torno de um acordeão.

Idealmente, o seu tema tornará esses elementos visíveis antes de a verificação de visibilidade do Editoria11y ser executada, para que tudo funcione como magia para os seus utilizadores — os carrosséis avançam automaticamente e os acordeões abrem-se automaticamente para mostrar o problema.

Para o fazer quando o painel abre pela primeira vez (por exemplo, expandindo todos os painéis de acordeão com problemas), adicione um listener de eventos JS para ed11yPanelOpened, execute depois 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.

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

Para revelar conteúdo apenas ao saltar para uma dica específica através do botão “seguinte” do painel (por exemplo, num separador fechado ou no próximo diapositivo de carrossel), precisará de definir tanto hiddenHandlers com os seletores CSS relevantes como checkVisible como TRUE nos seus parâmetros. Adicione depois um listener para o evento ed11yShowHidden. Este é emitido quando o Editoria11y reconhece que uma dica está dentro de um contentor com um dos seletores hiddenHandlers listados nas opções. Este evento JS incluirá o ID da dica que está prestes a abrir. O Editoria11y fará uma breve pausa após emitir este evento, para dar tempo ao seu JavaScript de tornar o elemento visível.

Eis um exemplo de uma implementação da Penn State. Procura o elemento correspondente ao ID fornecido, encontra o seu contentor de componente interativo ancestral e aciona o respetivo evento para ativar o seu alternador:

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