✨ 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.
This commit is contained in:
parent
e41e71cc78
commit
1a41a456d4
80 changed files with 14112 additions and 1218 deletions
68
doc/v0.6/es/src/explanation/htmx.md
Normal file
68
doc/v0.6/es/src/explanation/htmx.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# 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](https://htmx.org)
|
||||
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:
|
||||
|
||||
```text
|
||||
+--> 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](../how-to/htmx-search.md) y de [tablas](../how-to/htmx-tables.md) 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
|
||||
|
||||
- [Tareas del huerto con HTMX](../tutorials/htmx-tasks.md): el enfoque en la práctica.
|
||||
- [HTMX: atributos, cabeceras y respuestas](../reference/htmx.md).
|
||||
Loading…
Add table
Add a link
Reference in a new issue