Como tratar erros com HTMX

Neste artigo você vai aprender a como tratar erros com HTMX, uma ação simples que requer alguns cuidados, vem conferir

Fala galera, beleza?

Antes de seguir com o artigo, não deixe de conferir nosso curso completo de HTMX!

A manipulação eficaz de erros é um componente importante na criação de aplicações web interativas e responsivas.

HTMX oferece uma maneira elegante de melhorar a interação do usuário sem recarregar a página, mas o tratamento de erros pode ser um desafio.

Este artigo explora métodos avançados para exibir mensagens de erro de forma intuitiva usando HTMX, aprimorando a experiência do usuário ao interagir com formulários web e outras solicitações.

Tratamento de Erros com HTMX: Uma Abordagem Detalhada

Configuração Básica

Vamos considerar um cenário comum onde um formulário HTMX é usado para adicionar dados a uma lista:

<form id="form" hx-post="/add/" hx-swap="afterbegin" hx-target="#list" hx-trigger="submit">
    <input type="text" name="a">
    <input type="text" name="b">
    <div id="errors"></div>
    <button type="submit">Enviar</button>
</form>
<div id="list">
    <!-- Itens da lista são adicionados aqui -->
</div>

A questão é: como podemos tratar erros de maneira eficiente e exibir mensagens relevantes na div #errors sem afetar #list?

Solução Avançada

Sugerimos o uso de cabeçalhos de resposta para alterar o comportamento de swap e target baseado em erros de validação, utilizando o evento htmx:beforeOnLoad para manipular respostas de erro específicas, como 422 para erros de validação:

document.body.addEventListener('htmx:beforeOnLoad', function (evt) {
    if (evt.detail.xhr.status === 422) {
        evt.detail.shouldSwap = true;
        evt.detail.isError = false;
    }
});

Adicionalmente, para limpar mensagens de erro após uma submissão bem-sucedida, pode-se utilizar o atributo hx-swap-oob, permitindo uma resposta que inclua a remoção ou adição de conteúdo específico fora do contexto atual.

Extensões HTMX para Tratamento de Erros

A implementação do response-targets em HTMX permite uma manipulação mais refinada de respostas HTTP, especificando elementos de destino diferentes para diferentes códigos de resposta.

Isso é particularmente útil para exibir mensagens de erro ou sucesso em locais específicos da sua página, dependendo do resultado de uma solicitação HTMX.

Exemplo de Implementação do response-targets

Primeiro, é necessário incluir a extensão response-targets na sua página. Isso pode ser feito referenciando o script diretamente de um CDN ou baixando e servindo o arquivo localmente em seu projeto.

<script src="https://unpkg.com/htmx.org/dist/ext/response-targets.js"></script>

Com a extensão incluída, você pode então definir um bloco HTMX que utilize response-targets.

Dentro desse bloco, você especifica diferentes elementos de destino para diferentes códigos de resposta usando atributos hx-target-XXX, onde XXX é o código de status da resposta.

Aqui está um exemplo prático de como isso pode ser feito:

<div hx-ext="response-targets">
    <button hx-post="/path/to/your/endpoint"
            hx-target="#default-target"
            hx-target-200="#success-target"
            hx-target-400="#error-target-400"
            hx-target-500="#error-target-500">
        Submit
    </button>
</div>

<div id="default-target">Aqui será mostrado o conteúdo por padrão.</div>
<div id="success-target" style="display:none;">Sucesso!</div>
<div id="error-target-400" style="display:none;">Erro 400: Requisição inválida.</div>
<div id="error-target-500" style="display:none;">Erro 500: Erro interno do servidor.</div>

Neste exemplo, quando o botão é pressionado e a solicitação é enviada:

• Se a resposta for 200, o conteúdo da resposta será colocado em #success-target.
• Se a resposta for 400, a mensagem de erro será exibida em #error-target-400.
• Se a resposta for 500, a mensagem de erro será mostrada em #error-target-500.
• Para todos os outros códigos de resposta, o conteúdo será colocado em #default-target.

Conclusão

Tratar erros com HTMX não apenas melhora a experiência do usuário, mas também fortalece a robustez das aplicações web.

As técnicas e extensões discutidas proporcionam um controle fino sobre a apresentação de erros e o comportamento da aplicação, tornando HTMX uma ferramenta ainda mais poderosa para desenvolvedores web.

Ao final do artigo, inclua uma chamada à ação, incentivando os leitores a experimentar estas técnicas em seus próprios projetos e a compartilhar suas experiências ou perguntas nos comentários, aumentando assim a interação na página.