manuelcillero/pagetop
manuelcillero/pagetop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

✨ (theme): Añade componentes Region y Template

Browse source 
Introduce Region y Template (`base::component::layout`) para componer el
`<body>` de una página, con captura explícita vía `handle_component()`
en lugar de maquetado implícito:

- `RegionName`/`TemplateName` (`core/theme.rs`) como interfaces de
  identidad; `CoreRegion` (`Header`/`Content`/`Footer`) y `CoreTemplate`
  (`Standard`/`Admin`) como catálogo por defecto.
- `ReservedRegion` (`PageTop`/`PageBottom`, en `response/page.rs`) queda
  fuera de `CoreRegion`. `Page::render()` las renderiza siempre,
  envolviendo `Theme::render_page_body()`, con independencia de la
  plantilla o el tema activos.
- Elimina `TemplateSource` en `Context`: la plantilla pasa a ser un
  `TemplateRef` fijo, sin resolución por tema (ese mecanismo nunca llegó
  a implementarse).
- La personalización por tema es por captura (`handle_component()` +
  `downcast_ref()`), no por sustituir qué constante se resuelve.
- Corrige referencias obsoletas a `DefaultRegions` por `CoreRegion`.
- Sustituye `tests/theme_template.rs` (API anterior) por
  `tests/component_template.rs`, que cubre el patrón de captura con el
  API nuevo.
This commit is contained in:
Manuel Cillero 2026-07-26 09:51:27 +02:00
parent e7f2563967
commit 8573aca29e
13 changed files with 560 additions and 391 deletions
Download patch file Download diff file Expand all files Collapse all files

2
examples/navbar-menus.rs
View file

@ -102,7 +102,7 @@ impl Extension for SuperMenu {
)), )),
)); ));
InRegion::Global(&DefaultRegions::Header).add( InRegion::Global(&CoreRegion::Header).add(
bs::Container::new() bs::Container::new()
.with_width(bs::container::Width::FluidMax(UnitValue::RelRem(75.0))) .with_width(bs::container::Width::FluidMax(UnitValue::RelRem(75.0)))
.with_child(navbar_menu), .with_child(navbar_menu),

2
src/base/component.rs
View file

@ -1,5 +1,7 @@
//! Componentes nativos proporcionados por PageTop. //! Componentes nativos proporcionados por PageTop.
pub mod layout;
mod block; mod block;
pub use block::Block; pub use block::Block;

7
src/base/component/layout.rs Normal file
View file

@ -0,0 +1,7 @@
//! Definiciones para la composición de documentos ([`Region`] y [`Template`]).
mod region;
pub use region::Region;
mod template;
pub use template::Template;

111
src/base/component/layout/region.rs Normal file
View file

@ -0,0 +1,111 @@
use crate::prelude::*;
use std::fmt;
/// Componente que renderiza una región del `<body>`.
///
/// No recibe ningún contenido de quien lo construye. Lo obtiene directamente del [`Context`] en el
/// momento de renderizarse (ver [`Context::render_region()`]). Si la región no tiene contenido, no
/// se renderiza nada.
///
/// Si un tema necesita maquetar una región determinada de forma distinta, puede capturar este
/// componente en [`Theme::handle_component()`](crate::core::theme::Theme::handle_component) y hacer
/// [`downcast_ref()`](crate::core::AnyCast::downcast_ref) sobre el [`RegionRef`] que devuelve
/// [`Self::region()`], para compararlo con la variante deseada.
///
/// Como cualquier otro componente, participa también en el despacho de las
/// [acciones de componentes](crate::base::action::component) para que otras extensiones puedan
/// intervenir en su renderizado.
///
/// # Ejemplo
///
/// ```rust,no_run
/// use pagetop::prelude::*;
///
/// struct Sidebar;
///
/// impl RegionName for Sidebar {
/// fn name(&self) -> &'static str {
/// "sidebar"
/// }
///
/// fn label(&self) -> L10n {
/// L10n::n("Sidebar")
/// }
/// }
///
/// let header = layout::Region::header();
/// let sidebar = layout::Region::of(&Sidebar);
/// ```
#[derive(Clone, Getters)]
pub struct Region {
/// Devuelve la región subyacente.
#[getters(copy)]
region: RegionRef,
}
impl fmt::Debug for Region {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Region")
.field("region", &self.region().name())
.finish()
}
}
impl Default for Region {
fn default() -> Self {
Region {
region: &CoreRegion::Content,
}
}
}
#[async_trait]
impl Component for Region {
fn new() -> Self {
Self::default()
}
/// Devuelve el nombre de la región subyacente como identificador del componente.
fn id(&self) -> Option<String> {
Some(self.region().name().to_owned())
}
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
let name = self.region().name();
let content = cx.render_region(self.region()).await;
Ok(html! {
@if !content.is_empty() {
div
id=[self.id()]
class=(util::join!("region region-", name))
role="region"
aria-label=[self.region().label().lookup(cx)]
{
(content)
}
}
})
}
}
impl Region {
/// Define el componente que renderizará [`CoreRegion::Header`].
pub fn header() -> Self {
Region {
region: &CoreRegion::Header,
}
}
/// Define el componente que renderizará [`CoreRegion::Footer`].
pub fn footer() -> Self {
Region {
region: &CoreRegion::Footer,
}
}
/// Define el componente que renderizará la región indicada.
pub fn of(region: RegionRef) -> Self {
Region { region }
}
}

81
src/base/component/layout/template.rs Normal file
View file

@ -0,0 +1,81 @@
use crate::prelude::*;
use std::fmt;
/// Componente que renderiza el cuerpo de una plantilla de regiones.
///
/// La composición por defecto usa el componente [`Region`](crate::base::component::layout::Region)
/// para mostrar, en este orden, las regiones [`CoreRegion::Header`], [`CoreRegion::Content`] y
/// [`CoreRegion::Footer`].
///
/// No incluye las regiones reservadas
/// [`ReservedRegion::PageTop`](crate::response::ReservedRegion::PageTop) y
/// [`ReservedRegion::PageBottom`](crate::response::ReservedRegion::PageBottom) porque el propio
/// [`Page::render()`](crate::response::Page::render) las añade antes y después del resultado de
/// [`Theme::render_page_body()`](crate::core::theme::Theme::render_page_body) para que se
/// rendericen siempre, independientemente de la plantilla que se use.
///
/// Si un tema necesita maquetar una plantilla determinada de forma distinta, puede capturar este
/// componente en [`Theme::handle_component()`](crate::core::theme::Theme::handle_component) y hacer
/// [`downcast_ref()`](crate::core::AnyCast::downcast_ref) sobre el [`TemplateRef`] que devuelve
/// [`Self::template()`], para compararlo con la variante deseada.
///
/// Como cualquier otro componente, participa también en el despacho de las
/// [acciones de componentes](crate::base::action::component) para que otras extensiones puedan
/// intervenir en su renderizado.
#[derive(Clone, Getters)]
pub struct Template {
/// Devuelve la plantilla subyacente.
#[getters(copy)]
template: TemplateRef,
}
impl fmt::Debug for Template {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Template")
.field("template", &self.template().name())
.finish()
}
}
impl Default for Template {
fn default() -> Self {
Template {
template: &CoreTemplate::Standard,
}
}
}
#[async_trait]
impl Component for Template {
fn new() -> Self {
Self::default()
}
/// Devuelve el nombre de la plantilla subyacente como identificador del componente.
fn id(&self) -> Option<String> {
Some(self.template().name().to_owned())
}
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
Ok(html! {
(layout::Region::header().render(cx).await)
(layout::Region::default().render(cx).await)
(layout::Region::footer().render(cx).await)
})
}
}
impl Template {
/// Define el componente que renderizará [`CoreTemplate::Admin`].
pub fn admin() -> Self {
Template {
template: &CoreTemplate::Admin,
}
}
/// Define el componente que renderizará la plantilla indicada.
pub fn of(template: TemplateRef) -> Self {
Template { template }
}
}

2
src/base/theme/basic.rs
View file

@ -25,7 +25,7 @@ impl Theme for Basic {
.with_weight(-99), .with_weight(-99),
)) ))
.alter_child_in( .alter_child_in(
&DefaultRegions::Footer, &CoreRegion::Footer,
ChildOp::AddIfEmpty(PoweredBy::new().into()), ChildOp::AddIfEmpty(PoweredBy::new().into()),
); );
} }

64
src/core/component/context.rs
View file

