pagetop-website/doc/v0.6/es/src/explanation/htmx.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

3.4 KiB

HTML por la red: por qué HTMX

PageTop genera HTML en el servidor. Para la interactividad podría haber elegido un framework de JavaScript que pidiera JSON y pintara la interfaz en el navegador. Elige HTMX porque encaja con todo lo demás: el servidor sigue generando el HTML, y el navegador sólo decide cuándo pedirlo y dónde ponerlo.

Dos formas de hacer una interfaz interactiva

Aplicación de una sola página (SPA) HTMX
El servidor envía JSON HTML
La interfaz se genera en El navegador, con JavaScript El servidor, con los mismos componentes que la página
Estado de la interfaz Duplicado: en el servidor y en el cliente En el servidor
Lo que hay que mantener Dos aplicaciones y la API que las une Una aplicación
Validación En los dos lados En el servidor
Sin JavaScript No funciona Funciona, con recargas completas, si se diseña así

Con HTMX, una ruta que responde a una interacción es una ruta como las demás: recibe la petición, consulta lo que haga falta y devuelve HTML. No hay que diseñar una API, ni serializar, ni mantener en sincronía dos modelos de datos.

Por qué encaja con PageTop

  • Los mismos componentes. El fragmento que devuelve una ruta para HTMX se genera con los mismos componentes, el mismo tema y las mismas traducciones que la página entera. No hay una segunda versión de la interfaz en JavaScript.
  • Los atributos son sólo atributos. Los componentes de PageTop no conocen HTMX. Aceptan atributos con with_prop(), y hx-get es uno más. Por eso HTMX es una extensión opcional, y un componente sirve igual con HTMX o sin él.
  • Lo que se prueba es HTML. Una ruta para HTMX se prueba como cualquier otra: se envía la petición y se comprueba el HTML y las cabeceras de la respuesta. El comportamiento en el navegador lo declaran los atributos, sin lógica propia que probar.
  • Un solo lenguaje. La lógica de la interfaz está en Rust, comprobada por el compilador.

Mejora progresiva

Una página bien hecha con HTMX funciona antes de que HTMX llegue: los enlaces llevan su href y los formularios su action. HTMX intercepta esa navegación y la convierte en una petición parcial, y la ruta responde según quién llame:

                        +--> HX-Request: true  --> only the fragment
GET /plants?q=to  ------+
                        +--> (no header)        --> the whole page

Así, la misma URL sirve para buscar sin recargar, para compartir el resultado y para recargar la página. Las guías de búsqueda y de tablas lo aplican.

Cuándo no es la herramienta adecuada

HTMX resuelve muy bien las interfaces de gestión, los formularios, los listados, los paneles y la mayoría de webs con contenido. No es la mejor opción para:

  • interfaces que deben funcionar sin conexión;
  • interacciones de alta frecuencia en el propio navegador, como un editor gráfico, un juego o arrastrar elementos con respuesta inmediata a cada píxel;
  • aplicaciones donde casi todo ocurre en el cliente y el servidor apenas interviene.

Para esos casos puntuales, nada impide añadir JavaScript propio a una página o a un componente: PageTop lo gestiona como cualquier otro recurso.

Siguiente