paginas

Home > Servir site e arquivos > Páginas e HTMX 🚧

Páginas com rotas de visão e HTMX

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Vale para a 2.0 · Delphi XE em diante e Lazarus/FPC 3.2 em diante · Nível: intermediário

Em uma frase: o TRALViewModule liga rotas a modelos Mustache: cada rota devolve uma página, e um pedido do HTMX recebe só o pedaço, sem o layout.

Você vai precisar: o pacote RALModuleWebPackage (que agora também requer o RALNetPackage) e um TRALMustacheEngine com TemplateRoot e, de preferência, Layout.

Ligando

uses RALViewModule, RALTemplate, RALHtmx;

Motor := TRALMustacheEngine.Create(Self);
Motor.TemplateRoot := 'modelos';
Motor.Layout := 'layout';

Visoes := TRALViewModule.Create(Self);
Visoes.Server := Servidor;
Visoes.Engine := Motor;
Visoes.ErrorTemplate := 'erro';
Visoes.CreateView('/clientes', 'clientes', {$IFDEF FPC}@{$ENDIF}ListarClientes);

procedure TForm1.ListarClientes(Sender: TObject; ARequest: TRALRequest;
  AResponse: TRALResponse; AContext: TRALViewContext; var ARender: boolean);
begin
  AContext.Add('titulo', 'Clientes').AddOwned('lista', MontarLista);
  // ARender := False quando você respondeu sozinho (redirecionamento, erro)
end;

modelos/clientes.html é renderizado dentro de layout.html. Sem o segundo parâmetro de CreateView, o modelo é o nome da rota sem a barra (index para /).

Propriedades

propriedade
TRALViewModule.Engine	o motor que acha e renderiza os modelos (obrigatório)
ErrorTemplate	modelo usado quando uma visão levanta exceção, com status e message; vazio dá o erro comum do servidor
OnGetContext	enche os dados de toda visão, antes do evento da rota
Routes	as rotas (TRALViewRoute)
TRALViewRoute.Template	modelo da rota; vazio usa o caminho
UseLayout	True (padrão): renderiza dentro do Layout do motor
StatusCode	status da resposta (200)
OnGetContext (rota)	dados desta visão; ARender := False se você já respondeu

TRALViewContext é um TRALTemplateMap: Add liga um nome a um objeto que deve viver até o fim do render; AddOwned entrega o objeto para ser liberado depois dele.

Dados que já vêm em todo render

nome	conteúdo
params	campos da query e do formulário
htmx	True se o pedido veio do HTMX
csrf_token, csrf_field	quando há um TRALCSRFPlugin no servidor
status, message	só no ErrorTemplate

HTMX

Toda visão responde com Vary: HX-Request. Um pedido do HTMX que não é hx-boost nem restauração de histórico recebe a página sem o layout (TRALHtmx.WantsFragment).

A classe TRALHtmx (unit RALHtmx) lê e escreve os cabeçalhos HX-*:

pedido
Info(ARequest)	record com IsHtmx, Boosted, HistoryRestore, CurrentURL, Target, Trigger, TriggerName, Prompt
IsHtmx, WantsFragment	atalhos

resposta (antes do primeiro Send)	cabeçalho
TriggerEvent, TriggerAfterSwap, TriggerAfterSettle	HX-Trigger, -After-Swap, -After-Settle (chamar de novo acrescenta eventos; detalhe em JSON)
PushUrl, ReplaceUrl	HX-Push-Url, HX-Replace-Url
Redirect, Refresh, Location	HX-Redirect, HX-Refresh, HX-Location
Retarget, Reswap, Reselect	HX-Retarget, HX-Reswap, HX-Reselect

TRALHtmx.TriggerEvent(AResponse, 'cliente-salvo', '{"id":42}');
TRALHtmx.Retarget(AResponse, '#lista');
TRALHtmx.Reswap(AResponse, 'outerHTML');

Erros comuns

o que acontece	causa	o que fazer
exceção "sem Engine"	Engine não ligado	ligue o motor
o fragmento vem com layout	pedido hx-boost ou restauração de histórico	é o esperado: o body inteiro é trocado
cache serve o fragmento na página cheia	falta Vary: HX-Request em respostas suas	as visões já enviam; em rotas comuns, envie você
o modelo não é renderizado	ARender := False no evento	só use quando respondeu por conta própria
cabeçalho HX-* ignorado	posto depois do primeiro Send	ponha antes

Veja também

• Templates (Mustache) · Proteção CSRF · Sessões
• Servir site e arquivos