@ -2,7 +2,8 @@ use crate::auth::CurrentUser;
use crate::core::TypeInfo; use crate::core::TypeInfo;
use crate::core::component::{ChildOp, Component, MessageLevel, StatusMessage}; use crate::core::component::{ChildOp, Component, MessageLevel, StatusMessage};
use crate::core::theme::all::DEFAULT_THEME; use crate::core::theme::all::DEFAULT_THEME;
use crate::core::theme::{ChildrenInRegions, DefaultRegions, RegionRef, TemplateRef, ThemeRef}; use crate::core::theme::{ChildrenInRegions, CoreRegion, CoreTemplate};
use crate::core::theme::{RegionRef, TemplateRef, ThemeRef};
use crate::html::{Assets, Favicon, JavaScript, Preload, StyleSheet}; use crate::html::{Assets, Favicon, JavaScript, Preload, StyleSheet};
use crate::html::{Markup, Props, PropsOp, RoutePath, html}; use crate::html::{Markup, Props, PropsOp, RoutePath, html};
use crate::locale::L10n; use crate::locale::L10n;
@ -77,7 +78,7 @@ pub enum ContextError {
/// fn prepare_context<C: Contextual>(cx: C) -> C { /// fn prepare_context<C: Contextual>(cx: C) -> C {
/// cx.with_langid(&Locale::resolve("es-ES")) /// cx.with_langid(&Locale::resolve("es-ES"))
/// .with_theme(&Aliner) /// .with_theme(&Aliner)
/// .with_template(&DefaultTemplates::Standard) /// .with_template(&CoreTemplate::Standard)
/// .with_assets(AssetsOp::SetFavicon(Some(Favicon::new().with_icon("/favicon.ico")))) /// .with_assets(AssetsOp::SetFavicon(Some(Favicon::new().with_icon("/favicon.ico"))))
/// .with_assets(AssetsOp::AddStyleSheet(StyleSheet::from("/css/app.css"))) /// .with_assets(AssetsOp::AddStyleSheet(StyleSheet::from("/css/app.css")))
/// .with_assets(AssetsOp::AddJavaScript(JavaScript::defer("/js/app.js"))) /// .with_assets(AssetsOp::AddJavaScript(JavaScript::defer("/js/app.js")))
@ -137,7 +138,7 @@ pub trait Contextual: LangId {
/// Añade un componente o aplica una operación [`ChildOp`] en una región específica del /// Añade un componente o aplica una operación [`ChildOp`] en una región específica del
/// documento. /// documento.
#[builder_fn] #[builder_fn]
fn with_child_in(self, region_ref: RegionRef, op: impl Into<ChildOp>) -> Self; fn with_child_in(self, region: RegionRef, op: impl Into<ChildOp>) -> Self;
// **< Contextual GETTERS >********************************************************************* // **< Contextual GETTERS >*********************************************************************
@ -236,28 +237,6 @@ pub trait Contextual: LangId {
fn remove_param(&mut self, key: &'static str) -> bool; fn remove_param(&mut self, key: &'static str) -> bool;
} }
// Cómo obtener la plantilla activa del contexto: la del tema (por defecto o de administración), o
// una fijada explícitamente. Se resuelve contra el tema activo al leer `Context::template()`, no al
// asignarla, para que un cambio de tema posterior con `with_theme()` se refleje automáticamente.
enum TemplateSource {
// Plantilla por defecto.
Default,
// Plantilla de administración del tema activo.
Admin,
// Plantilla fijada explícitamente con `with_template()`.
Explicit(TemplateRef),
}
impl TemplateSource {
fn resolve(&self, theme: ThemeRef) -> TemplateRef {
match self {
Self::Default => theme.default_template(),
Self::Admin => theme.admin_template(),
Self::Explicit(template) => *template,
}
}
}
/// Implementa un **contexto de renderizado** para un documento HTML. /// Implementa un **contexto de renderizado** para un documento HTML.
/// ///
/// Se crea una sola vez por petición usando [`Context::new()`] (típicamente a través de /// Se crea una sola vez por petición usando [`Context::new()`] (típicamente a través de
@ -278,9 +257,8 @@ impl TemplateSource {
/// identificadores HTML únicos por tipo de componente. /// identificadores HTML únicos por tipo de componente.
/// - [`push_message()`](Self::push_message)/[`messages()`](Self::messages) para acumular /// - [`push_message()`](Self::push_message)/[`messages()`](Self::messages) para acumular
/// [`StatusMessage`] que mostrar en algún momento del renderizado. /// [`StatusMessage`] que mostrar en algún momento del renderizado.
/// - [`render_assets()`](Self::render_assets)/[`render_region_named()`](Self::render_region_named), /// - [`render_assets()`](Self::render_assets)/[`render_region()`](Self::render_region), usados
/// usados internamente por [`Page`](crate::response::Page) para producir el HTML final del /// internamente por [`Page`](crate::response::Page) para producir el HTML final del documento.
/// documento.
/// ///
/// # Ejemplos /// # Ejemplos
/// ///
@ -332,7 +310,7 @@ pub struct Context {
locale : RequestLocale, // Idioma asociado a la petición. locale : RequestLocale, // Idioma asociado a la petición.
current_user: CurrentUser, // Identidad del usuario actual. current_user: CurrentUser, // Identidad del usuario actual.
theme : ThemeRef, // Referencia al tema usado para renderizar. theme : ThemeRef, // Referencia al tema usado para renderizar.
template : TemplateSource, // Plantilla usada para renderizar. template : TemplateRef, // Plantilla usada para renderizar.
favicon : Option<Favicon>, // Favicon, si se ha definido. favicon : Option<Favicon>, // Favicon, si se ha definido.
preloads : Assets<Preload>, // Recursos para precarga. preloads : Assets<Preload>, // Recursos para precarga.
stylesheets : Assets<StyleSheet>, // Hojas de estilo CSS. stylesheets : Assets<StyleSheet>, // Hojas de estilo CSS.
@ -364,7 +342,7 @@ impl Context {
locale, locale,
current_user, current_user,
theme : *DEFAULT_THEME, theme : *DEFAULT_THEME,
template : TemplateSource::Default, template : &CoreTemplate::Standard,
favicon : None, favicon : None,
preloads : Assets::<Preload>::new(), preloads : Assets::<Preload>::new(),
stylesheets: Assets::<StyleSheet>::new(), stylesheets: Assets::<StyleSheet>::new(),
@ -386,13 +364,6 @@ impl Context {
.unwrap_or(CurrentUser::Anonymous) .unwrap_or(CurrentUser::Anonymous)
} }
// Fuerza la plantilla de administración del tema activo (usada por `Page::admin()`). Se
// resuelve dinámicamente contra `self.theme`, igual que `TemplateSource::Default`, así que
// sigue reflejando cualquier cambio de tema posterior con `with_theme()`.
pub(crate) fn use_admin_template(&mut self) {
self.template = TemplateSource::Admin;
}
// **< Context RENDER >************************************************************************* // **< Context RENDER >*************************************************************************
/// Renderiza los recursos del contexto. /// Renderiza los recursos del contexto.
@ -426,9 +397,13 @@ impl Context {
} }
/// Renderiza los componentes de una región. /// Renderiza los componentes de una región.
pub async fn render_region_named(&mut self, region_name: &str) -> Markup { ///
/// Combina los componentes registrados para esta región en la petición actual con los
/// prototipos globales añadidos vía [`InRegion`](crate::core::theme::InRegion) (comunes o
/// específicos del tema activo).
pub async fn render_region(&mut self, region: RegionRef) -> Markup {
self.regions self.regions
.assemble_region(self.theme, region_name) .assemble_region(self.theme, region)
.render(self) .render(self)
.await .await
} }
@ -568,7 +543,7 @@ impl Contextual for Context {
#[builder_fn] #[builder_fn]
fn with_template(mut self, template: TemplateRef) -> Self { fn with_template(mut self, template: TemplateRef) -> Self {
self.template = TemplateSource::Explicit(template); self.template = template;
self self
} }
@ -624,14 +599,13 @@ impl Contextual for Context {
#[builder_fn] #[builder_fn]
fn with_child(mut self, op: impl Into<ChildOp>) -> Self { fn with_child(mut self, op: impl Into<ChildOp>) -> Self {
self.regions self.regions.alter_child_in(&CoreRegion::Content, op.into());
.alter_child_in(&DefaultRegions::Content, op.into());
self self
} }
#[builder_fn] #[builder_fn]
fn with_child_in(mut self, region_ref: RegionRef, op: impl Into<ChildOp>) -> Self { fn with_child_in(mut self, region: RegionRef, op: impl Into<ChildOp>) -> Self {
self.regions.alter_child_in(region_ref, op.into()); self.regions.alter_child_in(region, op.into());
self self
} }
@ -650,7 +624,7 @@ impl Contextual for Context {
} }
fn template(&self) -> TemplateRef { fn template(&self) -> TemplateRef {
self.template.resolve(self.theme) self.template
} }
fn param<T: 'static>(&self, key: &'static str) -> Result<&T, ContextError> { fn param<T: 'static>(&self, key: &'static str) -> Result<&T, ContextError> {

249
src/core/theme.rs
View file

@ -1,14 +1,15 @@
//! API para añadir y gestionar nuevos temas. //! API para añadir y gestionar nuevos temas.
//! //!
//! Un tema es la *piel* de la aplicación: define estilos, tipografías, espaciados o comportamientos //! Un tema es la *piel* de la aplicación: define estilos, tipografías, espaciados o comportamientos
//! interactivos. Para ello utiliza plantillas ([`Template`]) que describen cómo maquetar el cuerpo //! interactivos. Usa plantillas ([`Template`](crate::base::component::layout::Template)) para
//! del documento a partir de regiones ([`Region`]). Cada región es un contenedor lógico //! maquetar los contenidos en base a regiones ([`Region`](crate::base::component::layout::Region)).
//! identificado por un nombre para agrupar y renderizar componentes. //! Cada región es un contenedor lógico identificado por un nombre para agrupar y renderizar
//! componentes.
//! //!
//! Una página ([`Page`](crate::response::Page)) es un documento HTML completo. Implementa //! Una página ([`Page`](crate::response::Page)) es un documento HTML completo. Implementa
//! [`Contextual`](crate::core::component::Contextual) para gestionar su propio [`Context`], donde //! [`Contextual`](crate::core::component::Contextual) para gestionar su propio
//! mantiene el tema activo, la plantilla seleccionada y los componentes asociados a cada región a //! [`Context`](crate::core::component::Context), donde mantiene el tema activo, la plantilla
//! renderizar. //! seleccionada y los componentes asociados a cada región a renderizar.
//! //!
//! Además, PageTop permite crear **temas hijo** que refinan el comportamiento de su tema padre. Un //! Además, PageTop permite crear **temas hijo** que refinan el comportamiento de su tema padre. Un
//! tema hijo hereda automáticamente todos los métodos del padre y puede sobrescribirlos //! tema hijo hereda automáticamente todos los métodos del padre y puede sobrescribirlos
@ -26,24 +27,34 @@
//! Un tema puede personalizarse en tres pasos, cada uno necesario sólo si lo que ofrece PageTop por //! Un tema puede personalizarse en tres pasos, cada uno necesario sólo si lo que ofrece PageTop por
//! defecto no basta: //! defecto no basta:
//! //!
//! 1. **Definir regiones propias**. Por defecto PageTop define [`DefaultRegions`], con tres //! 1. **Definir regiones nuevas**. Por defecto, PageTop define [`CoreRegion`] (`Header`, `Content`,
//! regiones (`Header`, `Content` y `Footer`) que usan la implementación por defecto de //! `Footer`) como las regiones de plantilla que se asumen siempre disponibles, y
//! [`Region::render()`]. Un tema puede definir un *enum* propio que implemente [`Region`] para //! [`ReservedRegion`](crate::response::ReservedRegion) (`PageTop`, `PageBottom`) como las
//! exponer sus propias regiones (por ejemplo, una barra lateral) o para cambiar cómo se muestra //! regiones reservadas que se renderizan al margen de cualquier plantilla. Un tema puede definir
//! el contenido de una región ya existente (identificada por su nombre). //! su propio *enum* que implemente [`RegionName`] para **añadir** nuevas regiones que PageTop no
//! 2. **Definir plantillas propias**. Por defecto existe [`DefaultTemplates`], con dos plantillas //! ofrece (por ejemplo, una barra lateral). No es necesario redefinir las de [`CoreRegion`] ni
//! (`Standard` y `Admin`) que usan la implementación por defecto de [`Template::render()`] para //! las de [`ReservedRegion`](crate::response::ReservedRegion), que ya existen y se asume que
//! renderizar [`DefaultRegions::Header`], [`DefaultRegions::Content`] y //! cualquier tema respeta.
//! [`DefaultRegions::Footer`], en este orden. Un tema puede definir un *enum* propio que //! 2. **Definir plantillas nuevas**. Por defecto existe [`CoreTemplate`], con las plantillas
//! implemente [`Template`] para crear nuevas plantillas, maquetar las regiones de otra forma, //! `Standard` y `Admin` que usan `Page::new()` y `Page::admin()` respectivamente, y que son
//! cambiar su orden o envolverlas en contenedores adicionales. //! siempre las mismas: no hay un método de `Theme` para elegir una plantilla predeterminada
//! 3. **Elegir las plantillas predeterminadas**. Por un lado, la plantilla por defecto vía //! distinta. Un tema puede definir su propio *enum* que implemente [`TemplateName`] para
//! [`Theme::default_template()`] y, por otro, la plantilla para las páginas de administración, //! **añadir** plantillas que PageTop no ofrece, y no para redefinir `Standard`/`Admin`.
//! [`Theme::admin_template()`]. De esta forma, las páginas creadas con `Page::new()` usarán //! 3. **Cambiar cómo se renderiza** una región, una plantilla o un componente ya existente, se hace
//! automáticamente la plantilla `default_template()` del tema activo, y las páginas creadas con //! capturando el componente ([`Region`](crate::base::component::layout::Region) o
//! `Page::admin()` usarán la de `admin_template()`, sin tener que llamar manualmente a //! [`Template`](crate::base::component::layout::Template), o el componente que sea) en
//! [`with_template()`](crate::core::component::Contextual::with_template). Un tema que no //! [`Theme::handle_component()`]. En el caso de regiones y plantillas, para distinguir *qué*
//! sobrescriba estos métodos sigue usando las plantillas por defecto de PageTop. //! región o plantilla concreta envuelve el componente, sin comparar cadenas, basta con encadenar
//! el *getter* correspondiente
//! ([`Region::region()`](crate::base::component::layout::Region::region) o
//! [`Template::template()`](crate::base::component::layout::Template::template)) con
//! [`AnyCast::downcast_ref()`](crate::core::AnyCast::downcast_ref) hacia el tipo concreto (por
//! ejemplo, [`CoreTemplate`] o el propio *enum* del tema). `pagetop-bootsier` hace exactamente
//! esto para maquetar `Standard` y `Admin` de forma distinta, sin necesitar sus propias
//! variantes de plantilla.
//!
//! Para forzar una plantilla completamente distinta en una página concreta, se puede llamar
//! manualmente a [`with_template()`](crate::core::component::Contextual::with_template).
//! //!
//! Las páginas de error (403, 404, y otros errores fatales) no tienen una plantilla propia: se //! Las páginas de error (403, 404, y otros errores fatales) no tienen una plantilla propia: se
//! renderizan con la plantilla ya activa en la página, para que el usuario no pierda el contexto de //! renderizan con la plantilla ya activa en la página, para que el usuario no pierda el contexto de
@ -51,9 +62,8 @@
//! [`Theme::error_403()`], [`Theme::error_404()`] o [`Theme::error_fatal()`], sin necesidad de una //! [`Theme::error_403()`], [`Theme::error_404()`] o [`Theme::error_fatal()`], sin necesidad de una
//! plantilla distinta. //! plantilla distinta.
//! //!
//! El resto del comportamiento de un tema (renderizado del `<head>`, o intervención en el //! El resto del comportamiento de un tema (por ejemplo, el renderizado del `<head>`) se sobrescribe
//! renderizado de componentes concretos con [`Theme::handle_component()`]) se sobrescribe de forma //! de forma independiente de estos tres pasos y no es necesario para tener un tema funcional.
//! independiente de estos tres pasos y no es necesario para tener un tema funcional.
//! //!
//! # Componentes que se procesan en todas las páginas //! # Componentes que se procesan en todas las páginas
//! //!
@ -69,7 +79,7 @@
//! //!
//! ```rust,no_run //! ```rust,no_run
//! # use pagetop::prelude::*; //! # use pagetop::prelude::*;
//! InRegion::Global(&DefaultRegions::Footer).add(PoweredBy::new()); //! InRegion::Global(&CoreRegion::Footer).add(PoweredBy::new());
//! ``` //! ```
//! //!
//! El componente se guarda como **prototipo**: cada página recibe un clon fresco en el momento del //! El componente se guarda como **prototipo**: cada página recibe un clon fresco en el momento del
@ -82,90 +92,66 @@
//! sola vez y que decida por sí mismo cuándo mostrarse, por ejemplo según la ruta de la petición o //! sola vez y que decida por sí mismo cuándo mostrarse, por ejemplo según la ruta de la petición o
//! si el usuario actual está autenticado. //! si el usuario actual está autenticado.
use crate::async_trait; use crate::AutoDefault;
use crate::core::component::Context; use crate::core::AnyInfo;
use crate::html::{Markup, html};
use crate::locale::L10n; use crate::locale::L10n;
use crate::{AutoDefault, util};
// **< Region >************************************************************************************* // **< RegionName >*********************************************************************************
/// Interfaz común para las regiones lógicas de un documento. /// Interfaz común para las regiones lógicas del `<body>`.
/// ///
/// Una `Region` representa un contenedor lógico identificado por un nombre de región. Su contenido /// Una `RegionName` representa un contenedor lógico identificado por un nombre de región. Su
/// se obtiene del [`Context`], donde los componentes suelen registrarse usando implementaciones de /// contenido se obtiene del [`Context`](crate::core::component::Context), donde los componentes
/// métodos como [`Contextual::with_child_in()`](crate::core::component::Contextual::with_child_in). /// suelen registrarse usando implementaciones de métodos como
/// [`Contextual::with_child_in()`](crate::core::component::Contextual::with_child_in).
/// ///
/// El contenido de una región viene determinado únicamente por su nombre, no por su tipo. Distintas /// El contenido de una región viene determinado únicamente por su nombre, no por su tipo. Distintas
/// implementaciones de [`Region`] que devuelvan el mismo nombre compartirán el mismo conjunto de /// implementaciones de [`RegionName`] que devuelvan el mismo nombre comparten el mismo conjunto de
/// componentes registrados en el [`Context`], aunque cada región puede renderizar ese contenido de /// componentes registrados en el [`Context`](crate::core::component::Context). Un *enum* propio que
/// forma diferente. Por ejemplo, [`DefaultRegions::Header`] y `BootsierRegions::Header` mostrarían /// implemente [`RegionName`] está pensado para **añadir** regiones que PageTop no ofrece (con un
/// los mismos componentes si ambas devuelven el nombre `"header"`, pero podrían maquetarse de /// nombre propio que no colisione con los de [`CoreRegion`] o
/// manera distinta. /// [`ReservedRegion`](crate::response::ReservedRegion)).
/// ///
/// El tema decide qué regiones mostrar en el cuerpo del documento, normalmente usando una plantilla /// El tema decide qué regiones mostrar en el `<body>`, normalmente usando una plantilla
/// ([`Template`]) al renderizar la página ([`Page`](crate::response::Page)). /// ([`TemplateName`]) al renderizar la página ([`Page`](crate::response::Page)).
#[async_trait] ///
pub trait Region: Send + Sync { /// Requiere [`AnyInfo`] para que un [`RegionRef`] pueda recuperarse mediante
/// [`AnyCast::downcast_ref()`](crate::core::AnyCast::downcast_ref) hacia su tipo concreto (por
/// ejemplo, para que un tema distinga en
/// [`Theme::handle_component()`](crate::core::theme::Theme::handle_component) qué variante
/// concreta está renderizando el componente [`Region`](crate::base::component::layout::Region)).
pub trait RegionName: Send + Sync + AnyInfo {
/// Devuelve el nombre de la región. /// Devuelve el nombre de la región.
/// ///
/// Este nombre es el identificador lógico de la región y se usa como clave en el [`Context`] /// Este nombre es el identificador lógico de la región y se usa como clave en el
/// para recuperar y renderizar el contenido registrado bajo ese nombre. Cualquier /// [`Context`](crate::core::component::Context) para recuperar y renderizar el contenido
/// implementación de [`Region`] que devuelva el mismo nombre compartirá el mismo conjunto de /// registrado bajo ese nombre. Cualquier implementación de [`RegionName`] que devuelva el mismo
/// componentes. /// nombre compartirá el mismo conjunto de componentes.
///
/// En la implementación predeterminada de [`Self::render()`] también se utiliza para construir
/// las clases del contenedor de la región (`"region region-<name>"`).
fn name(&self) -> &'static str; fn name(&self) -> &'static str;
/// Devuelve un *texto localizado* como etiqueta de accesibilidad asociada a la región. /// Devuelve un *texto localizado* como etiqueta de accesibilidad asociada a la región.
/// ///
/// En la implementación predeterminada de [`Self::render()`], este valor se usa como /// En la implementación predeterminada de [`Region`](crate::base::component::layout::Region),
/// `aria-label` del contenedor de la región. /// este valor se usa como `aria-label` del contenedor de la región.
fn label(&self) -> L10n; fn label(&self) -> L10n;
/// Renderiza el contenedor de la región.
///
/// Por defecto, recupera del [`Context`] el contenido de la región y, si no está vacío, lo
/// envuelve en un `<div>` con clases `"region region-<name>"` y un `aria-label` basado en el
/// *texto localizado* de la etiqueta asociada a la región:
///
/// ```html
/// <div class="region region-<name>" role="region" aria-label="<label>">
/// <!-- Componentes de la región "name" -->
/// </div>
/// ```
///
/// Se puede sobrescribir este método para modificar la estructura del contenedor, las clases
/// utilizadas o la semántica del marcado generado para cada región.
async fn render(&self, cx: &mut Context) -> Markup {
html! {
@let region = cx.render_region_named(self.name()).await;
@if !region.is_empty() {
div
class=(util::join!("region region-", self.name()))
role="region"
aria-label=[self.label().lookup(cx)]
{
(region)
}
}
}
}
} }
/// Referencia estática a una región. /// Referencia estática a una región.
pub type RegionRef = &'static dyn Region; pub type RegionRef = &'static dyn RegionName;
// **< DefaultRegions >***************************************************************************** // **< CoreRegion >*********************************************************************************
/// Regiones básicas que PageTop proporciona por defecto. /// Regiones básicas que PageTop proporciona por defecto.
/// ///
/// Estas regiones comparten sus nombres (`"header"`, `"content"`, `"footer"`) con cualquier región /// Comparten sus nombres (`"header"`, `"content"`, `"footer"`) con otras regiones que implementen
/// equivalente definida por otros temas, por lo que comparten también el contenido registrado bajo /// [`RegionName`], por lo que comparten también el contenido registrado bajo esos nombres. Por
/// esos nombres. /// defecto, son las regiones usadas por [`Template`](crate::base::component::layout::Template).
///
/// A estas regiones hay que sumar también las regiones internas reservadas por
/// [`ReservedRegion`](crate::response::ReservedRegion) (`"page-top"` y `"page-bottom"`), que
/// [`Page::render()`](crate::response::Page::render) renderiza en cualquier caso.
#[derive(AutoDefault)] #[derive(AutoDefault)]
pub enum DefaultRegions { pub enum CoreRegion {
/// Región estándar para la **cabecera** del documento, de nombre `"header"`. /// Región estándar para la **cabecera** del documento, de nombre `"header"`.
/// ///
/// Suele emplearse para mostrar un logotipo, navegación principal, barras superiores, etc. /// Suele emplearse para mostrar un logotipo, navegación principal, barras superiores, etc.
@ -184,7 +170,7 @@ pub enum DefaultRegions {
Footer, Footer,
} }
impl Region for DefaultRegions { impl RegionName for CoreRegion {
#[inline] #[inline]
fn name(&self) -> &'static str { fn name(&self) -> &'static str {
match self { match self {
@ -204,63 +190,64 @@ impl Region for DefaultRegions {
} }
} }
// **< Template >*********************************************************************************** // **< TemplateName >*******************************************************************************
/// Interfaz común para definir plantillas de contenido. /// Interfaz común para las plantillas lógicas de una página.
/// ///
/// Una `Template` puede proporcionar una o más variantes para decidir la composición del `<body>` /// Representa una variante identificada por un nombre. Un tema puede usar este nombre para decidir
/// de una página ([`Page`](crate::response::Page)). El tema utiliza esta información para /// la composición del cuerpo de una página ([`Page`](crate::response::Page)), es decir, qué
/// determinar qué regiones ([`Region`]) deben renderizarse y en qué orden. /// regiones ([`RegionName`]) renderizar y en qué orden.
#[async_trait] ///
pub trait Template: Send + Sync { /// Requiere [`AnyInfo`] por el mismo motivo que [`RegionName`], para que un [`TemplateRef`] pueda
/// Renderiza el contenido de la plantilla. /// recuperarse mediante [`AnyCast::downcast_ref()`](crate::core::AnyCast::downcast_ref) hacia su
/// /// tipo concreto (por ejemplo, para que un tema distinga en
/// Por defecto, renderiza las regiones básicas de [`DefaultRegions`] en este orden: /// [`Theme::handle_component()`](crate::core::theme::Theme::handle_component) qué variante concreta
/// [`DefaultRegions::Header`], [`DefaultRegions::Content`] y [`DefaultRegions::Footer`]. /// está renderizando el componente [`Template`](crate::base::component::layout::Template)).
/// pub trait TemplateName: Send + Sync + AnyInfo {
/// Se puede sobrescribir este método para: /// Devuelve el nombre de la plantilla.
/// fn name(&self) -> &'static str;
/// - Cambiar el conjunto de regiones que se renderizan según variantes de la plantilla.
/// - Alterar el orden de dichas regiones. /// Devuelve un *texto localizado* como etiqueta descriptiva de la plantilla.
/// - Envolver las regiones en contenedores adicionales. fn label(&self) -> L10n;
/// - Implementar distribuciones específicas (por ejemplo, con barras laterales).
///
/// Este método se invoca normalmente desde [`Theme::render_page_body()`] para generar el
/// contenido del `<body>` de una página según la plantilla devuelta por el contexto de la
/// propia página ([`Contextual::template()`](crate::core::component::Contextual::template())).
async fn render(&self, cx: &mut Context) -> Markup {
html! {
(DefaultRegions::Header.render(cx).await)
(DefaultRegions::Content.render(cx).await)
(DefaultRegions::Footer.render(cx).await)
}
}
} }
/// Referencia estática a una plantilla. /// Referencia estática a una plantilla.
pub type TemplateRef = &'static dyn Template; pub type TemplateRef = &'static dyn TemplateName;
// **< DefaultTemplates >*************************************************************************** // **< CoreTemplate >*******************************************************************************
/// Plantillas que PageTop proporciona por defecto. /// Plantillas que PageTop proporciona por defecto.
#[derive(AutoDefault)] #[derive(AutoDefault)]
pub enum DefaultTemplates { pub enum CoreTemplate {
/// Plantilla predeterminada. /// Plantilla predeterminada, de nombre `"standard"`.
/// ///
/// Utiliza la implementación por defecto de [`Template::render()`] y se emplea cuando no se /// Se emplea cuando no se selecciona ninguna otra plantilla explícitamente.
/// selecciona ninguna otra plantilla explícitamente.
#[default] #[default]
Standard, Standard,
/// Plantilla para la **interfaz de administración**. /// Plantilla para la **interfaz de administración**, de nombre `"admin"`.
/// ///
/// Se utiliza para páginas de administración o paneles de control. Por defecto utiliza la misma /// Se utiliza para páginas de administración o paneles de control.
/// implementación de [`Template::render()`] que [`Self::Standard`].
Admin, Admin,
} }
#[async_trait] impl TemplateName for CoreTemplate {
impl Template for DefaultTemplates {} #[inline]
fn name(&self) -> &'static str {
match self {
Self::Standard => "standard",
Self::Admin => "admin",
}
}
#[inline]
fn label(&self) -> L10n {
match self {
Self::Standard => L10n::l("template-standard"),
Self::Admin => L10n::l("template-admin"),
}
}
}
// **< render_component! >************************************************************************** // **< render_component! >**************************************************************************

85
src/core/theme/definition.rs
View file

@ -1,8 +1,9 @@
use crate::async_trait; use crate::async_trait;
use crate::base::component::{Html, Intro, IntroOpening}; use crate::base::component::{Html, Intro, IntroOpening, layout};
use crate::core::component::{ChildOp, Component, ComponentError, Context, Contextual}; use crate::core::component::{ChildOp, Component, ComponentError, ComponentRender};
use crate::core::component::{Context, Contextual};
use crate::core::extension::Extension; use crate::core::extension::Extension;
use crate::core::theme::{DefaultRegions, DefaultTemplates, TemplateRef}; use crate::core::theme::CoreRegion;
use crate::global; use crate::global;
use crate::html::{Markup, html}; use crate::html::{Markup, html};
use crate::locale::L10n; use crate::locale::L10n;
@ -13,10 +14,10 @@ use crate::web::http::StatusCode;
/// ///
/// Un tema es una [`Extension`](crate::core::extension::Extension) que define el aspecto general de /// Un tema es una [`Extension`](crate::core::extension::Extension) que define el aspecto general de
/// las páginas: cómo se renderiza el `<head>`, cómo se presenta el `<body>` usando plantillas /// las páginas: cómo se renderiza el `<head>`, cómo se presenta el `<body>` usando plantillas
/// ([`Template`](crate::core::theme::Template)) que maquetan regiones /// ([`TemplateName`](crate::core::theme::TemplateName)) que maquetan regiones
/// ([`Region`](crate::core::theme::Region)) y qué contenido mostrar en las páginas de error. El /// ([`RegionName`](crate::core::theme::RegionName)) y qué contenido mostrar en las páginas de
/// contenido de cada región depende del [`Context`](crate::core::component::Context) y de su nombre /// error. El contenido de cada región depende del [`Context`](crate::core::component::Context) y de
/// lógico. /// su nombre lógico.
/// ///
/// Todos los métodos de este *trait* tienen una implementación por defecto, por lo que pueden /// Todos los métodos de este *trait* tienen una implementación por defecto, por lo que pueden
/// sobrescribirse selectivamente para crear nuevos temas con comportamientos distintos a los /// sobrescribirse selectivamente para crear nuevos temas con comportamientos distintos a los
@ -59,34 +60,6 @@ pub trait Theme: Extension + Send + Sync {
None None
} }
/// Devuelve la plantilla ([`Template`](crate::core::theme::Template)) que el propio tema
/// propone como predeterminada.
///
/// Se utiliza al inicializar un [`Context`](crate::core::component::Context) o una página
/// ([`Page`](crate::response::Page)) por si no se elige ninguna otra plantilla con
/// [`Contextual::with_template()`](crate::core::component::Contextual::with_template).
///
/// La implementación por defecto devuelve la plantilla [`DefaultTemplates::Standard`] con una
/// estructura básica para la página. Los temas pueden sobrescribir este método para seleccionar
/// otra plantilla predeterminada o una plantilla propia.
#[inline]
fn default_template(&self) -> TemplateRef {
self.parent()
.map_or(&DefaultTemplates::Standard, |p| p.default_template())
}
/// Devuelve la plantilla ([`Template`](crate::core::theme::Template)) que el tema propone para
/// la interfaz de administración.
///
/// La implementación por defecto devuelve la plantilla [`DefaultTemplates::Admin`] con una
/// estructura básica para la interfaz de administración. Los temas pueden sobrescribir este
/// método para seleccionar otra plantilla predeterminada o una plantilla propia.
#[inline]
fn admin_template(&self) -> TemplateRef {
self.parent()
.map_or(&DefaultTemplates::Admin, |p| p.admin_template())
}
/// Acciones específicas del tema antes de renderizar el `<body>` de la página. /// Acciones específicas del tema antes de renderizar el `<body>` de la página.
/// ///
/// Es un buen lugar para inicializar o ajustar recursos en función del contexto de la página, /// Es un buen lugar para inicializar o ajustar recursos en función del contexto de la página,
@ -107,14 +80,13 @@ pub trait Theme: Extension + Send + Sync {
/// Renderiza el contenido del `<body>` de la página. /// Renderiza el contenido del `<body>` de la página.
/// ///
/// La implementación predeterminada delega en la plantilla asociada a la página, obtenida desde /// La implementación predeterminada delega en la plantilla asociada a la página, obtenida desde
/// su [`Context`](crate::core::component::Context), y llama a /// su [`Context`](crate::core::component::Context), para componer el `<body>` a partir de las
/// [`Template::render()`](crate::core::theme::Template::render) para componer el `<body>` a /// regiones.
/// partir de las regiones.
/// ///
/// Con la configuración por defecto, la plantilla estándar utiliza las regiones /// Con la configuración por defecto, la plantilla estándar utiliza las regiones
/// [`DefaultRegions::Header`](crate::core::theme::DefaultRegions::Header), /// [`CoreRegion::Header`](crate::core::theme::CoreRegion::Header),
/// [`DefaultRegions::Content`](crate::core::theme::DefaultRegions::Content) y /// [`CoreRegion::Content`](crate::core::theme::CoreRegion::Content) y
/// [`DefaultRegions::Footer`](crate::core::theme::DefaultRegions::Footer) en ese orden. /// [`CoreRegion::Footer`](crate::core::theme::CoreRegion::Footer) en ese orden.
/// ///
/// Los temas pueden sobrescribir este método para: /// Los temas pueden sobrescribir este método para:
/// ///
@ -127,7 +99,8 @@ pub trait Theme: Extension + Send + Sync {
if let Some(parent) = self.parent() { if let Some(parent) = self.parent() {
parent.render_page_body(page).await parent.render_page_body(page).await
} else { } else {
page.template().render(page.context()).await let template = page.template();
layout::Template::of(template).render(page.context()).await
} }
} }
@ -247,16 +220,16 @@ pub trait Theme: Extension + Send + Sync {
/// Contenido predefinido para la página de error "*403 - Forbidden*" (acceso denegado). /// Contenido predefinido para la página de error "*403 - Forbidden*" (acceso denegado).
/// ///
/// Normalmente se renderiza con la plantilla predeterminada del tema (por defecto suele ser /// Normalmente se renderiza con la plantilla ya activa en la página (por ejemplo
/// [`DefaultTemplates::Standard`]), para que el usuario no pierda el contexto de navegación del /// [`CoreTemplate::Standard`](crate::core::theme::CoreTemplate::Standard)), para que el usuario
/// sitio. Los temas pueden sobrescribir este método para personalizar completamente el diseño y /// no pierda el contexto de navegación del sitio. Los temas pueden sobrescribir este método
/// el contenido de la página de error. /// para personalizar completamente el diseño y el contenido de la página de error.
fn error_403(&self, page: &mut Page) { fn error_403(&self, page: &mut Page) {
if let Some(parent) = self.parent() { if let Some(parent) = self.parent() {
return parent.error_403(page); return parent.error_403(page);
} }
page.alter_title(L10n::l("error403_title")).alter_child_in( page.alter_title(L10n::l("error403_title")).alter_child_in(
&DefaultRegions::Content, &CoreRegion::Content,
ChildOp::Prepend( ChildOp::Prepend(
Html::with(move |cx| { Html::with(move |cx| {
html! { html! {
@ -273,15 +246,16 @@ pub trait Theme: Extension + Send + Sync {
/// Contenido predefinido para la página de error "*404 - Not Found*" (recurso no encontrado). /// Contenido predefinido para la página de error "*404 - Not Found*" (recurso no encontrado).
/// ///
/// Normalmente se renderiza con la plantilla predeterminada del tema (por defecto suele ser /// Normalmente se renderiza con la plantilla ya activa en la página (por ejemplo
/// [`DefaultTemplates::Standard`]). Los temas pueden sobrescribir este método para personalizar /// [`CoreTemplate::Standard`](crate::core::theme::CoreTemplate::Standard)). Los temas pueden
/// completamente el diseño y el contenido de la página de error. /// sobrescribir este método para personalizar completamente el diseño y el contenido de la
/// página de error.
fn error_404(&self, page: &mut Page) { fn error_404(&self, page: &mut Page) {
if let Some(parent) = self.parent() { if let Some(parent) = self.parent() {
return parent.error_404(page); return parent.error_404(page);
} }
page.alter_title(L10n::l("error404_title")).alter_child_in( page.alter_title(L10n::l("error404_title")).alter_child_in(
&DefaultRegions::Content, &CoreRegion::Content,
ChildOp::Prepend( ChildOp::Prepend(
Html::with(move |cx| { Html::with(move |cx| {
html! { html! {
@ -307,9 +281,10 @@ pub trait Theme: Extension + Send + Sync {
/// funcionan con normalidad. /// funcionan con normalidad.
/// ///
/// Por defecto, asigna el título al documento (`title`), se renderiza con la plantilla ya /// Por defecto, asigna el título al documento (`title`), se renderiza con la plantilla ya
/// activa en la página (normalmente [`DefaultTemplates::Standard`]) y muestra un componente /// activa en la página (normalmente
/// [`Intro`] con el código HTTP del error (`code`) y los mensajes proporcionados (`alert` y /// [`CoreTemplate::Standard`](crate::core::theme::CoreTemplate::Standard)) y muestra un
/// `help`) como descripción del error. /// componente [`Intro`] con el código HTTP del error (`code`) y los mensajes proporcionados
/// (`alert` y `help`) como descripción del error.
/// ///
/// Este método no se utiliza en las implementaciones predefinidas de [`Self::error_403()`] ni /// Este método no se utiliza en las implementaciones predefinidas de [`Self::error_403()`] ni
/// [`Self::error_404()`], que definen su propio contenido específico. /// [`Self::error_404()`], que definen su propio contenido específico.
@ -326,7 +301,7 @@ pub trait Theme: Extension + Send + Sync {
return parent.error_fatal(page, code, title, alert, help); return parent.error_fatal(page, code, title, alert, help);
} }
page.alter_title(title).alter_child_in( page.alter_title(title).alter_child_in(
&DefaultRegions::Content, &CoreRegion::Content,
ChildOp::Prepend( ChildOp::Prepend(
Intro::new() Intro::new()
.with_title(L10n::l("error_code").with_arg("code", code.to_string())) .with_title(L10n::l("error_code").with_arg("code", code.to_string()))

64
src/core/theme/regions.rs
View file

@ -1,5 +1,5 @@
use crate::core::component::{Child, ChildOp, Children, Component}; use crate::core::component::{Child, ChildOp, Children, Component};
use crate::core::theme::{DefaultRegions, RegionRef, ThemeRef}; use crate::core::theme::{CoreRegion, RegionRef, ThemeRef};
use crate::{AutoDefault, UniqueId, builder_fn}; use crate::{AutoDefault, UniqueId, builder_fn};
use parking_lot::RwLock; use parking_lot::RwLock;
@ -43,20 +43,19 @@ static COMMON_REGIONS: LazyLock<RwLock<RegionComponents>> =
pub(crate) struct ChildrenInRegions(HashMap<String, Children>); pub(crate) struct ChildrenInRegions(HashMap<String, Children>);
impl ChildrenInRegions { impl ChildrenInRegions {
pub fn with(region_ref: RegionRef, child: Child) -> Self { pub fn with(region: RegionRef, child: Child) -> Self {
Self::default().with_child_in(region_ref, child) Self::default().with_child_in(region, child)
} }
#[builder_fn] #[builder_fn]
pub fn with_child_in(mut self, region_ref: RegionRef, op: impl Into<ChildOp>) -> Self { pub fn with_child_in(mut self, region: RegionRef, op: impl Into<ChildOp>) -> Self {
let child = op.into(); let child = op.into();
if let Some(region) = self.0.get_mut(region_ref.name()) { let region_name = region.name();
if let Some(region) = self.0.get_mut(region_name) {
region.alter_child(child); region.alter_child(child);
} else { } else {
self.0.insert( let children = Children::new().with_child(child);
region_ref.name().to_owned(), self.0.insert(region_name.to_owned(), children);
Children::new().with_child(child),
);
} }
self self
} }
@ -71,7 +70,8 @@ impl ChildrenInRegions {
/// lugar de clonarse, ya que son de un único uso. /// lugar de clonarse, ya que son de un único uso.
/// 3. Prototipos del tema activo, exclusivos del tema en curso. También se clonan para asegurar /// 3. Prototipos del tema activo, exclusivos del tema en curso. También se clonan para asegurar
/// que llegan a `setup()` con el mismo estado inicial. /// que llegan a `setup()` con el mismo estado inicial.
pub fn assemble_region(&mut self, theme_ref: ThemeRef, region_name: &str) -> Children { pub fn assemble_region(&mut self, theme: ThemeRef, region: RegionRef) -> Children {
let region_name = region.name();
let common = COMMON_REGIONS.read(); let common = COMMON_REGIONS.read();
let themed = THEME_REGIONS.read(); let themed = THEME_REGIONS.read();
@ -90,7 +90,7 @@ impl ChildrenInRegions {
} }
} }
// 3. Prototipos del tema activo. // 3. Prototipos del tema activo.
if let Some(theme_map) = themed.get(&theme_ref.type_id()) { if let Some(theme_map) = themed.get(&theme.type_id()) {
if let Some(protos) = theme_map.get(region_name) { if let Some(protos) = theme_map.get(region_name) {
for proto in protos { for proto in protos {
result.add(proto.as_child()); result.add(proto.as_child());
@ -118,31 +118,27 @@ impl ChildrenInRegions {
/// InRegion::Content.add(Html::with(|_| html! { "🎉 ¡Bienvenido!" })); /// InRegion::Content.add(Html::with(|_| html! { "🎉 ¡Bienvenido!" }));
/// ///
/// // Texto en la cabecera, visible en todos los temas. /// // Texto en la cabecera, visible en todos los temas.
/// InRegion::Global(&DefaultRegions::Header).add(Html::with(|_| html! { "Publicidad" })); /// InRegion::Global(&CoreRegion::Header).add(Html::with(|_| html! { "Publicidad" }));
/// ``` /// ```
pub enum InRegion { pub enum InRegion {
/// Región principal de **contenido** por defecto. /// Región principal de **contenido** por defecto.
/// ///
/// Añade el componente a la región lógica de contenido principal de la aplicación. Por /// Añade el componente a la región lógica de contenido principal de la aplicación. Internamente
/// convención, esta región corresponde a [`DefaultRegions::Content`], cuyo nombre es /// equivale a `InRegion::Global(&CoreRegion::Content)`.
/// `"content"`. Cualquier tema que renderice esa misma región de contenido, ya sea usando
/// directamente [`DefaultRegions::Content`] o cualquier otra implementación de
/// [`Region`](crate::core::theme::Region) que devuelva ese mismo nombre, mostrará los
/// componentes registrados aquí, aunque lo harán según su propio método de renderizado
/// ([`Region::render()`](crate::core::theme::Region::render)).
Content, Content,
/// Región global compartida por todos los temas. /// Región global compartida por todos los temas.
/// ///
/// Los componentes añadidos aquí se asocian al nombre de la región indicado por [`RegionRef`], /// Los componentes añadidos aquí se asocian al nombre de la región indicado por [`RegionRef`],
/// es decir, al valor devuelto por [`Region::name()`](crate::core::theme::Region::name) para /// es decir, al valor devuelto por
/// esa región. Se mostrarán en cualquier tema cuya plantilla renderice una región que devuelva /// [`RegionName::name()`](crate::core::theme::RegionName::name) para esa región. Se mostrarán
/// ese mismo nombre. /// en cualquier tema que renderice la región que devuelva ese nombre.
Global(RegionRef), Global(RegionRef),
/// Región asociada a un tema concreto. /// Región asociada a un tema concreto.
/// ///
/// Los componentes sólo se renderizarán cuando el documento se procese con el tema indicado y /// Los componentes sólo se renderizarán cuando el documento se procese exactamente con el tema
/// se utilice la región referenciada. Resulta útil para añadir contenido específico en un tema /// indicado (no sirve un tema hijo que lo herede), y se utilice la región referenciada. A
/// sin afectar a otros. /// diferencia del resto de comportamiento de `Theme`, este registro no sigue la cadena
/// `parent()`. Resulta útil para añadir contenido específico en un tema sin afectar a otros.
ForTheme(ThemeRef, RegionRef), ForTheme(ThemeRef, RegionRef),
} }
@ -163,26 +159,26 @@ impl InRegion {
/// })); /// }));
/// ///
/// // Texto en la cabecera. /// // Texto en la cabecera.
/// InRegion::Global(&DefaultRegions::Header).add(Html::with(|_| { /// InRegion::Global(&CoreRegion::Header).add(Html::with(|_| {
/// html! { "Publicidad" } /// html! { "Publicidad" }
/// })); /// }));
/// ///
/// // Contenido sólo para la región del pie de página en un tema concreto. /// // Contenido sólo para la región del pie de página en un tema concreto.
/// InRegion::ForTheme(&theme::Basic, &DefaultRegions::Footer).add(Html::with(|_| { /// InRegion::ForTheme(&theme::Basic, &CoreRegion::Footer).add(Html::with(|_| {
/// html! { "Aviso legal" } /// html! { "Aviso legal" }
/// })); /// }));
/// ``` /// ```
pub fn add(&self, component: impl Component + Clone + 'static) -> &Self { pub fn add(&self, component: impl Component + Clone + 'static) -> &Self {
let proto: Arc<dyn ComponentGlobal> = Arc::new(component); let proto: Arc<dyn ComponentGlobal> = Arc::new(component);
match self { match self {
InRegion::Content => Self::add_to_common(&DefaultRegions::Content, proto), InRegion::Content => Self::add_to_common(&CoreRegion::Content, proto),
InRegion::Global(region_ref) => Self::add_to_common(*region_ref, proto), InRegion::Global(region) => Self::add_to_common(*region, proto),
InRegion::ForTheme(theme_ref, region_ref) => { InRegion::ForTheme(theme, region) => {
THEME_REGIONS THEME_REGIONS
.write() .write()
.entry(theme_ref.type_id()) .entry(theme.type_id())
.or_default() .or_default()
.entry((*region_ref).name().to_owned()) .entry((*region).name().to_owned())
.or_default() .or_default()
.push(proto); .push(proto);
} }
@ -191,10 +187,10 @@ impl InRegion {
} }
#[inline] #[inline]
fn add_to_common(region_ref: RegionRef, proto: Arc<dyn ComponentGlobal>) { fn add_to_common(region: RegionRef, proto: Arc<dyn ComponentGlobal>) {
COMMON_REGIONS COMMON_REGIONS
.write() .write()
.entry(region_ref.name().to_owned()) .entry(region.name().to_owned())
.or_default() .or_default()
.push(proto); .push(proto);
} }

83
src/response/page.rs
View file

@ -2,16 +2,17 @@
//! //!
//! Este módulo define [`Page`], que representa una página HTML lista para renderizar. Cada página //! Este módulo define [`Page`], que representa una página HTML lista para renderizar. Cada página
//! se construye a partir de un [`Context`] propio, donde se registran el tema activo, la plantilla //! se construye a partir de un [`Context`] propio, donde se registran el tema activo, la plantilla
//! ([`Template`](crate::core::theme::Template)) que define la disposición de las regiones //! ([`TemplateName`](crate::core::theme::TemplateName)) que define la disposición de las regiones
//! ([`Region`]), los componentes asociados y los recursos adicionales (hojas de estilo, scripts, //! ([`RegionName`]), los componentes asociados y los recursos adicionales (hojas de estilo,
//! *favicon*, etc.). //! scripts, *favicon*, etc.).
//! //!
//! El renderizado ([`Page::render()`]) delega en el tema ([`Theme`](crate::core::theme::Theme)) la //! El renderizado ([`Page::render()`]) delega en el tema ([`Theme`](crate::core::theme::Theme)) la
//! composición del `<head>` y del `<body>`, y se ejecutan las acciones registradas por las //! composición del `<head>` y del `<body>`, y se ejecutan las acciones registradas por las
//! extensiones antes y después de generar los contenidos. //! extensiones antes y después de generar los contenidos.
//! //!
//! También introduce regiones internas reservadas ([`ReservedRegion`]) que actúan como puntos de //! También define las regiones internas reservadas ([`ReservedRegion`]) que actúan como puntos de
//! anclaje globales al inicio y al final del documento. //! anclaje globales al inicio y al final del `<body>`, fuera de las regiones que maqueta la
//! plantilla activa.
mod error; mod error;
pub use error::ErrorPage; pub use error::ErrorPage;
@ -19,8 +20,10 @@ pub(crate) use error::{render_error_pages, response_for_panic, route_not_found};
use crate::auth::CurrentUser; use crate::auth::CurrentUser;
use crate::base::action; use crate::base::action;
use crate::core::component::{AssetsOp, ChildOp, Context, ContextError, Contextual}; use crate::base::component::layout;
use crate::core::theme::{DefaultRegions, Region, RegionRef, TemplateRef, ThemeRef}; use crate::core::component::{AssetsOp, ChildOp, ComponentRender};
use crate::core::component::{Context, ContextError, Contextual};
use crate::core::theme::{CoreRegion, CoreTemplate, RegionName, RegionRef, TemplateRef, ThemeRef};
use crate::html::{Assets, Favicon, JavaScript, StyleSheet}; use crate::html::{Assets, Favicon, JavaScript, StyleSheet};
use crate::html::{Attr, Props, PropsOp}; use crate::html::{Attr, Props, PropsOp};
use crate::html::{DOCTYPE, Markup, html}; use crate::html::{DOCTYPE, Markup, html};
@ -32,37 +35,35 @@ use crate::{AutoDefault, builder_fn};
/// Regiones internas reservadas como puntos de anclaje globales. /// Regiones internas reservadas como puntos de anclaje globales.
/// ///
/// Representan contenedores especiales situados al inicio y al final de un documento. Están /// Representan contenedores especiales situados al inicio y al final del `<body>`, fuera de las
/// pensadas para proporcionar regiones donde inyectar contenido global o técnico. No suelen usarse /// regiones que maqueta la plantilla activa. Las renderiza directamente [`Page::render()`],
/// como regiones visibles en los temas. /// envolviendo el resultado de
/// [`Theme::render_page_body()`](crate::core::theme::Theme::render_page_body). **No suelen usarse
/// como regiones "visibles" en los temas**, sino para inyectar contenido global o técnico.
#[derive(AutoDefault)]
pub enum ReservedRegion { pub enum ReservedRegion {
/// Región interna situada al **inicio del documento**. /// Región interna situada al **inicio del `<body>`**, de nombre `"page-top"`.
/// ///
/// Su función es proporcionar un contenedor donde las extensiones puedan inyectar contenido /// Proporciona un contenedor donde las extensiones puedan inyectar elementos auxiliares antes
/// global antes del resto de regiones principales (cabecera, contenido, etc.). /// del resto de regiones (cabecera, contenido, etc.), como marcadores técnicos, inicializadores
/// /// o contenido de depuración.
/// No suele utilizarse en los temas como una región “visible” dentro del maquetado habitual,
/// sino como punto de anclaje para elementos auxiliares, marcadores técnicos, inicializadores o
/// contenido de depuración que deban situarse en la parte superior del documento.
/// ///
/// Se considera una región **reservada** para este tipo de usos globales. /// Se considera una región **reservada** para este tipo de usos globales.
#[default]
PageTop, PageTop,
/// Región interna situada al **final del documento**. /// Región interna situada al **final del `<body>`**, de nombre `"page-bottom"`.
/// ///
/// Pensada para proporcionar un contenedor donde las extensiones puedan inyectar contenido /// Proporciona un contenedor donde las extensiones puedan inyectar contenido global después del
/// global después del resto de regiones principales (cabecera, contenido, etc.). /// resto de regiones (cabecera, contenido, etc.), como elementos auxiliares asociados a
/// /// comportamientos dinámicos.
/// No suele utilizarse en los temas como una región “visible” dentro del maquetado habitual,
/// sino como punto de anclaje para elementos auxiliares asociados a comportamientos dinámicos
/// que deban situarse en la parte inferior del documento.
/// ///
/// Igual que [`Self::PageTop`], se considera una región **reservada** para este tipo de usos /// Igual que [`Self::PageTop`], se considera una región **reservada** para este tipo de usos
/// globales. /// globales.
PageBottom, PageBottom,
} }
impl Region for ReservedRegion { impl RegionName for ReservedRegion {
#[inline] #[inline]
fn name(&self) -> &'static str { fn name(&self) -> &'static str {
match self { match self {
@ -101,22 +102,23 @@ impl Page {
/// [`CurrentUser`] inyectado por middleware en sus extensiones (ver /// [`CurrentUser`] inyectado por middleware en sus extensiones (ver
/// [`Context::new`](crate::core::component::Context::new)). Cualquier handler tiene acceso al /// [`Context::new`](crate::core::component::Context::new)). Cualquier handler tiene acceso al
/// usuario actual desde el momento en que se crea la página, sin llamadas adicionales. /// usuario actual desde el momento en que se crea la página, sin llamadas adicionales.
#[rustfmt::skip]
pub fn new(request: HttpRequest) -> Self { pub fn new(request: HttpRequest) -> Self {
Page { Page {
title : Attr::<L10n>::default(), context: Context::new(Some(request)),
description : Attr::<L10n>::default(), ..Default::default()
metadata : Vec::default(),
properties : Vec::default(),
context : Context::new(Some(request)),
} }
} }
/// Crea una nueva instancia de página con la plantilla de administración del tema activo. /// Crea una nueva instancia de página con la plantilla [`CoreTemplate::Admin`].
///
/// Cada tema puede maquetarla de forma distinta capturando
/// [`Template`](crate::base::component::layout::Template) en `handle_component()`, pero la
/// plantilla en sí es la misma constante para cualquier tema.
pub fn admin(request: HttpRequest) -> Self { pub fn admin(request: HttpRequest) -> Self {
let mut page = Page::new(request); Page {
page.context().use_admin_template(); context: Context::new(Some(request)).with_template(&CoreTemplate::Admin),
page ..Default::default()
}
} }
// **< Page BUILDER >*************************************************************************** // **< Page BUILDER >***************************************************************************
@ -217,9 +219,9 @@ impl Page {
// Renderiza el <body>. // Renderiza el <body>.
let body = html! { let body = html! {
(ReservedRegion::PageTop.render(&mut self.context).await) (layout::Region::of(&ReservedRegion::PageTop).render(&mut self.context).await)
(self.context.theme().render_page_body(self).await) (self.context.theme().render_page_body(self).await)
(ReservedRegion::PageBottom.render(&mut self.context).await) (layout::Region::of(&ReservedRegion::PageBottom).render(&mut self.context).await)
}; };
// Acciones específicas del tema después de renderizar el <body>. // Acciones específicas del tema después de renderizar el <body>.
@ -310,14 +312,13 @@ impl Contextual for Page {
#[builder_fn] #[builder_fn]
fn with_child(mut self, op: impl Into<ChildOp>) -> Self { fn with_child(mut self, op: impl Into<ChildOp>) -> Self {
self.context self.context.alter_child_in(&CoreRegion::Content, op.into());
.alter_child_in(&DefaultRegions::Content, op.into());
self self
} }
#[builder_fn] #[builder_fn]
fn with_child_in(mut self, region_ref: RegionRef, op: impl Into<ChildOp>) -> Self { fn with_child_in(mut self, region: RegionRef, op: impl Into<ChildOp>) -> Self {
self.context.alter_child_in(region_ref, op.into()); self.context.alter_child_in(region, op.into());
self self
} }

118
tests/component_template.rs Normal file
View file

@ -0,0 +1,118 @@
use pagetop::prelude::*;
/// Initializes PageTop (locale, extensions...) once for the whole suite.
///
/// Rendering a `Region`/`Template` looks up localized labels (`aria-label`, etc.), so tests that
/// render them need the localization subsystem loaded.
async fn setup() {
Application::new().await;
}
// **< A theme that intercepts the `Template` component >*******************************************
/// Replaces the default `Template` composition (`Header` + `Content` + `Footer`) with a fixed
/// marker string, for both `CoreTemplate::Standard` and `CoreTemplate::Admin`. Mirrors how
/// a real theme (e.g. `pagetop-bootsier`) tells its own layout apart from PageTop's default: by
/// intercepting the `Template` component in `handle_component()`, not by swapping which
/// `TemplateRef` gets resolved.
struct MarkerTheme;
#[async_trait]
impl Extension for MarkerTheme {
fn theme(&self) -> Option<ThemeRef> {
Some(&Self)
}
}
#[async_trait]
impl Theme for MarkerTheme {
async fn handle_component(
&self,
component: &mut dyn Component,
_cx: &mut Context,
) -> Option<Result<Markup, ComponentError>> {
let template = (&*component).downcast_ref::<layout::Template>()?;
template.template().downcast_ref::<CoreTemplate>()?;
Some(Ok(html! { "marker-template-output" }))
}
}
// **< Default/Admin template identity is independent of the active theme >*************************
//
// `Theme::default_template()`/`admin_template()` were removed: `Context::template()` always
// resolves `Default`/`Admin` to the core `CoreTemplate::Standard`/`Admin` identity, regardless
// of which theme is active. Themes customize the actual rendering by intercepting the `Template`
// component in `handle_component()` instead (see the tests further below).
#[pagetop::test]
async fn default_template_identity_is_independent_of_theme() {
let cx = Context::new(None);
assert_eq!(cx.template().name(), "standard");
let cx = Context::new(None).with_theme(&MarkerTheme);
assert_eq!(cx.template().name(), "standard");
}
#[pagetop::test]
async fn admin_template_identity_is_independent_of_theme() {
let mut page = Page::admin(web::test::TestRequest::get().to_http_request());
assert_eq!(page.context().template().name(), "admin");
let mut page =
Page::admin(web::test::TestRequest::get().to_http_request()).with_theme(&MarkerTheme);
assert_eq!(page.context().template().name(), "admin");
}
#[pagetop::test]
async fn explicit_template_is_not_overridden_by_a_later_with_theme() {
// A template explicitly set with `with_template()` prevails even if `with_theme()` is called
// afterwards.
let cx = Context::new(None)
.with_template(&CoreTemplate::Admin)
.with_theme(&pagetop::base::theme::Basic);
assert_eq!(cx.template().name(), "admin");
}
// **< A theme customizes rendering via `handle_component()` >**************************************
#[pagetop::test]
async fn without_a_matching_theme_the_default_composition_is_used() {
setup().await;
// With no theme intercepting it, and no content registered in any region, the default
// composition (Header + Content + Footer) renders empty.
let mut template = layout::Template::default();
let html = template.render(&mut Context::default()).await.into_string();
assert!(html.is_empty());
}
#[pagetop::test]
async fn theme_replaces_template_rendering_via_handle_component() {
setup().await;
let mut template = layout::Template::default();
let mut cx = Context::default().with_theme(&MarkerTheme);
let html = template.render(&mut cx).await.into_string();
assert_eq!(html, "marker-template-output");
}
// **< Page::render() reaches the active theme's `handle_component()` >*****************************
#[pagetop::test]
async fn page_admin_render_reflects_the_active_theme_template() {
setup().await;
let request = web::test::TestRequest::get().to_http_request();
let mut page = Page::admin(request).with_theme(&MarkerTheme);
let html = page
.render()
.await
.expect("page should render")
.into_string();
assert!(html.contains("marker-template-output"));
}

83
tests/theme_template.rs
View file

@ -1,83 +0,0 @@
use pagetop::prelude::*;
// **< Theme with its own template >****************************************************************
struct MarkerTemplate;
#[async_trait]
impl Template for MarkerTemplate {
async fn render(&self, _cx: &mut Context) -> Markup {
html! { "marker-template-output" }
}
}
struct MarkerTheme;
#[async_trait]
impl Extension for MarkerTheme {
fn theme(&self) -> Option<ThemeRef> {
Some(&Self)
}
}
#[async_trait]
impl Theme for MarkerTheme {
fn default_template(&self) -> TemplateRef {
&MarkerTemplate
}
fn admin_template(&self) -> TemplateRef {
&MarkerTemplate
}
}
async fn render_active_template(cx: &mut Context) -> String {
let template = cx.template();
template.render(cx).await.into_string()
}
// **< Context::template() follows the active theme >***********************************************
#[pagetop::test]
async fn with_theme_updates_the_effective_template() {
// Without changing theme, the active template is not `MarkerTheme`'s.
let mut cx = Context::new(None);
assert_ne!(
render_active_template(&mut cx).await,
"marker-template-output"
);
// After changing theme with `with_theme()`, the active template becomes that theme's, with no
// need to call `with_template()` explicitly.
let mut cx = Context::new(None).with_theme(&MarkerTheme);
assert_eq!(
render_active_template(&mut cx).await,
"marker-template-output"
);
}
#[pagetop::test]
async fn explicit_template_is_not_overridden_by_a_later_with_theme() {
// A template explicitly set with `with_template()` prevails even if `with_theme()` is called
// afterwards, regardless of order.
let mut cx = Context::new(None)
.with_template(&MarkerTemplate)
.with_theme(&pagetop::base::theme::Basic);
assert_eq!(
render_active_template(&mut cx).await,
"marker-template-output"
);
}
// **< Page::admin() follows the active theme >*****************************************************
#[pagetop::test]
async fn page_admin_template_follows_a_later_with_theme() {
let request = web::test::TestRequest::get().to_http_request();
let mut page = Page::admin(request).with_theme(&MarkerTheme);
let markup = page.context().template().render(page.context()).await;
assert_eq!(markup.into_string(), "marker-template-output");
}