pagetop-website/doc/v0.6/es/src/tutorials/first-app.md
Manuel Cillero 345bd26974 📝 Document route access and custom authentication
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.
2026-11-07 17:24:26 +01:00

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:

  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!.

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.toml que cambia la aplicación sin recompilar.

Siguiente