Rebuild the website on the current PageTop API, with Bootsier as its
theme and edition 2024. Add the first Spanish guide (doc/v0.6/es) as an
mdBook book, built in build.rs and served with pagetop-mdbook, and the
/doc/latest/{lang} redirect.
Add `tools/doccheck.sh` to check the links of the guides and to compile,
run and test their examples against PageTop.
Move the configuration to config/common.toml and translate the README
to English.
6.7 KiB
Añadir HTMX a una aplicación
Objetivo: que tus páginas carguen HTMX, que sus elementos pidan fragmentos de HTML al servidor y que tus rutas sepan responderlos.
Si es tu primer contacto con HTMX, el tutorial Tareas del huerto con HTMX lo presenta paso a paso. Esta guía reúne lo esencial para cualquier aplicación.
1. Declara la extensión
Añade pagetop-htmx a Cargo.toml:
[dependencies]
pagetop-htmx = { git = "https://git.cillero.es/manuelcillero/pagetop" }
Y declárala como dependencia de tu extensión:
# use pagetop::prelude::*;
pub struct MyApp;
#[async_trait]
impl Extension for MyApp {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_htmx::Htmx]
}
}
No hace falta nada más: la extensión añade el script de HTMX 2 a todas las páginas, con
defer, y lo sirve desde el propio binario. No hay que descargar nada ni configurar una CDN.
2. Escribe atributos hx-* en html!
Los atributos de HTMX se escriben en html! como cualquier otro:
# use pagetop::prelude::*;
# fn f() -> Html {
Html::with(|_| html! {
button hx-get="/time" hx-target="#time" { "What time is it?" }
span id="time" {}
})
# }
Al pulsar el botón, HTMX hace GET /time y pone la respuesta dentro de #time. Los atributos
principales:
| Atributo | Qué indica | Por defecto |
|---|---|---|
hx-get, hx-post, hx-put, hx-patch, hx-delete |
Método y URL de la petición | - |
hx-trigger |
Qué evento la lanza | click; change en campos; submit en formularios |
hx-target |
Dónde va la respuesta (selector CSS, this, closest tr...) |
El propio elemento |
hx-swap |
Cómo se coloca | innerHTML: sustituye el contenido |
La lista completa está en la referencia de HTMX.
3. Ponlos en componentes con with_prop()
Los componentes no conocen HTMX, pero todos aceptan atributos con with_prop(). El módulo hx de
pagetop-htmx tiene una constante para cada atributo y para sus valores habituales:
# use pagetop::prelude::*;
use pagetop_htmx::prelude::*;
# fn f() -> Button {
Button::plain(Lc::n("What time is it?"))
.with_prop(PropsOp::set(hx::GET, "/time"))
.with_prop(PropsOp::set(hx::TARGET, "#time"))
.with_prop(PropsOp::set(hx::SWAP, hx::swap::INNER_HTML))
# }
Con las constantes, una errata como hx::GTE no compila; escrita como texto, "hx-gte" fallaría
en silencio en el navegador.
4. Responde con un fragmento
Una ruta para HTMX devuelve sólo el trozo de HTML que va en el destino, no una página. Lo más
sencillo es devolver Markup:
# use pagetop::prelude::*;
async fn time() -> Markup {
html! { (Utc::now().format("%H:%M:%S")) " UTC" }
}
Si además necesitas cabeceras de HTMX (cambiar el destino, disparar eventos, redirigir...),
devuelve un HtmxResponse. Lo verás en Dirigir al navegador desde el
servidor:
# use pagetop::prelude::*;
use pagetop_htmx::prelude::*;
async fn time() -> HtmxResponse {
HtmxResponse::new(html! { (Utc::now().format("%H:%M:%S")) " UTC" })
.trigger("timeShown")
}
5. Renderiza componentes en un fragmento
Fuera de una Page, un componente se renderiza con un Context creado a partir de la petición. El
contexto aporta el idioma, el tema y las rutas, así que el fragmento sale igual que dentro de la
página:
# use pagetop::prelude::*;
use pagetop_htmx::prelude::*;
async fn notice(request: HttpRequest) -> HtmxResponse {
let mut cx = Context::new(request);
let mut badge = Badge::success(Lc::n("Saved"));
HtmxResponse::new(badge.render(&mut cx).await)
}
Los recursos de un componente no viajan en un fragmento. Si un componente añade su hoja de estilos o su script al contexto, en una página acaban en el
<head>; en un fragmento suelto no hay<head>donde ponerlos. Asegúrate de que la página que recibe el fragmento ya los carga, por ejemplo usando ese mismo componente en ella o añadiéndolos conwith_assets().
6. Una ruta, dos respuestas
Cuando la misma URL puede pedirse con HTMX (para un fragmento) o directamente (al recargar, desde
un enlace compartido o sin JavaScript), comprueba quién llama con is_htmx():
# use pagetop::prelude::*;
use pagetop_htmx::prelude::*;
async fn plants(request: HttpRequest) -> Response {
let list = html! { ul { li { "Tomato" } li { "Pepper" } } };
if request.is_htmx() {
HtmxResponse::new(list).into_response()
} else {
Page::new(request)
.with_title(Lc::n("Plants"))
.with_child(Html::with(move |_| list.clone()))
.render()
.await
.into_response()
}
}
is_htmx() lee la cabecera HX-Request que HTMX añade a sus peticiones. El trait
HtmxRequestExt también ofrece hx_target(), hx_trigger_id(), is_boosted()... para leer las
demás.
El ejemplo completo
use pagetop::prelude::*;
use pagetop_htmx::prelude::*;
struct Clock;
#[async_trait]
impl Extension for Clock {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_htmx::Htmx]
}
fn configure_router(&self, router: Router) -> Router {
router
.route("/", web::get(home))
.route("/time", web::get(time))
}
}
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
Page::new(request)
.with_title(Lc::n("Clock"))
.with_child(
Button::plain(Lc::n("What time is it?"))
.with_prop(PropsOp::set(hx::GET, "/time"))
.with_prop(PropsOp::set(hx::TARGET, "#time")),
)
.with_child(Html::with(|_| html! { p id="time" { "Not asked yet." } }))
.render()
.await
}
async fn time(request: HttpRequest) -> HtmxResponse {
let mut cx = Context::new(request);
let mut badge = Badge::info(Lc::n(Utc::now().format("%H:%M:%S UTC").to_string()));
HtmxResponse::new(badge.render(&mut cx).await)
}
#[pagetop::main]
async fn main() -> std::io::Result<()> {
Application::prepare(&Clock).await.run().await
}
Comprueba
- Arranca la aplicación y abre http://localhost:8080.
- Pulsa el botón: la hora aparece en una etiqueta, sin recargar.
- En las herramientas de desarrollo del navegador (pestaña Red), la petición a
/timelleva la cabeceraHX-Request: truey la respuesta es una sola etiqueta<span>.
Siguiente
- Cargar contenido bajo demanda: al pulsar, al cargar la página o al hacerse visible.
- Probar rutas y componentes: cómo probar una ruta de HTMX sin navegador.
- HTML por la red: por qué HTMX.