pagetop-website/doc/v0.6/es/src/how-to/htmx-setup.md
Manuel Cillero 1a41a456d4 ✨ Serve the PageTop guides with pagetop-mdbook
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.
2026-10-17 08:06:02 +02:00

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 con with_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

  1. Arranca la aplicación y abre http://localhost:8080.
  2. Pulsa el botón: la hora aparece en una etiqueta, sin recargar.
  3. En las herramientas de desarrollo del navegador (pestaña Red), la petición a /time lleva la cabecera HX-Request: true y la respuesta es una sola etiqueta <span>.

Siguiente