AJAX declarativo JavaScript

O que é

Serve para "Ver mais detalhes", "Carregar comentários", abrir uma ficha num modal, trocar o conteúdo de uma área do painel. Você põe sw-ajax="/endereco" no botão e sw-target="#area" dizendo onde o HTML que voltar deve entrar. Pode também abrir o resultado direto num modal ou painel lateral criado na hora, pedir confirmação antes, animar a entrada e empilhar no histórico do navegador (o botão Voltar funciona).

Precisa do JavaScript do SW Core e de um endereço no seu servidor que devolva HTML (texto HTML, não JSON). O script busca o endereço, mostra um "carregando" no destino, limpa o HTML recebido (tira scripts e atributos perigosos) e coloca no lugar. Os componentes SW Core que vierem dentro (abas, modal, estrelas, outro sw-ajax…) já chegam funcionando. Por segurança, só busca no mesmo domínio do site, a não ser que você libere. Também dá para usar um <template> da própria página como fonte (sw-ajax-src), sem ir ao servidor.

Quando usar

• Carregar sob demanda algo pesado ou pouco visto (comentários, ficha técnica, histórico): sw-ajax + sw-target.
• Abrir detalhes num modal ou painel sem montar o modal antes: sw-ajax-target="modal" / "panel".
• Ação perigosa que muda algo no servidor (excluir, arquivar): sw-ajax-method="POST" + sw-ajax-confirm.
• Se o seu servidor devolve JSON, use o Conteúdo via JSON, que monta o HTML a partir de um modelo.

Comece aqui

1. 1

   Coloque o SW Core na página.

   <link rel="stylesheet" href="swcore/swcore.min.css">
   
   <!-- fim do body -->
   <script src="swcore/swcore.min.js"></script>

2. 2

   No servidor, um endereço que devolve só o pedaço de HTML (ex.: /produto/12/detalhes):

   <div class="detalhes">
     <h3>Café especial 500g</h3>
     <p>Torra média, notas de chocolate e caramelo.</p>
   </div>

3. 3

   Na página: o botão diz de onde buscar (sw-ajax) e onde colocar (sw-target). Este exemplo busca de verdade um arquivo deste site.

   Ver detalhes

   <button sw-btn="pri" sw-ajax="/produto/12/detalhes" sw-target="#detalhes">Ver detalhes</button>
   <div id="detalhes"></div>

Todas as variações

Cada quadro abaixo é o componente de verdade, rodando. O código embaixo é exatamente o que está no quadro: copie e cole.

Tabela de opções

Receitas prontas — usos reais

Situações que aparecem em quase todo site. Copie a que servir.

<button sw-btn="out" sw-ajax="/posts/42/comentarios" sw-target="#comentarios">
  Ver comentários (18)
</button>
<section id="comentarios"></section>

<!-- /posts/42/comentarios devolve só o HTML dos comentários -->

<nav>
  <a href="/admin/clientes" sw-ajax="/admin/clientes" sw-target="#tela"
     sw-ajax-extract="#tela" sw-ajax-push>Clientes</a>
  <a href="/admin/pedidos"  sw-ajax="/admin/pedidos"  sw-target="#tela"
     sw-ajax-extract="#tela" sw-ajax-push>Pedidos</a>
</nav>
<main id="tela">…</main>

<!-- cada endereço é uma página completa; sw-ajax-extract pega só o #tela dela.
     sw-ajax-push atualiza a barra de endereço e faz o Voltar funcionar.
     Sem JavaScript, os links continuam funcionando normalmente (href). -->

<meta name="csrf-token" content="<?= $csrf ?>">   <!-- vai sozinho no POST -->

<button sw-btn="err p"
        sw-ajax="/pedidos/1042/excluir"
        sw-ajax-method="POST"
        sw-ajax-confirm="Excluir o pedido #1042? Não dá para desfazer."
        sw-target="#lista-pedidos">Excluir</button>

<div id="lista-pedidos">…</div>
<!-- o servidor exclui e devolve o HTML da lista atualizada -->

<!-- sw-ajax no <form>: dispara no envio (Enter ou botão submit) e manda os campos -->
<form sw-ajax="/orcamento" sw-ajax-method="POST" sw-target="#resposta">
  <input sw-inp name="nome" placeholder="Seu nome" required>
  <button sw-btn="pri" type="submit">Pedir orçamento</button>
</form>
<div id="resposta"></div>

<!-- ou por JavaScript:
     SW.Ajax.post('/orcamento', new FormData(form), '#resposta')
     (dados pode ser FormData ou um objeto, que vai como JSON) -->

const botao = document.querySelector('#ver-detalhes');

botao.addEventListener('sw:ajax:start', (e) => console.log('buscando', e.detail.url));
botao.addEventListener('sw:ajax:done',  () => console.log('chegou e já está na tela'));
botao.addEventListener('sw:ajax:error', (e) => console.log('falhou', e.detail.error));
// em caso de erro ele já mostra um aviso vermelho (SW.Alert) e contorna o destino de vermelho

Eventos

API (JavaScript)

Precisa de quê

• swcore.min.css e swcore.min.js.
• No servidor: um endereço que responda com sucesso (código 200) e Content-Type: text/html (ou text/plain), no mesmo domínio do site.
• Para POST com proteção CSRF: <meta name="csrf-token" content="…"> na página; o token vai no cabeçalho X-CSRF-Token.
• A página precisa ser aberta por um endereço http(s):// — abrindo o arquivo direto do computador (file://) a busca não funciona.

Cuidados — erros comuns

• Servidor devolvendo JSON: dá erro "Tipo de conteúdo não suportado". Este componente quer HTML. Para JSON, use o Conteúdo via JSON.
• Esquecer o destino (sw-target ou sw-ajax-target): o aviso de erro aparece e nada entra na tela.
• Endereço de outro domínio sem sw-ajax-crossorigin: é bloqueado de propósito.
• Esperar que um <script> que veio na resposta rode: ele é removido na limpeza (mesmo com sw-ajax-trusted, script inserido assim não executa). Coloque o JavaScript na página e use os eventos.
• Usar sw-ajax-trusted com conteúdo que o usuário escreveu (comentário, nome): abre espaço para ataque. Deixe a limpeza ligada.
• Num <form> com sw-ajax, o disparo é no envio (Enter ou botão type="submit"). Um botão type="button" não envia — ele só dispara se tiver o próprio sw-ajax.

O que ele não faz

• Não monta HTML a partir de JSON.
• Não guarda em cache: cada clique busca de novo.
• Um botão faz uma busca por vez: cliques repetidos enquanto carrega são ignorados.
• O modal/painel criado por sw-ajax-target não tem título nem botão de fechar próprios — mande-os no HTML da resposta se precisar.
• Com sw-ajax-push, voltar até antes da primeira troca recarrega a página inteira (ele não guarda o conteúdo original).