SWCore / Componentes / AJAX declarativo

AJAX declarativo Componentes

Carrega um fragmento de HTML de outra página, direto por atributo — sem escrever fetch().

O que é

Busca um pedaço de HTML de outra URL (mesma origem) e injeta na página, no clique ou quando o elemento fica visível.

Como funciona

Faz um fetch simples e injeta o HTML retornado no alvo — sw-ajax-extract permite pegar só um pedaço específico da resposta (um seletor CSS dentro do HTML buscado), não a página inteira.

Exemplos

Carregar ao clicar Ao vivo
<button sw-btn="pri" sw-ajax="/fragmento.html" sw-target="#area">Carregar</button>
<div id="area"></div>

<!-- o HTML que voltar é injetado dentro de #area -->
Quando disparar — click, load e hover Ao vivo
hover — passe o mouse
<!-- no clique (padrão) -->
<button sw-ajax="/parte.html" sw-target="#area">Carregar</button>

<!-- assim que a página abre -->
<div sw-ajax="/parte.html" sw-target="#area" sw-ajax-trigger="load"></div>

<!-- quando o mouse passa (busca uma vez só) -->
<a sw-ajax="/preview.html" sw-target="#area" sw-ajax-trigger="hover">Prévia</a>
Pegar só um pedaço da resposta Ao vivo
<!-- a resposta é uma página inteira, mas você só quer o miolo -->
<button sw-ajax="/pagina.html"
        sw-target="#area"
        sw-ajax-extract="#conteudo">Carregar</button>

<!-- sw-ajax-extract é um seletor CSS aplicado no HTML que voltou -->
Abrir num modal ou num painel Ao vivo
<!-- não precisa criar o modal/painel: ele monta e abre na hora -->
<button sw-ajax="/detalhe.html" sw-ajax-target="modal">Ver detalhes</button>
<button sw-ajax="/filtros.html" sw-ajax-target="panel">Filtros</button>

<!-- com sw-ajax-target você NÃO usa sw-target -->
POST, confirmação e transição Ao vivo

Sem demonstração ao vivo — envolve enviar dados de verdade pro servidor. Veja o código ao lado.

<!-- pede confirmação antes (ação destrutiva) -->
<button sw-btn="err"
        sw-ajax="/pedidos/12/excluir"
        sw-ajax-method="POST"
        sw-ajax-confirm="Excluir este pedido? Não dá pra desfazer."
        sw-target="#lista">Excluir</button>

<!-- com transição na troca do conteúdo -->
<button sw-ajax="/parte.html" sw-target="#area"
        sw-ajax-effect="fade-up">Carregar</button>

<!-- acompanhando -->
<script>
  document.addEventListener('sw:ajax:done',  (e) => console.log('chegou'));
  document.addEventListener('sw:ajax:error', () => SW.Alert.err('Falhou'));
</script>
Segurança — o que ele faz por você Ao vivo

Por padrão ele sanitiza o HTML recebido e bloqueia outra origem. Os dois só saem do caminho se você pedir explicitamente.

Use sw-ajax-trusted só quando o HTML for do seu próprio servidor, e sw-ajax-crossorigin só quando a origem externa for de confiança — os dois ampliam a superfície de ataque de XSS.

<!-- padrão seguro: sanitiza e só aceita mesma origem -->
<button sw-ajax="/parte.html" sw-target="#area">Carregar</button>

<!-- pula a sanitização (só pra HTML 100% seu) -->
<button sw-ajax="/parte.html" sw-target="#area" sw-ajax-trusted>…</button>

<!-- libera origem externa -->
<button sw-ajax="https://outro.site/x.html" sw-target="#area"
        sw-ajax-crossorigin>…</button>

Atributos

sw-ajax
o endereço do fragmento (ou sw-ajax-src="#id" pra usar um <template> local, sem rede)
sw-target
seletor de onde o HTML volta a ser injetado
sw-ajax-target
só aceita "panel" ou "modal" — cria e abre um painel/modal na hora, em vez de usar o sw-target
sw-ajax-trigger
quando disparar: click (padrão) \| load \| hover
sw-ajax-method
GET (padrão) \| POST
sw-ajax-extract
seletor pra pegar só um pedaço do HTML que voltou
sw-ajax-effect
transição ao trocar o conteúdo — ex.: "fade-up reveal"
sw-ajax-confirm
texto de confirmação antes de disparar (usa o SW.Alert.confirmar)
sw-ajax-trusted
pula a sanitização do HTML — só pra fonte 100% sua
sw-ajax-crossorigin
libera buscar de outra origem (sem ele, é bloqueado)

Variantes

click
padrão — busca quando o usuário clica
load
busca assim que a página carrega
hover
busca quando o mouse passa por cima (uma vez só)
sw-ajax-target="modal"
o conteúdo abre dentro de um modal criado na hora
sw-ajax-target="panel"
o conteúdo abre num painel lateral criado na hora

Eventos

sw:ajax:start
a busca começou
sw:ajax:done
o conteúdo chegou e foi injetado
sw:ajax:error
a busca falhou

API (JavaScript)

SW.Ajax.load(el)
dispara a busca por código
SW.Ajax.post(el, dados)
envia por POST

Requisitos

Nenhuma.

Limitações — o que ele não faz

  • Outra origem é bloqueada por padrão — libere com sw-ajax-crossorigin e só se confiar na fonte.
  • Ele espera HTML de volta. Se a sua API devolve JSON, o componente certo é o Conteúdo responsivo (sw-content), que monta o HTML a partir de um template.