Adapt the guides to the current PageTop API: Routes with the access of each route, Layers, StaticFiles and the administration panel in the core, with pagetop-admin reduced to the settings forms. Add the "Connect your own authentication" guide, the mail test page and the admin_path setting, and explain route access in the architecture page. Mount the books with their access through pagetop-mdbook.
6.3 KiB
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 y comprueba la versión:
rustc --version
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
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:
[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:
use pagetop::prelude::*;
#[pagetop::main]
async fn main() -> std::io::Result<()> {
Application::new().await.run().await
}
Y ejecútalo:
cargo run
La primera compilación tarda unos minutos; las siguientes, segundos. Cuando termine, verás algo así:
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:
use pagetop::prelude::*;
struct HelloPageTop;
#[async_trait]
impl Extension for HelloPageTop {
fn configure_router(&self, routes: Routes) -> Routes {
routes.public_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:
HelloPageTopes una extensión: un struct vacío que implementaExtension. Todos sus métodos son opcionales; aquí sólo usa uno.configure_router()registra la ruta/y la asocia al handlerhome.homerecibe la petición, construye unaPage, 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.Application::prepare()arranca la aplicación conHelloPageTopcomo 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!.
5. Una ruta con parámetros
Las rutas pueden capturar segmentos de la URL. Añade una segunda ruta:
use pagetop::prelude::*;
struct HelloPageTop;
#[async_trait]
impl Extension for HelloPageTop {
fn configure_router(&self, routes: Routes) -> Routes {
routes
.public_route("/", web::get(home))
.public_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:
[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:
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.tomlque cambia la aplicación sin recompilar.
Siguiente
- Recorrido por PageTop: componentes, formularios, traducciones y pruebas en un solo paseo.
- Tareas del huerto con HTMX, si prefieres ir directo a la interactividad.
- Arquitectura: del arranque a la respuesta, para entender qué
hace
Application::prepare()por dentro.