pagetop-website/doc/v0.6/es/src/how-to/themes.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

5.5 KiB

Crear un tema

Objetivo: elegir el aspecto de la aplicación y, si hace falta, crear un tema propio que herede de otro y cambie sólo lo necesario.

El tema es la piel de la aplicación: maqueta la página por regiones, aporta estilos y scripts, y decide cómo se ve cada componente. Cambiar de tema no obliga a tocar las páginas.

1. Elige un tema

PageTop trae el tema Basic. Hay otros como extensiones:

Tema Crate Estilo
Basic pagetop Sobrio, sin dependencias
Bootsier pagetop-bootsier Bootstrap 5
Aliner pagetop-aliner Muestra la estructura de la página, para pruebas

Para usar uno, declara su extensión como dependencia y selecciónalo en la configuración:

# use pagetop::prelude::*;
pub struct MyApp;

#[async_trait]
impl Extension for MyApp {
    fn dependencies(&self) -> Vec<ExtensionRef> {
        vec![&pagetop_bootsier::Bootsier]
    }
}
[app]
theme = "Bootsier"

Si el tema configurado no está disponible, PageTop usa Basic y avisa al arrancar.

2. Crea un tema

Un tema es una extensión que además implementa Theme. Todos los métodos de Theme tienen implementación por defecto, así que el mínimo es éste:

use pagetop::prelude::*;

pub struct Earth;

#[async_trait]
impl Extension for Earth {
    fn theme(&self) -> Option<ThemeRef> {
        Some(&Self)
    }
}

#[async_trait]
impl Theme for Earth {}

3. Hereda de otro tema

Lo más práctico es partir de un tema existente y cambiar sólo lo necesario. Un tema hijo hereda todo de su padre:

use pagetop::prelude::*;

pub struct Earth;

#[async_trait]
impl Extension for Earth {
    fn dependencies(&self) -> Vec<ExtensionRef> {
        vec![&pagetop_bootsier::Bootsier]
    }

    fn theme(&self) -> Option<ThemeRef> {
        Some(&Self)
    }
}

#[async_trait]
impl Theme for Earth {
    fn parent(&self) -> Option<ThemeRef> {
        Some(&pagetop_bootsier::Bootsier)
    }

    // Adds its own style sheet to every page.
    fn before_render_page_body(&self, page: &mut Page) {
        if let Some(parent) = self.parent() {
            parent.before_render_page_body(page);
        }
        page.alter_assets(StyleSheet::from("/static/css/earth.css").with_weight(10));
    }
}

before_render_page_body() es donde un tema añade sus recursos. Al sobrescribirlo, llama al del padre para no perder los suyos.

No olvides seleccionarlo en la configuración (theme = "Earth") y declararlo como dependencia de la aplicación.

4. Ajusta componentes

setup_component() permite retocar cualquier componente antes de pintarlo. La macro setup_component! lo distingue por tipo:

# use pagetop::prelude::*;
# pub struct Earth;
# #[async_trait]
# impl Extension for Earth {}
#[async_trait]
impl Theme for Earth {
    fn setup_component(&self, component: &mut dyn Component, _cx: &mut Context) {
        setup_component!(component, {
            Button => |button| { button.alter_prop(PropsOp::add_classes("earth-button")); },
            Block  => |block|  { block.alter_prop(PropsOp::add_classes("earth-block")); },
        });
    }
}

5. Reescribe componentes

Para cambiar el HTML entero de un componente, usa render_component() con la macro render_component!. Lo que no captures se pinta como siempre:

# use pagetop::prelude::*;
# pub struct Earth;
# #[async_trait]
# impl Extension for Earth {}
#[async_trait]
impl Theme for Earth {
    async fn render_component(
        &self,
        component: &dyn Component,
        cx: &mut Context,
    ) -> Option<Result<Markup, ComponentError>> {
        render_component!(component, {
            Badge => |badge| Ok(html! {
                span class="earth-label" { (badge.label().using(cx)) }
            }),
        })
    }
}

Como el componente expone sus datos con getters (badge.label()), el tema no depende de sus detalles internos.

Si capturas layout::Region para maquetar la región de contenido a tu manera, incluye al principio Messages::new().with_deferred(true), que es lo que pone PageTop: sin él, los avisos al usuario no se ven. Es también la forma de llevarlos a otro lugar de la página, por ejemplo a la cabecera.

6. Cambia las páginas de error

Las páginas 403, 404 y de error grave se pintan con la plantilla activa, para no perder la navegación. Un tema puede cambiar su contenido:

# use pagetop::prelude::*;
# pub struct Earth;
# #[async_trait]
# impl Extension for Earth {}
#[async_trait]
impl Theme for Earth {
    fn error_404(&self, page: &mut Page) {
        page.alter_title(Lc::n("Not found")).alter_child_in(
            &CoreRegions::Content,
            ChildOp::Prepend(
                Html::with(|_| {
                    html! {
                        h1 { "This page has gone off to plant tomatoes" }
                        p { a href="/" { "Back to home" } }
                    }
                })
                .into(),
            ),
        );
    }
}

Más allá

Un tema también puede definir regiones y plantillas propias, fijar los anchos de los puntos de corte (breakpoint_entry()) o traducir las intenciones a su paleta de colores (intent_color()). La documentación del módulo core::theme en docs.rs recorre los seis pasos para personalizar un tema por completo.

Siguiente