✨ [theme] Añade componentes Region y Template
- Incluye un componente base `Template` para gestionar la estructura del documento y sus regiones (`Region`). - Actualiza el *trait* `Contextual` para permitir la selección de la plantilla de renderizado. - Modifica `Page` y `Context`, y refactoriza el manejo de temas, para dar soporte al nuevo sistema de plantillas y eliminar la gestión obsoleta de regiones.
This commit is contained in:
parent
e55a9805d7
commit
59268e9ddd
20 changed files with 506 additions and 475 deletions
|
|
@ -19,7 +19,7 @@ static ACTIONS: LazyLock<RwLock<HashMap<ActionKey, ActionsList>>> =
|
|||
//
|
||||
// Las extensiones llamarán a esta función durante su inicialización para instalar acciones
|
||||
// personalizadas que modifiquen el comportamiento del *core* o de otros componentes.
|
||||
pub fn add_action(action: ActionBox) {
|
||||
pub(crate) fn add_action(action: ActionBox) {
|
||||
let key = ActionKey::new(
|
||||
action.type_id(),
|
||||
action.theme_type_id(),
|
||||
|
|
|
|||
|
|
@ -200,7 +200,7 @@ pub enum TypedOp<C: Component> {
|
|||
/// Esta lista permite añadir, modificar, renderizar y consultar componentes hijo en orden de
|
||||
/// inserción, soportando operaciones avanzadas como inserción relativa o reemplazo por
|
||||
/// identificador.
|
||||
#[derive(Clone, Default)]
|
||||
#[derive(AutoDefault, Clone)]
|
||||
pub struct Children(Vec<Child>);
|
||||
|
||||
impl Children {
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
use crate::base::component::Template;
|
||||
use crate::core::component::ChildOp;
|
||||
use crate::core::theme::all::{theme_by_short_name, DEFAULT_THEME};
|
||||
use crate::core::theme::all::DEFAULT_THEME;
|
||||
use crate::core::theme::{ChildrenInRegions, ThemeRef};
|
||||
use crate::core::TypeInfo;
|
||||
use crate::html::{html, Markup};
|
||||
|
|
@ -13,19 +14,16 @@ use std::collections::HashMap;
|
|||
|
||||
/// Operaciones para modificar recursos asociados al contexto ([`Context`]) de un documento.
|
||||
pub enum ContextOp {
|
||||
// Favicon.
|
||||
/// Define el *favicon* del documento. Sobrescribe cualquier valor anterior.
|
||||
SetFavicon(Option<Favicon>),
|
||||
/// Define el *favicon* solo si no se ha establecido previamente.
|
||||
SetFaviconIfNone(Favicon),
|
||||
|
||||
// Stylesheets.
|
||||
/// Añade una hoja de estilos CSS al documento.
|
||||
AddStyleSheet(StyleSheet),
|
||||
/// Elimina una hoja de estilos por su ruta o identificador.
|
||||
RemoveStyleSheet(&'static str),
|
||||
|
||||
// JavaScripts.
|
||||
/// Añade un script JavaScript al documento.
|
||||
AddJavaScript(JavaScript),
|
||||
/// Elimina un script por su ruta o identificador.
|
||||
|
|
@ -50,27 +48,27 @@ pub enum ContextError {
|
|||
|
||||
/// Interfaz para gestionar el **contexto de renderizado** de un documento HTML.
|
||||
///
|
||||
/// `Contextual` extiende [`LangId`] y define los métodos para:
|
||||
/// `Contextual` extiende [`LangId`] para establecer el idioma del documento y añade métodos para:
|
||||
///
|
||||
/// - Establecer el **idioma** del documento.
|
||||
/// - Almacenar la **solicitud HTTP** de origen.
|
||||
/// - Seleccionar **tema** y **composición** (*layout*) de renderizado.
|
||||
/// - Seleccionar el **tema** y la **plantilla** de renderizado.
|
||||
/// - Administrar **recursos** del documento como el icono [`Favicon`], las hojas de estilo
|
||||
/// [`StyleSheet`] o los scripts [`JavaScript`] mediante [`ContextOp`].
|
||||
/// - Leer y mantener **parámetros dinámicos tipados** de contexto.
|
||||
/// - Generar **identificadores únicos** por tipo de componente.
|
||||
///
|
||||
/// Lo implementan, típicamente, estructuras que representan el contexto de renderizado, como
|
||||
/// Lo implementan, típicamente, estructuras que manejan el contexto de renderizado, como
|
||||
/// [`Context`](crate::core::component::Context) o [`Page`](crate::response::page::Page).
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
/// # use pagetop_aliner::Aliner;
|
||||
/// fn prepare_context<C: Contextual>(cx: C) -> C {
|
||||
/// cx.with_langid(&LangMatch::resolve("es-ES"))
|
||||
/// .with_theme("aliner")
|
||||
/// .with_layout("default")
|
||||
/// .with_theme(&Aliner)
|
||||
/// .with_template(Template::DEFAULT)
|
||||
/// .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")))
|
||||
|
|
@ -90,11 +88,11 @@ pub trait Contextual: LangId {
|
|||
|
||||
/// Especifica el tema para renderizar el documento.
|
||||
#[builder_fn]
|
||||
fn with_theme(self, theme_name: &'static str) -> Self;
|
||||
fn with_theme(self, theme: ThemeRef) -> Self;
|
||||
|
||||
/// Especifica la composición para renderizar el documento.
|
||||
/// Especifica la plantilla para renderizar el documento.
|
||||
#[builder_fn]
|
||||
fn with_layout(self, layout_name: &'static str) -> Self;
|
||||
fn with_template(self, template_name: &'static str) -> Self;
|
||||
|
||||
/// Añade o modifica un parámetro dinámico del contexto.
|
||||
#[builder_fn]
|
||||
|
|
@ -104,9 +102,9 @@ pub trait Contextual: LangId {
|
|||
#[builder_fn]
|
||||
fn with_assets(self, op: ContextOp) -> Self;
|
||||
|
||||
/// Opera con [`ChildOp`] en una región (`region_key`) de la página.
|
||||
/// Opera con [`ChildOp`] en una región (`region_name`) del documento.
|
||||
#[builder_fn]
|
||||
fn with_child_in(self, region_key: &'static str, op: ChildOp) -> Self;
|
||||
fn with_child_in(self, region_name: impl AsRef<str>, op: ChildOp) -> Self;
|
||||
|
||||
// **< Contextual GETTERS >*********************************************************************
|
||||
|
||||
|
|
@ -116,8 +114,8 @@ pub trait Contextual: LangId {
|
|||
/// Devuelve el tema que se usará para renderizar el documento.
|
||||
fn theme(&self) -> ThemeRef;
|
||||
|
||||
/// Devuelve la composición para renderizar el documento. Por defecto es `"default"`.
|
||||
fn layout(&self) -> &str;
|
||||
/// Devuelve el nombre de la plantilla usada para renderizar el documento.
|
||||
fn template(&self) -> &str;
|
||||
|
||||
/// Recupera un parámetro como [`Option`].
|
||||
fn param<T: 'static>(&self, key: &'static str) -> Option<&T>;
|
||||
|
|
@ -168,12 +166,13 @@ pub trait Contextual: LangId {
|
|||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
/// # use pagetop_aliner::Aliner;
|
||||
/// fn new_context(request: HttpRequest) -> Context {
|
||||
/// Context::new(Some(request))
|
||||
/// // Establece el idioma del documento a español.
|
||||
/// .with_langid(&LangMatch::resolve("es-ES"))
|
||||
/// // Selecciona un tema (por su nombre corto).
|
||||
/// .with_theme("aliner")
|
||||
/// // Establece el tema para renderizar.
|
||||
/// .with_theme(&Aliner)
|
||||
/// // Asigna un favicon.
|
||||
/// .with_assets(ContextOp::SetFavicon(Some(Favicon::new().with_icon("/favicon.ico"))))
|
||||
/// // Añade una hoja de estilo externa.
|
||||
|
|
@ -208,8 +207,8 @@ pub trait Contextual: LangId {
|
|||
pub struct Context {
|
||||
request : Option<HttpRequest>, // Solicitud HTTP de origen.
|
||||
langid : &'static LanguageIdentifier, // Identificador de idioma.
|
||||
theme : ThemeRef, // Referencia al tema para renderizar.
|
||||
layout : &'static str, // Composición del documento para renderizar.
|
||||
theme : ThemeRef, // Referencia al tema usado para renderizar.
|
||||
template : &'static str, // Nombre de la plantilla usada para renderizar.
|
||||
favicon : Option<Favicon>, // Favicon, si se ha definido.
|
||||
stylesheets: Assets<StyleSheet>, // Hojas de estilo CSS.
|
||||
javascripts: Assets<JavaScript>, // Scripts JavaScript.
|
||||
|
|
@ -227,8 +226,8 @@ impl Default for Context {
|
|||
impl Context {
|
||||
/// Crea un nuevo contexto asociado a una solicitud HTTP.
|
||||
///
|
||||
/// El contexto inicializa el idioma, tema y composición por defecto, sin favicon ni recursos
|
||||
/// cargados.
|
||||
/// El contexto inicializa el idioma, el tema y la plantilla por defecto, sin favicon ni otros
|
||||
/// recursos cargados.
|
||||
#[rustfmt::skip]
|
||||
pub fn new(request: Option<HttpRequest>) -> Self {
|
||||
// Se intenta DEFAULT_LANGID.
|
||||
|
|
@ -249,7 +248,7 @@ impl Context {
|
|||
request,
|
||||
langid,
|
||||
theme : *DEFAULT_THEME,
|
||||
layout : "default",
|
||||
template : Template::DEFAULT,
|
||||
favicon : None,
|
||||
stylesheets: Assets::<StyleSheet>::new(),
|
||||
javascripts: Assets::<JavaScript>::new(),
|
||||
|
|
@ -287,10 +286,10 @@ impl Context {
|
|||
markup
|
||||
}
|
||||
|
||||
/// Renderiza los componentes de una región (`region_key`).
|
||||
pub fn render_components_of(&mut self, region_key: &'static str) -> Markup {
|
||||
/// Renderiza los componentes de la región `region_name`.
|
||||
pub fn render_region(&mut self, region_name: impl AsRef<str>) -> Markup {
|
||||
self.regions
|
||||
.merge_all_components(self.theme, region_key)
|
||||
.children_for(self.theme, region_name)
|
||||
.render(self)
|
||||
}
|
||||
|
||||
|
|
@ -364,7 +363,7 @@ impl Context {
|
|||
|
||||
/// Elimina un parámetro del contexto. Devuelve `true` si la clave existía y se eliminó.
|
||||
///
|
||||
/// Devuelve `false` en caso contrario. Usar cuando solo interesa borrar la entrada.
|
||||
/// Devuelve `false` en caso contrario. Usar cuando sólo interesa borrar la entrada.
|
||||
///
|
||||
/// # Ejemplos
|
||||
///
|
||||
|
|
@ -411,19 +410,15 @@ impl Contextual for Context {
|
|||
self
|
||||
}
|
||||
|
||||
/// Asigna el tema para renderizar el documento.
|
||||
///
|
||||
/// Localiza el tema por su [`short_name()`](crate::core::AnyInfo::short_name), y si no aplica
|
||||
/// ninguno entonces usará el tema por defecto.
|
||||
#[builder_fn]
|
||||
fn with_theme(mut self, theme_name: &'static str) -> Self {
|
||||
self.theme = theme_by_short_name(theme_name).unwrap_or(*DEFAULT_THEME);
|
||||
fn with_theme(mut self, theme: ThemeRef) -> Self {
|
||||
self.theme = theme;
|
||||
self
|
||||
}
|
||||
|
||||
#[builder_fn]
|
||||
fn with_layout(mut self, layout_name: &'static str) -> Self {
|
||||
self.layout = layout_name;
|
||||
fn with_template(mut self, template_name: &'static str) -> Self {
|
||||
self.template = template_name;
|
||||
self
|
||||
}
|
||||
|
||||
|
|
@ -467,7 +462,7 @@ impl Contextual for Context {
|
|||
ContextOp::RemoveStyleSheet(path) => {
|
||||
self.stylesheets.remove(path);
|
||||
}
|
||||
// JavaScripts.
|
||||
// Scripts JavaScript.
|
||||
ContextOp::AddJavaScript(js) => {
|
||||
self.javascripts.add(js);
|
||||
}
|
||||
|
|
@ -479,8 +474,8 @@ impl Contextual for Context {
|
|||
}
|
||||
|
||||
#[builder_fn]
|
||||
fn with_child_in(mut self, region_key: &'static str, op: ChildOp) -> Self {
|
||||
self.regions.alter_child_in(region_key, op);
|
||||
fn with_child_in(mut self, region_name: impl AsRef<str>, op: ChildOp) -> Self {
|
||||
self.regions.alter_child_in(region_name, op);
|
||||
self
|
||||
}
|
||||
|
||||
|
|
@ -494,8 +489,8 @@ impl Contextual for Context {
|
|||
self.theme
|
||||
}
|
||||
|
||||
fn layout(&self) -> &str {
|
||||
self.layout
|
||||
fn template(&self) -> &str {
|
||||
self.template
|
||||
}
|
||||
|
||||
/// Recupera un parámetro como [`Option`], simplificando el acceso.
|
||||
|
|
|
|||
|
|
@ -1,25 +1,24 @@
|
|||
//! API para añadir y gestionar nuevos temas.
|
||||
//!
|
||||
//! En PageTop un tema es la *piel* de la aplicación, decide cómo se muestra cada documento HTML,
|
||||
//! especialmente las páginas de contenido ([`Page`](crate::response::page::Page)), sin alterar la
|
||||
//! lógica interna de sus componentes.
|
||||
//! 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.).
|
||||
//!
|
||||
//! Un tema **declara las regiones** (*cabecera*, *barra lateral*, *pie*, etc.) que estarán
|
||||
//! disponibles para colocar contenido. Los temas son responsables últimos de los estilos,
|
||||
//! tipografías, espaciados y cualquier otro detalle visual o de comportamiento (como animaciones,
|
||||
//! scripts de interfaz, etc.).
|
||||
//! 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.
|
||||
//!
|
||||
//! 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
|
||||
//! registrarlos como temas.
|
||||
|
||||
mod definition;
|
||||
pub use definition::{Theme, ThemePage, ThemeRef, DefaultRegions};
|
||||
pub use definition::{Theme, ThemeRef};
|
||||
|
||||
mod regions;
|
||||
pub(crate) use regions::{ChildrenInRegions, REGION_CONTENT};
|
||||
pub use regions::{InRegion, Region, RegionRef};
|
||||
pub(crate) use regions::ChildrenInRegions;
|
||||
pub use regions::InRegion;
|
||||
|
||||
pub(crate) mod all;
|
||||
|
|
|
|||
|
|
@ -1,129 +1,136 @@
|
|||
use crate::core::component::{ContextOp, Contextual};
|
||||
use crate::base::component::Template;
|
||||
use crate::core::component::{ComponentRender, ContextOp, Contextual};
|
||||
use crate::core::extension::Extension;
|
||||
use crate::core::theme::{Region, RegionRef, REGION_CONTENT};
|
||||
use crate::global;
|
||||
use crate::html::{html, Markup, StyleSheet};
|
||||
use crate::locale::L10n;
|
||||
use crate::response::page::Page;
|
||||
use crate::{global, join, AutoDefault};
|
||||
|
||||
use std::sync::LazyLock;
|
||||
|
||||
/// 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`].
|
||||
/// 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;
|
||||
|
||||
/// Conjunto de regiones predefinidas que los temas pueden exponer para el renderizado.
|
||||
/// Interfaz común que debe implementar cualquier tema de PageTop.
|
||||
///
|
||||
/// `DefaultRegions` define un conjunto de regiones predefinidas para estructurar un documento HTML.
|
||||
/// Proporciona **identificadores estables** (vía [`Region::key()`]) y **etiquetas localizables**
|
||||
/// (vía [`Region::label()`]) a las regiones donde se añadirán los componentes.
|
||||
/// 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.
|
||||
///
|
||||
/// Se usa por defecto en [`Theme::page_regions()`](crate::core::theme::Theme::page_regions) y sus
|
||||
/// variantes representan el conjunto mínimo recomendado para cualquier tema. Sin embargo, cada tema
|
||||
/// podría exponer su propio conjunto de regiones.
|
||||
#[derive(AutoDefault)]
|
||||
pub enum DefaultRegions {
|
||||
/// Cabecera de la página.
|
||||
/// 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:
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
/// pub struct MyTheme;
|
||||
///
|
||||
/// impl Extension for MyTheme {
|
||||
/// fn name(&self) -> L10n {
|
||||
/// L10n::n("My theme")
|
||||
/// }
|
||||
///
|
||||
/// fn description(&self) -> L10n {
|
||||
/// L10n::n("A personal theme")
|
||||
/// }
|
||||
///
|
||||
/// fn theme(&self) -> Option<ThemeRef> {
|
||||
/// Some(&Self)
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// impl Theme for MyTheme {}
|
||||
/// ```
|
||||
pub trait Theme: Extension + Send + Sync {
|
||||
/// Acciones específicas del tema antes de renderizar el `<body>` de la página.
|
||||
///
|
||||
/// Clave: `"header"`. Suele contener *branding*, navegación principal o avisos globales.
|
||||
Header,
|
||||
|
||||
/// Contenido principal de la página (**obligatoria**).
|
||||
/// 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:
|
||||
///
|
||||
/// Clave: `"content"`. Es el destino por defecto para insertar componentes a nivel de página.
|
||||
#[default]
|
||||
Content,
|
||||
/// - Añadir metadatos o propiedades a la página.
|
||||
/// - Preparar atributos compartidos.
|
||||
/// - Registrar *assets* condicionales en el contexto.
|
||||
#[allow(unused_variables)]
|
||||
fn before_render_page_body(&self, page: &mut Page) {}
|
||||
|
||||
/// Pie de página.
|
||||
/// Renderiza el contenido del `<body>` de la página.
|
||||
///
|
||||
/// Clave: `"footer"`. Suele contener enlaces legales, créditos o navegación secundaria.
|
||||
Footer,
|
||||
}
|
||||
/// 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.
|
||||
///
|
||||
/// Los temas pueden sobrescribir este método para:
|
||||
///
|
||||
/// - Forzar una plantilla concreta en determinadas páginas.
|
||||
/// - Envolver el contenido en marcadores 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())
|
||||
}
|
||||
|
||||
impl Region for DefaultRegions {
|
||||
fn key(&self) -> &str {
|
||||
match self {
|
||||
Self::Header => "header",
|
||||
Self::Content => REGION_CONTENT,
|
||||
Self::Footer => "footer",
|
||||
/// Acciones específicas del tema después de renderizar el `<body>` de la página.
|
||||
///
|
||||
/// Se invoca tras la generación del contenido del `<body>`. Es útil para:
|
||||
///
|
||||
/// - Ajustar o registrar recursos en función de lo que se haya renderizado.
|
||||
/// - 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 añade una serie de hojas de estilo básicas (`normalize.css`,
|
||||
/// `root.css`, `basic.css`) cuando el parámetro `include_basic_assets` de la página está
|
||||
/// activado.
|
||||
#[allow(unused_variables)]
|
||||
fn after_render_page_body(&self, page: &mut Page) {
|
||||
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),
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
fn label(&self) -> L10n {
|
||||
L10n::l(join!("region_", self.key()))
|
||||
}
|
||||
}
|
||||
|
||||
/// Métodos predefinidos de renderizado para las páginas de un tema.
|
||||
///
|
||||
/// Contiene las implementaciones base para renderizar las **secciones** `<head>` y `<body>`. Se
|
||||
/// implementa automáticamente para cualquier tipo que implemente [`Theme`], por lo que normalmente
|
||||
/// no requiere implementación explícita.
|
||||
///
|
||||
/// Si un tema **sobrescribe** uno o más de los siguientes métodos de [`Theme`]:
|
||||
///
|
||||
/// - [`render_page_region()`](Theme::render_page_region),
|
||||
/// - [`render_page_head()`](Theme::render_page_head), o
|
||||
/// - [`render_page_body()`](Theme::render_page_body);
|
||||
///
|
||||
/// puede volver al comportamiento por defecto con una llamada FQS (*Fully Qualified Syntax*) a:
|
||||
///
|
||||
/// - `<Self as ThemePage>::render_region(self, page, region)`,
|
||||
/// - `<Self as ThemePage>::render_body(self, page, self.page_regions())`, o
|
||||
/// - `<Self as ThemePage>::render_head(self, page)`.
|
||||
pub trait ThemePage {
|
||||
/// Renderiza el **contenedor** de una región concreta del `<body>` de la página.
|
||||
/// Renderiza el contenido del `<head>` de la página.
|
||||
///
|
||||
/// Obtiene los componentes asociados a `region.key()` desde el contexto de la página y, si hay
|
||||
/// salida, envuelve el contenido en un contenedor `<div>` predefinido.
|
||||
/// Aunque en una página el `<head>` se encuentra antes del `<body>`, internamente se renderiza
|
||||
/// después para contar con los ajustes que hayan ido acumulando los componentes. Por ejemplo,
|
||||
/// permitiría añadir un archivo de iconos sólo si se ha incluido un icono en la página.
|
||||
///
|
||||
/// Si la región **no produce contenido**, devuelve un `Markup` vacío.
|
||||
/// Por defecto incluye:
|
||||
///
|
||||
/// - La codificación (`charset="utf-8"`).
|
||||
/// - El título, usando el título de la página si existe y, en caso contrario, sólo el nombre de
|
||||
/// la aplicación.
|
||||
/// - La descripción (`<meta name="description">`), si está definida.
|
||||
/// - La etiqueta `viewport` básica para diseño adaptable.
|
||||
/// - Los metadatos (`name`/`content`) y propiedades (`property`/`content`) declarados en la
|
||||
/// página.
|
||||
/// - Todos 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_region(&self, page: &mut Page, region: RegionRef) -> Markup {
|
||||
html! {
|
||||
@let key = region.key();
|
||||
@let output = page.context().render_components_of(key);
|
||||
@if !output.is_empty() {
|
||||
div
|
||||
id=(key)
|
||||
class={ "region region--" (key) }
|
||||
role="region"
|
||||
aria-label=[region.label().lookup(page)]
|
||||
{
|
||||
(output)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Renderiza el **contenido interior** del `<body>` de la página.
|
||||
///
|
||||
/// Recorre `regions` en el **orden declarado** y, para cada región con contenido, delega en
|
||||
/// [`render_region()`](Self::render_region) la generación del contenedor. Las regiones sin
|
||||
/// contenido **no** producen salida. Se asume que cada identificador de región es **único**
|
||||
/// dentro de la página.
|
||||
///
|
||||
/// La etiqueta `<body>` no se incluye aquí; únicamente renderiza su contenido.
|
||||
#[inline]
|
||||
fn render_body(&self, page: &mut Page, regions: &[RegionRef]) -> Markup {
|
||||
html! {
|
||||
@for region in regions {
|
||||
(self.render_region(page, *region))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Renderiza el **contenido interior** del `<head>` de la página.
|
||||
///
|
||||
/// Incluye por defecto las etiquetas básicas (`charset`, `title`, `description`, `viewport`,
|
||||
/// `X-UA-Compatible`), los metadatos (`name/content`) y propiedades (`property/content`),
|
||||
/// además de los recursos CSS/JS de la página.
|
||||
///
|
||||
/// La etiqueta `<head>` no se incluye aquí; únicamente se renderiza su contenido.
|
||||
#[inline]
|
||||
fn render_head(&self, page: &mut Page) -> Markup {
|
||||
fn render_page_head(&self, page: &mut Page) -> Markup {
|
||||
let viewport = "width=device-width, initial-scale=1, shrink-to-fit=no";
|
||||
html! {
|
||||
meta charset="utf-8";
|
||||
|
|
@ -151,155 +158,20 @@ pub trait ThemePage {
|
|||
(page.context().render_assets())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Interfaz común que debe implementar cualquier tema de PageTop.
|
||||
///
|
||||
/// Un tema implementa [`Theme`] y los métodos necesarios de [`Extension`]. El único método
|
||||
/// **obligatorio** de `Extension` para un tema es [`theme()`](Extension::theme).
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
/// pub struct MyTheme;
|
||||
///
|
||||
/// impl Extension for MyTheme {
|
||||
/// fn name(&self) -> L10n {
|
||||
/// L10n::n("My theme")
|
||||
/// }
|
||||
///
|
||||
/// fn description(&self) -> L10n {
|
||||
/// L10n::n("A personal theme")
|
||||
/// }
|
||||
///
|
||||
/// fn theme(&self) -> Option<ThemeRef> {
|
||||
/// Some(&Self)
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// impl Theme for MyTheme {}
|
||||
/// ```
|
||||
pub trait Theme: Extension + ThemePage + Send + Sync {
|
||||
/// **Obsoleto desde la versión 0.4.0**: usar [`page_regions()`](Self::page_regions) en su
|
||||
/// lugar.
|
||||
#[deprecated(since = "0.4.0", note = "Use `page_regions()` instead")]
|
||||
fn regions(&self) -> Vec<(&'static str, L10n)> {
|
||||
vec![("content", L10n::l("content"))]
|
||||
}
|
||||
|
||||
/// Declaración ordenada de las regiones disponibles en la página.
|
||||
///
|
||||
/// Retorna una **lista estática** de referencias ([`RegionRef`](crate::core::theme::RegionRef))
|
||||
/// que representan las regiones que el tema admite dentro del `<body>`.
|
||||
///
|
||||
/// Cada referencia apunta a una instancia que implementa [`Region`](crate::core::theme::Region)
|
||||
/// para definir cada región de forma segura y estable. Y si un tema necesita un conjunto
|
||||
/// distinto de regiones, puede **sobrescribir** este método siguiendo estas recomendaciones:
|
||||
///
|
||||
/// - Los identificadores devueltos por [`Region::key()`](crate::core::theme::Region::key)
|
||||
/// deben ser **estables** (p. ej. `"sidebar-left"`, `"content"`).
|
||||
/// - La región `"content"` es **obligatoria**, ya que se usa como destino por defecto para
|
||||
/// insertar componentes y renderizarlos.
|
||||
/// - El orden de la lista podría tener relevancia como **orden de renderizado** dentro del
|
||||
/// `<body>` segun la implementación de [`render_page_body()`](Self::render_page_body).
|
||||
/// - Las etiquetas (`L10n`) de cada región se evaluarán con el idioma activo de la página.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// fn page_regions(&self) -> &'static [RegionRef] {
|
||||
/// static REGIONS: LazyLock<[RegionRef; 4]> = LazyLock::new(|| {
|
||||
/// [
|
||||
/// &DefaultRegions::Header,
|
||||
/// &DefaultRegions::Content,
|
||||
/// &DefaultRegions::Footer,
|
||||
/// ]
|
||||
/// });
|
||||
/// &*REGIONS
|
||||
/// }
|
||||
/// ```
|
||||
fn page_regions(&self) -> &'static [RegionRef] {
|
||||
static REGIONS: LazyLock<[RegionRef; 3]> = LazyLock::new(|| {
|
||||
[
|
||||
&DefaultRegions::Header,
|
||||
&DefaultRegions::Content,
|
||||
&DefaultRegions::Footer,
|
||||
]
|
||||
});
|
||||
&*REGIONS
|
||||
}
|
||||
|
||||
/// Renderiza una región de la página.
|
||||
///
|
||||
/// Si se sobrescribe este método, se puede volver al comportamiento base con:
|
||||
/// `<Self as ThemePage>::render_region(self, page, region)`.
|
||||
#[inline]
|
||||
fn render_page_region(&self, page: &mut Page, region: RegionRef) -> Markup {
|
||||
<Self as ThemePage>::render_region(self, page, region)
|
||||
}
|
||||
|
||||
/// Acciones específicas del tema antes de renderizar el `<body>` de la página.
|
||||
///
|
||||
/// Útil para preparar clases, inyectar recursos o ajustar metadatos.
|
||||
#[allow(unused_variables)]
|
||||
fn before_render_page_body(&self, page: &mut Page) {}
|
||||
|
||||
/// Renderiza el contenido del `<body>` de la página.
|
||||
///
|
||||
/// Si se sobrescribe este método, se puede volver al renderizado base con:
|
||||
/// `<Self as ThemePage>::render_body(self, page, self.page_regions())`.
|
||||
#[inline]
|
||||
fn render_page_body(&self, page: &mut Page) -> Markup {
|
||||
<Self as ThemePage>::render_body(self, page, self.page_regions())
|
||||
}
|
||||
|
||||
/// Acciones específicas del tema después de renderizar el `<body>` de la página.
|
||||
///
|
||||
/// Útil para *tracing*, métricas o ajustes finales del estado de la página.
|
||||
#[allow(unused_variables)]
|
||||
fn after_render_page_body(&self, page: &mut Page) {}
|
||||
|
||||
/// Renderiza el contenido del `<head>` de la página.
|
||||
///
|
||||
/// Si se sobrescribe este método, se puede volver al renderizado base con:
|
||||
/// `<Self as ThemePage>::render_head(self, page)`.
|
||||
#[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),
|
||||
));
|
||||
}
|
||||
<Self as ThemePage>::render_head(self, page)
|
||||
}
|
||||
|
||||
/// Contenido predeterminado para la página de error "*403 - Forbidden*".
|
||||
///
|
||||
/// Se puede sobrescribir este método para personalizar y adaptar este contenido al tema.
|
||||
/// Los temas pueden sobrescribir este método para personalizar el diseño y el contenido de la
|
||||
/// página de error, manteniendo o no el mensaje de los textos localizados.
|
||||
fn error403(&self, page: &mut Page) -> Markup {
|
||||
html! { div { h1 { (L10n::l("error403_notice").using(page)) } } }
|
||||
}
|
||||
|
||||
/// Contenido predeterminado para la página de error "*404 - Not Found*".
|
||||
///
|
||||
/// Se puede sobrescribir este método para personalizar y adaptar este contenido al tema.
|
||||
/// Los temas pueden sobrescribir este método para personalizar el diseño y el contenido de la
|
||||
/// página de error, manteniendo o no el mensaje de los textos localizados.
|
||||
fn error404(&self, page: &mut Page) -> Markup {
|
||||
html! { div { h1 { (L10n::l("error404_notice").using(page)) } } }
|
||||
}
|
||||
}
|
||||
|
||||
/// Se implementa automáticamente `ThemePage` para cualquier tema.
|
||||
impl<T: Theme> ThemePage for T {}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
use crate::base::component::Region;
|
||||
use crate::core::component::{Child, ChildOp, Children};
|
||||
use crate::core::theme::ThemeRef;
|
||||
use crate::locale::L10n;
|
||||
use crate::{builder_fn, AutoDefault, UniqueId};
|
||||
|
||||
use parking_lot::RwLock;
|
||||
|
|
@ -16,97 +16,36 @@ static THEME_REGIONS: LazyLock<RwLock<HashMap<UniqueId, ChildrenInRegions>>> =
|
|||
static COMMON_REGIONS: LazyLock<RwLock<ChildrenInRegions>> =
|
||||
LazyLock::new(|| RwLock::new(ChildrenInRegions::default()));
|
||||
|
||||
/// Nombre de la región de contenido por defecto (`"content"`).
|
||||
pub const REGION_CONTENT: &str = "content";
|
||||
|
||||
/// Define la interfaz mínima que describe una **región de renderizado** dentro de una página.
|
||||
///
|
||||
/// Una *región* representa una zona del documento HTML (por ejemplo: `"header"`, `"content"` o
|
||||
/// `"sidebar-left"`), en la que se pueden incluir y renderizar componentes dinámicamente.
|
||||
///
|
||||
/// Este `trait` abstrae los metadatos básicos de cada región, esencialmente:
|
||||
///
|
||||
/// - su **clave interna** (`key()`), que la identifica de forma única dentro de la página, y
|
||||
/// - su **etiqueta localizada** (`label()`), que se usa como texto accesible (por ejemplo en
|
||||
/// `aria-label` o en descripciones semánticas del contenedor).
|
||||
///
|
||||
/// Las implementaciones típicas son *enumeraciones estáticas* declaradas por cada tema (ver como
|
||||
/// ejemplo [`DefaultRegions`](crate::core::theme::DefaultRegions)), de modo que las claves y
|
||||
/// etiquetas permanecen inmutables y fácilmente referenciables.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
/// pub enum MyThemeRegions {
|
||||
/// Header,
|
||||
/// Content,
|
||||
/// Footer,
|
||||
/// }
|
||||
///
|
||||
/// impl Region for MyThemeRegions {
|
||||
/// fn key(&self) -> &str {
|
||||
/// match self {
|
||||
/// Self::Header => "header",
|
||||
/// Self::Content => "content",
|
||||
/// Self::Footer => "footer",
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// fn label(&self) -> L10n {
|
||||
/// L10n::l(join!("region__", self.key()))
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub trait Region: Send + Sync {
|
||||
/// Devuelve la **clave interna** que identifica de forma única una región.
|
||||
///
|
||||
/// La clave se utiliza para asociar los componentes de la región con su contenedor HTML
|
||||
/// correspondiente. Por convención, se emplean nombres en minúsculas y con guiones (`"header"`,
|
||||
/// `"main"`, `"sidebar-right"`, etc.), y la región `"content"` es **obligatoria** en todos los
|
||||
/// temas.
|
||||
fn key(&self) -> &str;
|
||||
|
||||
/// Devuelve la **etiqueta localizada** (`L10n`) asociada a la región.
|
||||
///
|
||||
/// Esta etiqueta se evalúa en el idioma activo de la página y se utiliza principalmente para
|
||||
/// accesibilidad, como el valor de `aria-label` en el contenedor generado por
|
||||
/// [`ThemePage::render_region()`](crate::core::theme::ThemePage::render_region).
|
||||
fn label(&self) -> L10n;
|
||||
}
|
||||
|
||||
/// Referencia estática a una región.
|
||||
pub type RegionRef = &'static dyn Region;
|
||||
|
||||
// Contenedor interno de componentes agrupados por región.
|
||||
#[derive(AutoDefault)]
|
||||
pub struct ChildrenInRegions(HashMap<&'static str, Children>);
|
||||
pub(crate) struct ChildrenInRegions(HashMap<String, Children>);
|
||||
|
||||
impl ChildrenInRegions {
|
||||
pub fn with(region_key: &'static str, child: Child) -> Self {
|
||||
ChildrenInRegions::default().with_child_in(region_key, ChildOp::Add(child))
|
||||
pub fn with(region_name: impl AsRef<str>, child: Child) -> Self {
|
||||
Self::default().with_child_in(region_name, ChildOp::Add(child))
|
||||
}
|
||||
|
||||
#[builder_fn]
|
||||
pub fn with_child_in(mut self, region_key: &'static str, op: ChildOp) -> Self {
|
||||
if let Some(region) = self.0.get_mut(region_key) {
|
||||
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) {
|
||||
region.alter_child(op);
|
||||
} else {
|
||||
self.0.insert(region_key, Children::new().with_child(op));
|
||||
self.0
|
||||
.insert(name.to_owned(), Children::new().with_child(op));
|
||||
}
|
||||
self
|
||||
}
|
||||
|
||||
pub fn merge_all_components(&self, theme_ref: ThemeRef, region_key: &'static str) -> Children {
|
||||
pub fn children_for(&self, theme_ref: ThemeRef, region_name: impl AsRef<str>) -> Children {
|
||||
let name = region_name.as_ref();
|
||||
let common = COMMON_REGIONS.read();
|
||||
if let Some(r) = THEME_REGIONS.read().get(&theme_ref.type_id()) {
|
||||
Children::merge(&[
|
||||
common.0.get(region_key),
|
||||
self.0.get(region_key),
|
||||
r.0.get(region_key),
|
||||
])
|
||||
let themed = THEME_REGIONS.read();
|
||||
|
||||
if let Some(r) = themed.get(&theme_ref.type_id()) {
|
||||
Children::merge(&[common.0.get(name), self.0.get(name), r.0.get(name)])
|
||||
} else {
|
||||
Children::merge(&[common.0.get(region_key), self.0.get(region_key)])
|
||||
Children::merge(&[common.0.get(name), self.0.get(name)])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -120,10 +59,10 @@ impl ChildrenInRegions {
|
|||
/// estas regiones, como las páginas de contenido ([`Page`](crate::response::page::Page)).
|
||||
pub enum InRegion {
|
||||
/// Región de contenido por defecto.
|
||||
Content,
|
||||
/// Región identificada por la clave proporcionado.
|
||||
Key(&'static str),
|
||||
/// Región identificada por una clave para un tema concreto.
|
||||
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),
|
||||
}
|
||||
|
||||
|
|
@ -135,39 +74,38 @@ impl InRegion {
|
|||
/// ```rust
|
||||
/// # use pagetop::prelude::*;
|
||||
/// // Banner global, en la región por defecto de cualquier página.
|
||||
/// InRegion::Content.add(Child::with(Html::with(|_|
|
||||
/// InRegion::Default.add(Child::with(Html::with(|_|
|
||||
/// html! { ("🎉 ¡Bienvenido!") }
|
||||
/// )));
|
||||
///
|
||||
/// // Texto en la región "sidebar".
|
||||
/// InRegion::Key("sidebar").add(Child::with(Html::with(|_|
|
||||
/// InRegion::Named("sidebar").add(Child::with(Html::with(|_|
|
||||
/// html! { ("Publicidad") }
|
||||
/// )));
|
||||
/// ```
|
||||
pub fn add(&self, child: Child) -> &Self {
|
||||
match self {
|
||||
InRegion::Content => {
|
||||
COMMON_REGIONS
|
||||
.write()
|
||||
.alter_child_in(REGION_CONTENT, ChildOp::Add(child));
|
||||
}
|
||||
InRegion::Key(region_key) => {
|
||||
COMMON_REGIONS
|
||||
.write()
|
||||
.alter_child_in(region_key, ChildOp::Add(child));
|
||||
}
|
||||
InRegion::OfTheme(region_key, theme_ref) => {
|
||||
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) => {
|
||||
let mut regions = THEME_REGIONS.write();
|
||||
if let Some(r) = regions.get_mut(&theme_ref.type_id()) {
|
||||
r.alter_child_in(region_key, ChildOp::Add(child));
|
||||
r.alter_child_in(region_name, ChildOp::Add(child));
|
||||
} else {
|
||||
regions.insert(
|
||||
theme_ref.type_id(),
|
||||
ChildrenInRegions::with(region_key, child),
|
||||
ChildrenInRegions::with(region_name, child),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
self
|
||||
}
|
||||
|
||||
#[inline]
|
||||
fn add_to_common(region_name: &str, child: Child) {
|
||||
COMMON_REGIONS
|
||||
.write()
|
||||
.alter_child_in(region_name, ChildOp::Add(child));
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue