✨ 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
131
doc/v0.6/es/src/explanation/architecture.md
Normal file
131
doc/v0.6/es/src/explanation/architecture.md
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
# Arquitectura: del arranque a la respuesta
|
||||
|
||||
Una aplicación PageTop vive dos momentos distintos: el **arranque**, que ocurre una vez y prepara
|
||||
todo, y la **petición**, que ocurre miles de veces y debe ser rápida. Entender qué pasa en cada uno
|
||||
explica casi todas las decisiones de diseño de PageTop.
|
||||
|
||||
## Un árbol de extensiones
|
||||
|
||||
Una aplicación es un **árbol de extensiones**. En la raíz está la tuya; de ella cuelgan las que
|
||||
declara como dependencias, y de esas, las suyas:
|
||||
|
||||
```text
|
||||
MyApp <- root extension
|
||||
├── Bootsier <- theme
|
||||
├── User <- accounts and permissions
|
||||
│ ├── Admin
|
||||
│ ├── SeaORM <- database
|
||||
│ └── Htmx
|
||||
└── Blog <- your feature
|
||||
└── SeaORM <- the same one: each extension is registered once
|
||||
```
|
||||
|
||||
Este árbol es independiente de las dependencias de `Cargo.toml`: Cargo decide qué se **compila**;
|
||||
`dependencies()` decide qué se **activa** y en qué orden. Una extensión compilada pero que nadie
|
||||
declara no registra rutas ni ajustes.
|
||||
|
||||
Separar la extensión raíz en `src/lib.rs` y dejar `src/main.rs` con lo mínimo permite usar la
|
||||
aplicación como biblioteca, por ejemplo desde las pruebas:
|
||||
|
||||
```text
|
||||
my-app/
|
||||
├── Cargo.toml
|
||||
├── config/
|
||||
│ ├── common.toml <- common settings
|
||||
│ └── local.toml <- local settings (not versioned)
|
||||
└── src/
|
||||
├── lib.rs <- root extension
|
||||
├── main.rs <- startup
|
||||
└── locale/ <- translations
|
||||
├── en-US/
|
||||
└── es-ES/
|
||||
```
|
||||
|
||||
## El arranque
|
||||
|
||||
`Application::prepare()` sigue siempre los mismos pasos:
|
||||
|
||||
```text
|
||||
Application::prepare(&MyApp)
|
||||
1. banner and traces [log] settles how much is traced and where
|
||||
2. language and time zone the defaults of [app]
|
||||
3. register extensions walks the tree: dependencies first, each one once
|
||||
4. load settings every settings() section, validated
|
||||
5. default theme the one in [app] theme, or Basic with a warning
|
||||
6. register actions every actions(), sorted by weight
|
||||
7. initialize extensions every initialize(), dependencies first
|
||||
|
|
||||
v
|
||||
.run()
|
||||
8. build the server routes + middleware + static files
|
||||
9. serve requests until Ctrl+C or SIGTERM
|
||||
```
|
||||
|
||||
Dos consecuencias importantes:
|
||||
|
||||
- **Lo que falla, falla al arrancar.** Una clave mal escrita, un valor no válido, una base de datos
|
||||
que no responde o una migración rota detienen la aplicación antes de servir una sola petición,
|
||||
con un mensaje que explica la causa. Nunca hay una aplicación a medias en producción.
|
||||
- **Lo costoso se hace una vez.** Las traducciones, los ajustes, las acciones y los recursos
|
||||
estáticos se cargan o se registran al arrancar; en cada petición sólo se consultan.
|
||||
|
||||
## La petición
|
||||
|
||||
Cuando llega una petición, recorre las capas que construyó `run()`:
|
||||
|
||||
```text
|
||||
request
|
||||
|
|
||||
v
|
||||
+------------------------------------------------------------+
|
||||
| static files (/static, /htmx...) -> served directly, |
|
||||
| without middleware |
|
||||
+------------------------------------------------------------+
|
||||
| middleware of the extensions (session, current user...) |
|
||||
| +------------------------------------------------------+ |
|
||||
| | router -> your handler | |
|
||||
| | Page::new(request) builds the Context: | |
|
||||
| | language, theme, user, zone | |
|
||||
| | .with_child(...) adds components, not HTML | |
|
||||
| | .render() the theme lays out the page | |
|
||||
| +------------------------------------------------------+ |
|
||||
+------------------------------------------------------------+
|
||||
|
|
||||
v
|
||||
response (complete HTML, or a fragment for HTMX)
|
||||
```
|
||||
|
||||
- Los **archivos estáticos** se registran después del *middleware*, así que no pasan por él:
|
||||
servir una hoja de estilos no resuelve sesiones ni consulta la base de datos.
|
||||
- El **middleware** de cada extensión (`configure_middleware()`) envuelve las rutas de **todas**
|
||||
las extensiones. Así, `pagetop-user` resuelve la sesión una vez y cualquier ruta sabe quién pide.
|
||||
- El ***handler*** es un *handler* de Axum normal. `Page::new(request)` crea el **contexto** de la
|
||||
petición, que viajará por todos los componentes: el idioma negociado, el tema, el usuario, la
|
||||
zona horaria, los recursos y los mensajes.
|
||||
|
||||
Qué pasa dentro de `render()` se explica en [Componentes, temas y renderizado](rendering.md).
|
||||
|
||||
## Sin estado mutable compartido
|
||||
|
||||
Los ajustes son de sólo lectura, las acciones se registran una vez y los componentes globales
|
||||
(`InRegion`) se **clonan** para cada página. Cada petición trabaja con su propio contexto y sus
|
||||
propias copias: lo que un componente cambia al renderizarse no afecta a otras peticiones. El estado
|
||||
que debe compartirse entre peticiones (datos, sesiones) vive en la base de datos o, si es tuyo, en
|
||||
tus propias estructuras.
|
||||
|
||||
## El preludio
|
||||
|
||||
Casi todo lo que necesitas está en un solo `use`:
|
||||
|
||||
```rust
|
||||
use pagetop::prelude::*;
|
||||
```
|
||||
|
||||
Trae los tipos principales (`Extension`, `Page`, `Component`, `Lc`...), los componentes base, las
|
||||
macros (`html!`, `include_locales!`...) y accesos directos a módulos como `web`, `trace`, `util` o
|
||||
`global`. Las extensiones tienen el suyo: `pagetop_htmx::prelude::*`, `pagetop_user::prelude::*`...
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Componentes, temas y renderizado](rendering.md).
|
||||
- [Si vienes de Axum](coming-from-axum.md): qué es igual y qué cambia.
|
||||
Loading…
Add table
Add a link
Reference in a new issue