✨ 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
206
doc/v0.6/es/src/tutorials/first-app.md
Normal file
206
doc/v0.6/es/src/tutorials/first-app.md
Normal file
|
|
@ -0,0 +1,206 @@
|
|||
# Tu primera aplicación
|
||||
|
||||
En este tutorial pasas de no tener nada instalado a un servidor web propio con dos páginas, una
|
||||
de ellas con parámetros en la URL, y un ajuste que cambias sin recompilar.
|
||||
|
||||
- **Tiempo:** unos 10 minutos (más lo que tarde la primera compilación).
|
||||
- **Necesitas:** conocer lo básico de Rust y tener una terminal a mano.
|
||||
- **Al terminar tendrás:** una aplicación PageTop que entiendes línea a línea.
|
||||
|
||||
## 1. Instala Rust
|
||||
|
||||
PageTop necesita **Rust 1.88** o posterior. Si no lo tienes, instálalo con
|
||||
[rustup](https://rustup.rs) y comprueba la versión:
|
||||
|
||||
```sh
|
||||
rustc --version
|
||||
```
|
||||
|
||||
```text
|
||||
rustc 1.90.0 (1159e78c4 2025-09-14)
|
||||
```
|
||||
|
||||
Cualquier versión igual o superior sirve. Un editor con *rust-analyzer* (VS Code, Zed, RustRover...)
|
||||
te ahorrará muchos viajes a la documentación.
|
||||
|
||||
## 2. Crea el proyecto
|
||||
|
||||
```sh
|
||||
cargo new hello-pagetop
|
||||
cd hello-pagetop
|
||||
```
|
||||
|
||||
Añade PageTop a `Cargo.toml`. Esta guía describe la versión en desarrollo, que se obtiene del
|
||||
repositorio oficial:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop = { git = "https://git.cillero.es/manuelcillero/pagetop" }
|
||||
```
|
||||
|
||||
No necesitas añadir Tokio ni Axum: PageTop ya los trae y los expone a través de su **preludio**,
|
||||
`pagetop::prelude::*`.
|
||||
|
||||
## 3. Arranca el servidor
|
||||
|
||||
Sustituye el contenido de `src/main.rs`:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::new().await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
Y ejecútalo:
|
||||
|
||||
```sh
|
||||
cargo run
|
||||
```
|
||||
|
||||
La primera compilación tarda unos minutos; las siguientes, segundos. Cuando termine, verás algo así:
|
||||
|
||||
```text
|
||||
PageTop App
|
||||
Powered by PageTop 0.5.0
|
||||
|
||||
INFO pagetop::core::extension::all: Loading settings for all extensions
|
||||
INFO pagetop::core::extension::all: Calling application bootstrap
|
||||
```
|
||||
|
||||
En un terminal de 80 columnas o más, el nombre aparece en letras grandes. Abre
|
||||
<http://localhost:8080>: es la página de bienvenida de PageTop. Para el servidor con `Ctrl+C`.
|
||||
|
||||
`Application::new()` arranca una aplicación vacía, útil para comprobar que todo funciona. Para hacer
|
||||
algo propio necesitas una **extensión raíz**.
|
||||
|
||||
## 4. Tu primera página
|
||||
|
||||
Todo en PageTop es una extensión, empezando por tu aplicación. Cambia `src/main.rs`:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
struct HelloPageTop;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for HelloPageTop {
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router.route("/", web::get(home))
|
||||
}
|
||||
}
|
||||
|
||||
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Home"))
|
||||
.with_child(Html::with(|_| html! {
|
||||
h1 { "Hello, PageTop!" }
|
||||
p { "This page is generated by the server." }
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&HelloPageTop).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
Arranca de nuevo y recarga <http://localhost:8080>. Qué está pasando:
|
||||
|
||||
1. `HelloPageTop` es una extensión: un *struct* vacío que implementa `Extension`. Todos sus
|
||||
métodos son opcionales; aquí sólo usa uno.
|
||||
2. `configure_router()` registra la ruta `/` y la asocia al *handler* `home`.
|
||||
3. `home` recibe la petición, construye una `Page`, le pone título y contenido, y la **renderiza**:
|
||||
el tema activo añade el `<head>`, la estructura de la página, los estilos y el pie.
|
||||
4. `Application::prepare()` arranca la aplicación con `HelloPageTop` como **extensión raíz**.
|
||||
|
||||
El contenido se escribe con la macro `html!`: HTML con sintaxis de Rust, comprobado al compilar. Si
|
||||
olvidas cerrar una llave, no compila. La verás a fondo en [Escribir HTML con
|
||||
`html!`](../how-to/html.md).
|
||||
|
||||
## 5. Una ruta con parámetros
|
||||
|
||||
Las rutas pueden capturar segmentos de la URL. Añade una segunda ruta:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
struct HelloPageTop;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for HelloPageTop {
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
router
|
||||
.route("/", web::get(home))
|
||||
.route("/hello/{name}", web::get(hello))
|
||||
}
|
||||
}
|
||||
|
||||
# async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
# Page::new(request).render().await
|
||||
# }
|
||||
async fn hello(
|
||||
request: HttpRequest,
|
||||
web::Path(name): web::Path<String>,
|
||||
) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::n("Greeting"))
|
||||
.with_child(Html::with(move |_| html! { h1 { "Hello, " (name) "!" } }))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&HelloPageTop).await.run().await
|
||||
}
|
||||
```
|
||||
|
||||
Visita <http://localhost:8080/hello/Ana>. Ahora prueba
|
||||
<http://localhost:8080/hello/%3Cscript%3E>: verás `<script>` como texto, porque `html!` **escapa**
|
||||
todo lo que insertas. No tienes que acordarte de hacerlo.
|
||||
|
||||
Y una ruta que no existe, como <http://localhost:8080/nope>, responde con una página 404 que
|
||||
mantiene el aspecto del sitio.
|
||||
|
||||
## 6. Cambia un ajuste sin recompilar
|
||||
|
||||
El título de la pestaña dice «PageTop App | Greeting». Ese nombre es un **ajuste** de la
|
||||
aplicación. Crea `config/common.toml`, junto a `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[app]
|
||||
name = "Hello PageTop"
|
||||
```
|
||||
|
||||
Para el servidor y arráncalo con `cargo run`: no se recompila nada, sólo se lee la configuración.
|
||||
La pestaña dice ahora «Hello PageTop | Greeting», y el pie de página también usa el nuevo nombre.
|
||||
|
||||
Prueba a escribir mal la clave (`nmae = ...`): la aplicación no arranca y te dice qué clave no
|
||||
reconoce, y cuáles admite:
|
||||
|
||||
```text
|
||||
Invalid settings in section [app]: unknown field `nmae`, expected one of `name`, `theme`, ...
|
||||
```
|
||||
|
||||
Las erratas en la configuración no pasan desapercibidas.
|
||||
|
||||
## Lo que has construido
|
||||
|
||||
- Un servidor web completo en un solo archivo, sin añadir Tokio ni Axum a mano.
|
||||
- Una **extensión raíz** con dos rutas, una de ellas con parámetros.
|
||||
- Páginas completas que el tema rodea de cabecera, estilos y pie.
|
||||
- HTML comprobado al compilar y escapado automáticamente.
|
||||
- Un ajuste en `config/common.toml` que cambia la aplicación sin recompilar.
|
||||
|
||||
## Siguiente
|
||||
|
||||
- [Recorrido por PageTop](tour.md): componentes, formularios, traducciones y pruebas en un solo
|
||||
paseo.
|
||||
- [Tareas del huerto con HTMX](htmx-tasks.md), si prefieres ir directo a la interactividad.
|
||||
- [Arquitectura: del arranque a la respuesta](../explanation/architecture.md), para entender qué
|
||||
hace `Application::prepare()` por dentro.
|
||||
Loading…
Add table
Add a link
Reference in a new issue