pagetop-website/doc/v0.6/es/src/how-to/components.md
Manuel Cillero 4e007feec8 📝 Doc cron, mail queue, CSRF and flash messages
Add the scheduled tasks guide, environment variable overrides, the
[mail] and [cron] references, CSRF protection without tokens, flash
messages after redirects and the username policies of pagetop-user.
Update the framework comparison with Poem and Topcoat.
2026-11-02 14:46:28 +01:00

6.6 KiB

Usar componentes

Objetivo: construir la interfaz con los componentes que trae PageTop: crearlos, configurarlos, anidarlos y ajustar sus clases y atributos sin tocar su código.

Un componente es una pieza de interfaz con su propio HTML (y, si los necesita, sus estilos y scripts). Se crea con un constructor, se configura con métodos with_*() encadenados y se añade a una página o a otro componente.

# use pagetop::prelude::*;
async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
    Page::new(request)
        .with_child(
            Block::new()
                .with_title(Lc::n("What's new"))
                .with_child(Html::with(|_| html! { p { "Version 2 is here." } }))
                .with_child(Button::anchor(Lc::n("Download"), "/downloads")),
        )
        .render()
        .await
}

Los componentes no se pintan al crearlos, sino al renderizar la página. Por eso pueden adaptarse al idioma de cada visitante, al tema activo o al usuario conectado.

El catálogo básico

PageTop trae un conjunto de componentes que funcionan con cualquier tema. La lista completa, con sus constructores, está en el catálogo de componentes.

Componente Para qué sirve
Html Marcado puntual con html!
Container Agrupa componentes en un <div>, <section>, <header>...
Block Bloque con título y contenido
Intro Portada de bienvenida con título, eslogan y botón
Button Botones y enlaces con aspecto de botón
Badge Etiquetas pequeñas de estado
Image Imágenes, también responsive
Brand Logotipo y nombre del sitio
Breadcrumb Migas de pan
Messages Avisos al usuario
Dialog Ventanas de diálogo
Flex, Grid Maquetación
Nav, Navbar, Dropdown Navegación
Form y sus campos Formularios
Table, Pager Tablas y paginación
PoweredBy Pie con el crédito «Funciona con PageTop»

Contenedores

Container agrupa varios componentes. Elige la etiqueta con el constructor:

# use pagetop::prelude::*;
# fn f() -> Container {
Container::section()
    .with_id("team")
    .with_child(Html::with(|_| html! { h2 { "The team" } }))
    .with_child(Block::new().with_title(Lc::n("Ana")))
    .with_child(Block::new().with_title(Lc::n("Luke")))
# }

Container::new() genera un <div>; también están header(), main(), section(), article() y footer().

Botones

# use pagetop::prelude::*;
# fn f() -> Vec<Button> { vec![
// A link that looks like a button.
Button::anchor(Lc::n("See the catalog"), "/catalog"),
// A form submit button, with style and intent.
Button::submit(Lc::n("Save"))
    .with_style(button::Style::Solid(Intent::Success))
    .with_size(button::Size::Large),
// An outline button, disabled.
Button::plain(Lc::n("Delete"))
    .with_style(button::Style::Outline(Intent::Severe))
    .with_disabled(true),
# ] }

Intenciones

Muchos componentes reciben una Intent: el significado del color, no el color. El tema decide cómo se ve cada una.

Intent Significado
Primary Acción principal
Neutral Sin énfasis
Info Información
Success Éxito o confirmación
Warning Advertencia
Severe Error o acción peligrosa
# use pagetop::prelude::*;
# fn f() -> Vec<Badge> { vec![
Badge::success(Lc::n("Active")),
Badge::warning(Lc::n("Pending")),
Badge::neutral(Lc::n("Archived")),
# ] }

Imágenes

# use pagetop::prelude::*;
# fn f() -> Image {
Image::with(image::Source::responsive("/static/img/cover.jpg"))
    .with_alternative(Lc::n("View of the harbour at dawn"))
# }

El origen (image::Source) decide cómo se muestra: plain() a su tamaño, responsive() ajustada al ancho disponible y thumbnail() como miniatura.

Identificadores, clases y estilos

Todos los componentes aceptan with_id() y with_prop(). Con PropsOp añades clases, atributos o estilos sin tocar el componente:

# use pagetop::prelude::*;
# fn f() -> Block {
Block::new()
    .with_id("featured")
    .with_prop(PropsOp::add_classes("block-highlight shadow"))
    .with_prop(PropsOp::set("data-section", "home"))
    .with_prop(PropsOp::add_style("border-radius", "8px"))
# }

Para márgenes y rellenos hay tipos propios, Margin y Padding, con unidades tipadas:

# use pagetop::prelude::*;
# fn f() -> Block {
Block::new()
    .with_prop(Margin::new().with_bottom(UnitValue::RelRem(2.0)))
    .with_prop(Padding::new().with_all(UnitValue::Px(16)))
# }

Mensajes al usuario

Page acumula avisos en su contexto, y la región de contenido empieza siempre por un componente Messages que los muestra. Basta con añadirlos:

# use pagetop::prelude::*;
async fn saved(request: HttpRequest) -> Result<Markup, ErrorPage> {
    let mut page = Page::new(request);
    page.context()
        .push_message(MessageLevel::Info, Lc::n("Your changes have been saved."));
    page.render().await
}

Ese Messages se renderiza el último, cuando ya está hecho el resto de la página, así que recoge también los avisos que añadan los componentes al renderizarse, aunque se muestre al principio. Cada aviso aparece una sola vez: añade tu propio Messages::new() sólo para mostrarlos en otro lugar, por ejemplo justo antes de un formulario, o en un fragmento de HTMX, que no tiene página.

Para avisar en la página a la que rediriges, añade el mensaje a la respuesta con with_message() (ver Crear y procesar formularios).

Una portada en un minuto

Intro monta una página de presentación con un solo componente:

# use pagetop::prelude::*;
async fn landing(request: HttpRequest) -> Result<Markup, ErrorPage> {
    Page::new(request)
        .with_child(
            Intro::custom()
                .with_title(Lc::n("Urban Garden"))
                .with_slogan(Lc::n("Grow your city"))
                .with_button(Some((Lc::n("Start here"), Route::from("/guide"))))
                .with_child(
                    Block::new()
                        .with_title(Lc::n("What is it?"))
                        .with_child(Html::with(|_| html! { p { "A network of community gardens." } })),
                ),
        )
        .render()
        .await
}

Siguiente