♻️ Refactoriza la gestión de regiones y plantillas
This commit is contained in:
parent
0746bbbee7
commit
9f79e4179a
15 changed files with 494 additions and 655 deletions
|
|
@ -1,7 +1,6 @@
|
|||
use crate::base::component::Template;
|
||||
use crate::core::component::ChildOp;
|
||||
use crate::core::theme::all::DEFAULT_THEME;
|
||||
use crate::core::theme::{ChildrenInRegions, ThemeRef};
|
||||
use crate::core::theme::{ChildrenInRegions, RegionRef, TemplateRef, ThemeRef};
|
||||
use crate::core::TypeInfo;
|
||||
use crate::html::{html, Markup};
|
||||
use crate::html::{Assets, Favicon, JavaScript, StyleSheet};
|
||||
|
|
@ -68,7 +67,7 @@ pub enum ContextError {
|
|||
/// fn prepare_context<C: Contextual>(cx: C) -> C {
|
||||
/// cx.with_langid(&LangMatch::resolve("es-ES"))
|
||||
/// .with_theme(&Aliner)
|
||||
/// .with_template(Template::DEFAULT)
|
||||
/// .with_template(&DefaultTemplate::Standard)
|
||||
/// .with_assets(ContextOp::SetFavicon(Some(Favicon::new().with_icon("/favicon.ico"))))
|
||||
/// .with_assets(ContextOp::AddStyleSheet(StyleSheet::from("/css/app.css")))
|
||||
/// .with_assets(ContextOp::AddJavaScript(JavaScript::defer("/js/app.js")))
|
||||
|
|
@ -92,7 +91,7 @@ pub trait Contextual: LangId {
|
|||
|
||||
/// Especifica la plantilla para renderizar el documento.
|
||||
#[builder_fn]
|
||||
fn with_template(self, template_name: &'static str) -> Self;
|
||||
fn with_template(self, template: TemplateRef) -> Self;
|
||||
|
||||
/// Añade o modifica un parámetro dinámico del contexto.
|
||||
#[builder_fn]
|
||||
|
|
@ -102,9 +101,9 @@ pub trait Contextual: LangId {
|
|||
#[builder_fn]
|
||||
fn with_assets(self, op: ContextOp) -> Self;
|
||||
|
||||
/// Opera con [`ChildOp`] en una región (`region_name`) del documento.
|
||||
/// Opera con [`ChildOp`] en una región del documento.
|
||||
#[builder_fn]
|
||||
fn with_child_in(self, region_name: impl AsRef<str>, op: ChildOp) -> Self;
|
||||
fn with_child_in(self, region_ref: RegionRef, op: ChildOp) -> Self;
|
||||
|
||||
// **< Contextual GETTERS >*********************************************************************
|
||||
|
||||
|
|
@ -114,8 +113,8 @@ pub trait Contextual: LangId {
|
|||
/// Devuelve el tema que se usará para renderizar el documento.
|
||||
fn theme(&self) -> ThemeRef;
|
||||
|
||||
/// Devuelve el nombre de la plantilla usada para renderizar el documento.
|
||||
fn template(&self) -> &str;
|
||||
/// Devuelve la plantilla configurada para renderizar el documento.
|
||||
fn template(&self) -> TemplateRef;
|
||||
|
||||
/// Recupera un parámetro como [`Option`].
|
||||
fn param<T: 'static>(&self, key: &'static str) -> Option<&T>;
|
||||
|
|
@ -208,7 +207,7 @@ pub struct Context {
|
|||
request : Option<HttpRequest>, // Solicitud HTTP de origen.
|
||||
langid : &'static LanguageIdentifier, // Identificador de idioma.
|
||||
theme : ThemeRef, // Referencia al tema usado para renderizar.
|
||||
template : &'static str, // Nombre de la plantilla usada para renderizar.
|
||||
template : TemplateRef, // Plantilla usada para renderizar.
|
||||
favicon : Option<Favicon>, // Favicon, si se ha definido.
|
||||
stylesheets: Assets<StyleSheet>, // Hojas de estilo CSS.
|
||||
javascripts: Assets<JavaScript>, // Scripts JavaScript.
|
||||
|
|
@ -248,7 +247,7 @@ impl Context {
|
|||
request,
|
||||
langid,
|
||||
theme : *DEFAULT_THEME,
|
||||
template : Template::DEFAULT,
|
||||
template : DEFAULT_THEME.default_template(),
|
||||
favicon : None,
|
||||
stylesheets: Assets::<StyleSheet>::new(),
|
||||
javascripts: Assets::<JavaScript>::new(),
|
||||
|
|
@ -286,10 +285,10 @@ impl Context {
|
|||
markup
|
||||
}
|
||||
|
||||
/// Renderiza los componentes de la región `region_name`.
|
||||
pub fn render_region(&mut self, region_name: impl AsRef<str>) -> Markup {
|
||||
/// Renderiza los componentes de una región.
|
||||
pub fn render_region(&mut self, region_ref: RegionRef) -> Markup {
|
||||
self.regions
|
||||
.children_for(self.theme, region_name)
|
||||
.children_for(self.theme, region_ref)
|
||||
.render(self)
|
||||
}
|
||||
|
||||
|
|
@ -417,8 +416,8 @@ impl Contextual for Context {
|
|||
}
|
||||
|
||||
#[builder_fn]
|
||||
fn with_template(mut self, template_name: &'static str) -> Self {
|
||||
self.template = template_name;
|
||||
fn with_template(mut self, template: TemplateRef) -> Self {
|
||||
self.template = template;
|
||||
self
|
||||
}
|
||||
|
||||
|
|
@ -474,8 +473,8 @@ impl Contextual for Context {
|
|||
}
|
||||
|
||||
#[builder_fn]
|
||||
fn with_child_in(mut self, region_name: impl AsRef<str>, op: ChildOp) -> Self {
|
||||
self.regions.alter_child_in(region_name, op);
|
||||
fn with_child_in(mut self, region_ref: RegionRef, op: ChildOp) -> Self {
|
||||
self.regions.alter_child_in(region_ref, op);
|
||||
self
|
||||
}
|
||||
|
||||
|
|
@ -489,7 +488,7 @@ impl Contextual for Context {
|
|||
self.theme
|
||||
}
|
||||
|
||||
fn template(&self) -> &str {
|
||||
fn template(&self) -> TemplateRef {
|
||||
self.template
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -4,24 +4,23 @@ use crate::core::AnyInfo;
|
|||
use crate::locale::L10n;
|
||||
use crate::{actions_boxed, service};
|
||||
|
||||
/// Representa una referencia a una extensión.
|
||||
///
|
||||
/// Las extensiones se definen como instancias estáticas globales para poder acceder a ellas desde
|
||||
/// cualquier hilo de la ejecución sin necesidad de sincronización adicional.
|
||||
pub type ExtensionRef = &'static dyn Extension;
|
||||
|
||||
/// Interfaz común que debe implementar cualquier extensión de PageTop.
|
||||
///
|
||||
/// Este *trait* es fácil de implementar, basta con declarar una estructura de tamaño cero para la
|
||||
/// extensión y sobreescribir los métodos que sea necesario.
|
||||
/// Este *trait* es fácil de implementar, basta con declarar una estructura sin campos para la
|
||||
/// extensión y sobrescribir los métodos que sean necesarios. Por ejemplo:
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
/// pub struct Blog;
|
||||
///
|
||||
/// impl Extension for Blog {
|
||||
/// fn name(&self) -> L10n { L10n::n("Blog") }
|
||||
/// fn description(&self) -> L10n { L10n::n("Blog system") }
|
||||
/// fn name(&self) -> L10n {
|
||||
/// L10n::n("Blog")
|
||||
/// }
|
||||
///
|
||||
/// fn description(&self) -> L10n {
|
||||
/// L10n::n("Blog system")
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub trait Extension: AnyInfo + Send + Sync {
|
||||
|
|
@ -34,14 +33,19 @@ pub trait Extension: AnyInfo + Send + Sync {
|
|||
}
|
||||
|
||||
/// Descripción corta localizada de la extensión para paneles, listados, etc.
|
||||
///
|
||||
/// Por defecto devuelve un valor vacío (`L10n::default()`).
|
||||
fn description(&self) -> L10n {
|
||||
L10n::default()
|
||||
}
|
||||
|
||||
/// Devuelve una referencia a esta misma extensión cuando se trata de un tema.
|
||||
/// Devuelve una referencia a esta misma extensión cuando actúa como un tema.
|
||||
///
|
||||
/// Para ello, debe implementar [`Extension`] y también [`Theme`](crate::core::theme::Theme). Si
|
||||
/// la extensión no es un tema, este método devuelve `None` por defecto.
|
||||
/// Para ello, la implementación concreta debe ser una extensión que también implemente
|
||||
/// [`Theme`](crate::core::theme::Theme). Por defecto, asume que la extensión no es un tema y
|
||||
/// devuelve `None`.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
|
|
@ -61,17 +65,17 @@ pub trait Extension: AnyInfo + Send + Sync {
|
|||
|
||||
/// Otras extensiones que deben habilitarse **antes** de esta.
|
||||
///
|
||||
/// PageTop las resolverá automáticamente respetando el orden durante el arranque de la
|
||||
/// aplicación.
|
||||
/// PageTop resolverá automáticamente estas dependencias respetando el orden durante el arranque
|
||||
/// de la aplicación.
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![]
|
||||
}
|
||||
|
||||
/// Devuelve la lista de acciones que la extensión va a registrar.
|
||||
/// Devuelve la lista de acciones que la extensión registra.
|
||||
///
|
||||
/// Estas [acciones](crate::core::action) se despachan por orden de registro o por
|
||||
/// [peso](crate::Weight), permitiendo personalizar el comportamiento de la aplicación en puntos
|
||||
/// específicos.
|
||||
/// [peso](crate::Weight) (ver [`actions_boxed!`](crate::actions_boxed)), permitiendo
|
||||
/// personalizar el comportamiento de la aplicación en puntos específicos.
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions_boxed![]
|
||||
}
|
||||
|
|
@ -85,6 +89,8 @@ pub trait Extension: AnyInfo + Send + Sync {
|
|||
/// Configura los servicios web de la extensión, como rutas, *middleware*, acceso a ficheros
|
||||
/// estáticos, etc., usando [`ServiceConfig`](crate::service::web::ServiceConfig).
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// # use pagetop::prelude::*;
|
||||
/// pub struct ExtensionSample;
|
||||
|
|
@ -98,11 +104,15 @@ pub trait Extension: AnyInfo + Send + Sync {
|
|||
#[allow(unused_variables)]
|
||||
fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {}
|
||||
|
||||
/// Permite crear extensiones para deshabilitar y desinstalar recursos de otras de versiones
|
||||
/// anteriores de la aplicación.
|
||||
/// Permite declarar extensiones destinadas a deshabilitar o desinstalar recursos de otras
|
||||
/// extensiones asociadas a versiones anteriores de la aplicación.
|
||||
///
|
||||
/// Actualmente no se usa, pero se deja como *placeholder* para futuras implementaciones.
|
||||
/// Actualmente PageTop no utiliza este método, pero se reserva como *placeholder* para futuras
|
||||
/// implementaciones.
|
||||
fn drop_extensions(&self) -> Vec<ExtensionRef> {
|
||||
vec![]
|
||||
}
|
||||
}
|
||||
|
||||
/// Representa una referencia a una extensión.
|
||||
pub type ExtensionRef = &'static dyn Extension;
|
||||
|
|
|
|||
|
|
@ -1,18 +1,206 @@
|
|||
//! API para añadir y gestionar nuevos temas.
|
||||
//!
|
||||
//! En PageTop un tema es la *piel* de la aplicación. Es responsable último de los estilos,
|
||||
//! tipografías, espaciados y cualquier otro detalle visual o interactivo (animaciones, scripts de
|
||||
//! interfaz, etc.).
|
||||
//! Los temas son extensiones que implementan [`Extension`](crate::core::extension::Extension) y
|
||||
//! también [`Theme`], de modo que [`Extension::theme()`](crate::core::extension::Extension::theme)
|
||||
//! permita identificar y registrar los temas disponibles.
|
||||
//!
|
||||
//! Un tema determina el aspecto final de un documento HTML sin alterar la lógica interna de los
|
||||
//! componentes ni la estructura del documento, que queda definida por la plantilla
|
||||
//! ([`Template`](crate::base::component::Template)) utilizada por cada página.
|
||||
//! 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
|
||||
//! del documento a partir de varias regiones ([`Region`]). Cada región es un contenedor lógico
|
||||
//! identificado por un nombre, cuyo contenido se obtiene del [`Context`] de la página.
|
||||
//!
|
||||
//! Los temas son extensiones que implementan [`Extension`](crate::core::extension::Extension), por
|
||||
//! lo que se instancian, declaran dependencias y se inician igual que cualquier otra extensión.
|
||||
//! También deben implementar [`Theme`] y sobrescribir el método
|
||||
//! [`Extension::theme()`](crate::core::extension::Extension::theme) para que PageTop pueda
|
||||
//! registrarlos como temas.
|
||||
//! Una página ([`Page`](crate::response::page::Page)) representa un documento HTML completo.
|
||||
//! Implementa [`Contextual`](crate::core::component::Contextual) para gestionar su propio
|
||||
//! [`Context`], donde mantiene el tema activo, la plantilla seleccionada y los componentes
|
||||
//! asociados a cada región.
|
||||
//!
|
||||
//! De este modo, temas y extensiones colaboran sobre una estructura común: las aplicaciones
|
||||
//! registran componentes en el [`Context`], las plantillas organizan las regiones y las páginas
|
||||
//! generan el documento HTML resultante.
|
||||
//!
|
||||
//! Los temas pueden definir sus propias implementaciones de [`Template`] y [`Region`] (por ejemplo,
|
||||
//! mediante *enums* adicionales) para añadir nuevas plantillas o exponer regiones específicas.
|
||||
|
||||
use crate::core::component::Context;
|
||||
use crate::html::{html, Markup};
|
||||
use crate::locale::L10n;
|
||||
use crate::{join, AutoDefault};
|
||||
|
||||
// **< Region >*************************************************************************************
|
||||
|
||||
/// Interfaz común para las regiones lógicas de un documento.
|
||||
///
|
||||
/// Una `Region` representa un contenedor lógico identificado por un nombre de región. Su contenido
|
||||
/// se obtiene del [`Context`], donde los componentes 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
|
||||
/// implementaciones de [`Region`] que devuelvan el mismo nombre compartirán el mismo conjunto de
|
||||
/// componentes registrados en el [`Context`], aunque cada región puede renderizar ese contenido de
|
||||
/// forma diferente. Por ejemplo, [`DefaultRegion::Header`] y `BootsierRegion::Header` mostrarían
|
||||
/// los mismos componentes si ambas devuelven el nombre `"header"`, pero podrían maquetarse de
|
||||
/// manera distinta.
|
||||
///
|
||||
/// El tema decide qué regiones mostrar en el cuerpo del documento, normalmente usando una plantilla
|
||||
/// ([`Template`]) al renderizar la página ([`Page`](crate::response::page::Page)).
|
||||
pub trait Region {
|
||||
/// 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`]
|
||||
/// para recuperar y renderizar el contenido registrado bajo ese nombre. Cualquier
|
||||
/// implementación de [`Region`] que devuelva el mismo 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;
|
||||
|
||||
/// Devuelve la etiqueta de accesibilidad localizada asociada a la región.
|
||||
///
|
||||
/// En la implementación predeterminada de [`Self::render()`], este valor se usa como
|
||||
/// `aria-label` del contenedor de la región.
|
||||
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 la
|
||||
/// etiqueta localizada de 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.
|
||||
fn render(&'static self, cx: &mut Context) -> Markup
|
||||
where
|
||||
Self: Sized,
|
||||
{
|
||||
html! {
|
||||
@let region = cx.render_region(self);
|
||||
@if !region.is_empty() {
|
||||
div
|
||||
class=(join!("region region-", self.name()))
|
||||
role="region"
|
||||
aria-label=[self.label().lookup(cx)]
|
||||
{
|
||||
(region)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Referencia estática a una región.
|
||||
pub type RegionRef = &'static dyn Region;
|
||||
|
||||
// **< DefaultRegion >******************************************************************************
|
||||
|
||||
/// Regiones básicas que PageTop proporciona por defecto.
|
||||
///
|
||||
/// Estas regiones comparten sus nombres (`"header"`, `"content"`, `"footer"`) con cualquier región
|
||||
/// equivalente definida por otros temas, por lo que comparten también el contenido registrado bajo
|
||||
/// esos nombres.
|
||||
#[derive(AutoDefault)]
|
||||
pub enum DefaultRegion {
|
||||
/// Región estándar para la **cabecera** del documento, de nombre `"header"`.
|
||||
///
|
||||
/// Suele emplearse para mostrar un logotipo, navegación principal, barras superiores, etc.
|
||||
Header,
|
||||
|
||||
/// Región principal de **contenido**, de nombre `"content"`.
|
||||
///
|
||||
/// Es la región donde se renderiza el contenido principal del documento. En general será la
|
||||
/// región mínima imprescindible para que una página tenga sentido.
|
||||
#[default]
|
||||
Content,
|
||||
|
||||
/// Región estándar para el **pie de página**, de nombre `"footer"`.
|
||||
///
|
||||
/// Suele contener información legal, enlaces secundarios, créditos, etc.
|
||||
Footer,
|
||||
}
|
||||
|
||||
impl Region for DefaultRegion {
|
||||
#[inline]
|
||||
fn name(&self) -> &'static str {
|
||||
match self {
|
||||
Self::Header => "header",
|
||||
Self::Content => "content",
|
||||
Self::Footer => "footer",
|
||||
}
|
||||
}
|
||||
|
||||
#[inline]
|
||||
fn label(&self) -> L10n {
|
||||
match self {
|
||||
Self::Header => L10n::l("region-header"),
|
||||
Self::Content => L10n::l("region-content"),
|
||||
Self::Footer => L10n::l("region-footer"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// **< Template >***********************************************************************************
|
||||
|
||||
/// Interfaz común para definir plantillas de contenido.
|
||||
///
|
||||
/// Una `Template` puede proporcionar una o más variantes para decidir la composición del `<body>`
|
||||
/// de una página ([`Page`](crate::response::page::Page)). El tema utiliza esta información para
|
||||
/// determinar qué regiones ([`Region`]) deben renderizarse y en qué orden.
|
||||
pub trait Template {
|
||||
/// Renderiza el contenido de la plantilla.
|
||||
///
|
||||
/// Por defecto, renderiza las regiones básicas de [`DefaultRegion`] en este orden:
|
||||
/// [`DefaultRegion::Header`], [`DefaultRegion::Content`] y [`DefaultRegion::Footer`].
|
||||
///
|
||||
/// Se puede sobrescribir este método para:
|
||||
///
|
||||
/// - Cambiar el conjunto de regiones que se renderizan según variantes de la plantilla.
|
||||
/// - Alterar el orden de dichas regiones.
|
||||
/// - Envolver las regiones en contenedores adicionales.
|
||||
/// - 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())).
|
||||
fn render(&'static self, cx: &mut Context) -> Markup {
|
||||
html! {
|
||||
(DefaultRegion::Header.render(cx))
|
||||
(DefaultRegion::Content.render(cx))
|
||||
(DefaultRegion::Footer.render(cx))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Referencia estática a una plantilla.
|
||||
pub type TemplateRef = &'static dyn Template;
|
||||
|
||||
// **< DefaultTemplate >****************************************************************************
|
||||
|
||||
/// Plantillas que PageTop proporciona por defecto.
|
||||
#[derive(AutoDefault)]
|
||||
pub enum DefaultTemplate {
|
||||
/// Plantilla predeterminada.
|
||||
///
|
||||
/// Utiliza la implementación por defecto de [`Template::render()`] y se emplea cuando no se
|
||||
/// selecciona ninguna otra plantilla explícitamente.
|
||||
#[default]
|
||||
Standard,
|
||||
|
||||
/// Plantilla de error.
|
||||
///
|
||||
/// Se utiliza para páginas de error u otros estados excepcionales. Por defecto utiliza la misma
|
||||
/// implementación de [`Template::render()`] que [`Self::Standard`].
|
||||
Error,
|
||||
}
|
||||
|
||||
impl Template for DefaultTemplate {}
|
||||
|
||||
// **< Definitions >********************************************************************************
|
||||
|
||||
mod definition;
|
||||
pub use definition::{Theme, ThemeRef};
|
||||
|
|
|
|||
|
|
@ -1,30 +1,26 @@
|
|||
use crate::base::component::Template;
|
||||
use crate::core::component::{ComponentRender, ContextOp, Contextual};
|
||||
use crate::core::component::Contextual;
|
||||
use crate::core::extension::Extension;
|
||||
use crate::global;
|
||||
use crate::html::{html, Markup, StyleSheet};
|
||||
use crate::html::{html, Markup};
|
||||
use crate::locale::L10n;
|
||||
use crate::prelude::{DefaultTemplate, TemplateRef};
|
||||
use crate::response::page::Page;
|
||||
|
||||
/// Referencia estática a un tema.
|
||||
///
|
||||
/// Los temas son también extensiones. Por tanto, deben declararse como **instancias estáticas** que
|
||||
/// implementen [`Theme`] y, a su vez, [`Extension`]. Estas instancias se exponen usando
|
||||
/// [`Extension::theme()`](crate::core::extension::Extension::theme).
|
||||
pub type ThemeRef = &'static dyn Theme;
|
||||
|
||||
/// Interfaz común que debe implementar cualquier tema de PageTop.
|
||||
///
|
||||
/// 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>` mediante plantillas
|
||||
/// ([`Template`]) y qué contenido mostrar en las páginas de error.
|
||||
/// 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
|
||||
/// ([`Region`](crate::core::theme::Region)) y qué contenido mostrar en las páginas de error. El
|
||||
/// contenido de cada región depende del [`Context`](crate::core::component::Context) y de su nombre
|
||||
/// lógico.
|
||||
///
|
||||
/// 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
|
||||
/// predeterminados.
|
||||
///
|
||||
/// El único método **obligatorio** de `Extension` para un tema es [`theme()`](Extension::theme),
|
||||
/// que debe devolver una referencia estática al propio tema:
|
||||
/// que debe devolver una referencia al propio tema:
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
|
|
@ -47,32 +43,55 @@ pub type ThemeRef = &'static dyn Theme;
|
|||
/// impl Theme for MyTheme {}
|
||||
/// ```
|
||||
pub trait Theme: Extension + Send + Sync {
|
||||
/// 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::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 estándar ([`DefaultTemplate::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 {
|
||||
&DefaultTemplate::Standard
|
||||
}
|
||||
|
||||
/// Acciones específicas del tema antes de renderizar el `<body>` de la página.
|
||||
///
|
||||
/// Se invoca antes de que se procese la plantilla ([`Template`]) asociada a la página
|
||||
/// ([`Page::template()`](crate::response::page::Page::template)). Es un buen lugar para
|
||||
/// inicializar o ajustar recursos en función del contexto de la página, por ejemplo:
|
||||
/// Es un buen lugar para inicializar o ajustar recursos en función del contexto de la página,
|
||||
/// por ejemplo:
|
||||
///
|
||||
/// - Añadir metadatos o propiedades a la página.
|
||||
/// - Añadir metadatos o propiedades a la cabecera de la página.
|
||||
/// - Preparar atributos compartidos.
|
||||
/// - Registrar *assets* condicionales en el contexto.
|
||||
///
|
||||
/// La implementación por defecto no realiza ninguna acción.
|
||||
#[allow(unused_variables)]
|
||||
fn before_render_page_body(&self, page: &mut Page) {}
|
||||
|
||||
/// Renderiza el contenido del `<body>` de la página.
|
||||
///
|
||||
/// Por defecto, delega en la plantilla ([`Template`]) asociada a la página
|
||||
/// ([`Page::template()`](crate::response::page::Page::template)). La plantilla se encarga de
|
||||
/// procesar las regiones y renderizar los componentes registrados en el contexto.
|
||||
/// La implementación predeterminada delega en la plantilla asociada a la página, obtenida desde
|
||||
/// su [`Context`](crate::core::component::Context), y llama a
|
||||
/// [`Template::render()`](crate::core::theme::Template::render) para componer el `<body>` a
|
||||
/// partir de las regiones.
|
||||
///
|
||||
/// Con la configuración por defecto, la plantilla estándar utiliza las regiones
|
||||
/// [`DefaultRegion::Header`](crate::core::theme::DefaultRegion::Header),
|
||||
/// [`DefaultRegion::Content`](crate::core::theme::DefaultRegion::Content) y
|
||||
/// [`DefaultRegion::Footer`](crate::core::theme::DefaultRegion::Footer) en ese orden.
|
||||
///
|
||||
/// Los temas pueden sobrescribir este método para:
|
||||
///
|
||||
/// - Forzar una plantilla concreta en determinadas páginas.
|
||||
/// - Envolver el contenido en marcadores adicionales.
|
||||
/// - Consultar la plantilla de la página y variar la composición según su nombre.
|
||||
/// - Envolver el contenido en contenedores adicionales.
|
||||
/// - Implementar lógicas de composición alternativas.
|
||||
#[inline]
|
||||
fn render_page_body(&self, page: &mut Page) -> Markup {
|
||||
Template::named(page.template()).render(page.context())
|
||||
page.template().render(page.context())
|
||||
}
|
||||
|
||||
/// Acciones específicas del tema después de renderizar el `<body>` de la página.
|
||||
|
|
@ -83,6 +102,8 @@ pub trait Theme: Extension + Send + Sync {
|
|||
/// - Realizar *tracing* o recopilar métricas.
|
||||
/// - Aplicar ajustes finales al estado de la página antes de producir el `<head>` o la
|
||||
/// respuesta final.
|
||||
///
|
||||
/// La implementación por defecto no realiza ninguna acción.
|
||||
#[allow(unused_variables)]
|
||||
fn after_render_page_body(&self, page: &mut Page) {}
|
||||
|
||||
|
|
@ -101,34 +122,11 @@ pub trait Theme: Extension + Send + Sync {
|
|||
/// - La etiqueta `viewport` básica para diseño adaptable.
|
||||
/// - Los metadatos (`name`/`content`) y propiedades (`property`/`content`) declarados en la
|
||||
/// página.
|
||||
/// - Los *assets* registrados en el contexto de la página. Si el parámetro
|
||||
/// `include_basic_assets` está activado, añade de serie las siguientes hojas de estilo
|
||||
/// básicas: `normalize.css`, `root.css`, `basic.css`, útiles para temas sencillos o de uso
|
||||
/// general.
|
||||
/// - Los *assets* registrados en el contexto de la página.
|
||||
///
|
||||
/// Los temas pueden sobrescribir este método para añadir etiquetas adicionales (por ejemplo,
|
||||
/// *favicons* personalizados, manifest, etiquetas de analítica, etc.).
|
||||
#[inline]
|
||||
fn render_page_head(&self, page: &mut Page) -> Markup {
|
||||
if page.param_or("include_basic_assets", false) {
|
||||
let pkg_version = env!("CARGO_PKG_VERSION");
|
||||
|
||||
page.alter_assets(ContextOp::AddStyleSheet(
|
||||
StyleSheet::from("/css/normalize.css")
|
||||
.with_version("8.0.1")
|
||||
.with_weight(-99),
|
||||
))
|
||||
.alter_assets(ContextOp::AddStyleSheet(
|
||||
StyleSheet::from("/css/root.css")
|
||||
.with_version(pkg_version)
|
||||
.with_weight(-99),
|
||||
))
|
||||
.alter_assets(ContextOp::AddStyleSheet(
|
||||
StyleSheet::from("/css/basic.css")
|
||||
.with_version(pkg_version)
|
||||
.with_weight(-99),
|
||||
));
|
||||
}
|
||||
let viewport = "width=device-width, initial-scale=1, shrink-to-fit=no";
|
||||
html! {
|
||||
meta charset="utf-8";
|
||||
|
|
@ -173,3 +171,6 @@ pub trait Theme: Extension + Send + Sync {
|
|||
html! { div { h1 { (L10n::l("error404_notice").using(page)) } } }
|
||||
}
|
||||
}
|
||||
|
||||
/// Referencia estática a un tema.
|
||||
pub type ThemeRef = &'static dyn Theme;
|
||||
|
|
|
|||
|
|
@ -1,6 +1,5 @@
|
|||
use crate::base::component::Region;
|
||||
use crate::core::component::{Child, ChildOp, Children};
|
||||
use crate::core::theme::ThemeRef;
|
||||
use crate::core::theme::{DefaultRegion, RegionRef, ThemeRef};
|
||||
use crate::{builder_fn, AutoDefault, UniqueId};
|
||||
|
||||
use parking_lot::RwLock;
|
||||
|
|
@ -21,24 +20,23 @@ static COMMON_REGIONS: LazyLock<RwLock<ChildrenInRegions>> =
|
|||
pub(crate) struct ChildrenInRegions(HashMap<String, Children>);
|
||||
|
||||
impl ChildrenInRegions {
|
||||
pub fn with(region_name: impl AsRef<str>, child: Child) -> Self {
|
||||
Self::default().with_child_in(region_name, ChildOp::Add(child))
|
||||
pub fn with(region_ref: RegionRef, child: Child) -> Self {
|
||||
Self::default().with_child_in(region_ref, ChildOp::Add(child))
|
||||
}
|
||||
|
||||
#[builder_fn]
|
||||
pub fn with_child_in(mut self, region_name: impl AsRef<str>, op: ChildOp) -> Self {
|
||||
let name = region_name.as_ref();
|
||||
if let Some(region) = self.0.get_mut(name) {
|
||||
pub fn with_child_in(mut self, region_ref: RegionRef, op: ChildOp) -> Self {
|
||||
if let Some(region) = self.0.get_mut(region_ref.name()) {
|
||||
region.alter_child(op);
|
||||
} else {
|
||||
self.0
|
||||
.insert(name.to_owned(), Children::new().with_child(op));
|
||||
.insert(region_ref.name().to_owned(), Children::new().with_child(op));
|
||||
}
|
||||
self
|
||||
}
|
||||
|
||||
pub fn children_for(&self, theme_ref: ThemeRef, region_name: impl AsRef<str>) -> Children {
|
||||
let name = region_name.as_ref();
|
||||
pub fn children_for(&self, theme_ref: ThemeRef, region_ref: RegionRef) -> Children {
|
||||
let name = region_ref.name();
|
||||
let common = COMMON_REGIONS.read();
|
||||
let themed = THEME_REGIONS.read();
|
||||
|
||||
|
|
@ -50,20 +48,36 @@ impl ChildrenInRegions {
|
|||
}
|
||||
}
|
||||
|
||||
/// Permite añadir componentes a regiones globales o específicas de un tema.
|
||||
/// Añade componentes a regiones globales o específicas de un tema.
|
||||
///
|
||||
/// Según la variante, se pueden añadir componentes ([`add()`](Self::add)) que permanecerán
|
||||
/// disponibles durante toda la ejecución.
|
||||
///
|
||||
/// Estos componentes se renderizarán automáticamente al procesar los documentos HTML que incluyen
|
||||
/// estas regiones, como las páginas de contenido ([`Page`](crate::response::page::Page)).
|
||||
/// Cada variante indica la región en la que se añade el componente usando [`Self::add()`]. Los
|
||||
/// componentes añadidos se mantienen durante toda la ejecución y se inyectan automáticamente al
|
||||
/// renderizar los documentos HTML que utilizan esas regiones, como las páginas de contenido
|
||||
/// ([`Page`](crate::response::page::Page)).
|
||||
pub enum InRegion {
|
||||
/// Región de contenido por defecto.
|
||||
Default,
|
||||
/// Región identificada por el nombre proporcionado.
|
||||
Named(&'static str),
|
||||
/// Región identificada por su nombre para un tema concreto.
|
||||
OfTheme(&'static str, ThemeRef),
|
||||
/// 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
|
||||
/// convención, esta región corresponde a [`DefaultRegion::Content`], cuyo nombre es
|
||||
/// `"content"`. Cualquier tema que renderice esa misma región de contenido, ya sea usando
|
||||
/// directamente [`DefaultRegion::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,
|
||||
/// Región global compartida por todos los temas.
|
||||
///
|
||||
/// 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
|
||||
/// esa región. Se mostrarán en cualquier tema cuya plantilla renderice una región que devuelva
|
||||
/// ese mismo nombre.
|
||||
Global(RegionRef),
|
||||
/// Región asociada a un tema concreto.
|
||||
///
|
||||
/// Los componentes sólo se renderizarán cuando el documento se procese con el tema indicado y
|
||||
/// se utilice la región referenciada. Resulta útil para añadir contenido específico en un tema
|
||||
/// sin afectar a otros.
|
||||
ForTheme(ThemeRef, RegionRef),
|
||||
}
|
||||
|
||||
impl InRegion {
|
||||
|
|
@ -73,28 +87,33 @@ impl InRegion {
|
|||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
/// // Banner global, en la región por defecto de cualquier página.
|
||||
/// InRegion::Default.add(Child::with(Html::with(|_|
|
||||
/// html! { ("🎉 ¡Bienvenido!") }
|
||||
/// )));
|
||||
/// // Banner global en la región por defecto.
|
||||
/// InRegion::Content.add(Child::with(Html::with(|_| {
|
||||
/// html! { "🎉 ¡Bienvenido!" }
|
||||
/// })));
|
||||
///
|
||||
/// // Texto en la región "sidebar".
|
||||
/// InRegion::Named("sidebar").add(Child::with(Html::with(|_|
|
||||
/// html! { ("Publicidad") }
|
||||
/// )));
|
||||
/// // Texto en la cabecera.
|
||||
/// InRegion::Global(&DefaultRegion::Header).add(Child::with(Html::with(|_| {
|
||||
/// html! { "Publicidad" }
|
||||
/// })));
|
||||
///
|
||||
/// // Contenido sólo para la región del pie de página en un tema concreto.
|
||||
/// InRegion::ForTheme(&theme::Basic, &DefaultRegion::Footer).add(Child::with(Html::with(|_| {
|
||||
/// html! { "Aviso legal" }
|
||||
/// })));
|
||||
/// ```
|
||||
pub fn add(&self, child: Child) -> &Self {
|
||||
match self {
|
||||
InRegion::Default => Self::add_to_common(Region::DEFAULT, child),
|
||||
InRegion::Named(region_name) => Self::add_to_common(region_name, child),
|
||||
InRegion::OfTheme(region_name, theme_ref) => {
|
||||
InRegion::Content => Self::add_to_common(&DefaultRegion::Content, child),
|
||||
InRegion::Global(region_ref) => Self::add_to_common(*region_ref, child),
|
||||
InRegion::ForTheme(theme_ref, region_ref) => {
|
||||
let mut regions = THEME_REGIONS.write();
|
||||
if let Some(r) = regions.get_mut(&theme_ref.type_id()) {
|
||||
r.alter_child_in(region_name, ChildOp::Add(child));
|
||||
r.alter_child_in(*region_ref, ChildOp::Add(child));
|
||||
} else {
|
||||
regions.insert(
|
||||
theme_ref.type_id(),
|
||||
ChildrenInRegions::with(region_name, child),
|
||||
ChildrenInRegions::with(*region_ref, child),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
@ -103,9 +122,9 @@ impl InRegion {
|
|||
}
|
||||
|
||||
#[inline]
|
||||
fn add_to_common(region_name: &str, child: Child) {
|
||||
fn add_to_common(region_ref: RegionRef, child: Child) {
|
||||
COMMON_REGIONS
|
||||
.write()
|
||||
.alter_child_in(region_name, ChildOp::Add(child));
|
||||
.alter_child_in(region_ref, ChildOp::Add(child));
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue