♻️ (pagetop): Separa handle_component() en 2 métodos
`Theme::handle_component()` se divide en `setup_component()` (síncrono, muta por tipo con la macro homónima) y `render_component()` (async, decide el renderizado con su propia macro). Aplica mismo criterio que ya separa `Component::setup()` de `prepare()`.
This commit is contained in:
parent
1e2d171805
commit
28f1eee391
15 changed files with 185 additions and 170 deletions
|
|
@ -236,38 +236,53 @@ pub trait Theme: Extension + Send + Sync {
|
|||
}
|
||||
}
|
||||
|
||||
/// Permite al tema intervenir en el ciclo de renderizado de un componente.
|
||||
/// Permite al tema modificar un componente antes de decidir cómo renderizarlo.
|
||||
///
|
||||
/// Este método tiene especial utilidad en los **temas hijo** porque permite ajustar el estado
|
||||
/// de un componente concreto sin modificar el resto del comportamiento heredado.
|
||||
///
|
||||
/// Recibe una referencia mutable al componente (como objeto dinámico [`Component`]) y el
|
||||
/// contexto de renderizado. Se ejecuta en cada tema de la cadena (hijo > padre > abuelo...), en
|
||||
/// ese orden, justo antes de que ese mismo nivel decida si renderiza el componente con
|
||||
/// [`render_component()`](Self::render_component). La implementación por defecto no hace nada.
|
||||
///
|
||||
/// Usa la macro [`setup_component!`](crate::setup_component) para mutar por tipo:
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// fn setup_component(&self, component: &mut dyn Component, cx: &mut Context) {
|
||||
/// setup_component!(component, {
|
||||
/// Button => |btn| { btn.add_class("btn-primary"); },
|
||||
/// });
|
||||
/// }
|
||||
/// ```
|
||||
#[allow(unused_variables)]
|
||||
fn setup_component(&self, component: &mut dyn Component, cx: &mut Context) {}
|
||||
|
||||
/// Permite al tema sobrescribir el renderizado de un componente.
|
||||
///
|
||||
/// Este método tiene especial utilidad en los **temas hijo** porque permite sobrescribir el
|
||||
/// renderizado que el propio componente o el tema padre ofrece para un componente concreto, sin
|
||||
/// modificar el resto del comportamiento heredado.
|
||||
///
|
||||
/// Recibe una referencia mutable al componente (como objeto dinámico [`Component`]) y el
|
||||
/// contexto de renderizado. Devuelve:
|
||||
/// Recibe una referencia compartida al componente (como objeto dinámico [`Component`]), ya con
|
||||
/// las modificaciones de [`setup_component()`](Self::setup_component) del mismo nivel
|
||||
/// aplicadas, y el contexto de renderizado. Devuelve:
|
||||
///
|
||||
/// - `None` si este tema no sobrescribe el renderizado. Es la implementación por defecto. El
|
||||
/// sistema continúa con el siguiente tema de la cadena y, si ninguno lo sobrescribe, usa
|
||||
/// [`Component::prepare()`](crate::core::component::Component::prepare).
|
||||
/// El tema puede mutar el componente antes de devolver `None`, dejando que otro nivel de la
|
||||
/// cadena se encargue del renderizado.
|
||||
/// - `Some(Ok(markup))` con el HTML generado por el tema para el componente.
|
||||
/// - `Some(Err(e))` si el tema intentó renderizarlo pero falló.
|
||||
///
|
||||
/// Para renderizar usa [`render_component!`](crate::render_component), que devuelve `None` si
|
||||
/// ningún tipo coincide. Para mutar sin renderizar usa
|
||||
/// [`setup_component!`](crate::setup_component) y devuelve `None` explícitamente:
|
||||
/// Usa la macro [`render_component!`](crate::render_component), que devuelve `None` si ningún
|
||||
/// tipo coincide:
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// fn handle_component(
|
||||
/// fn render_component(
|
||||
/// &self,
|
||||
/// component: &mut dyn Component,
|
||||
/// component: &dyn Component,
|
||||
/// cx: &mut Context,
|
||||
/// ) -> Option<Result<Markup, ComponentError>> {
|
||||
/// // Sólo mutación: ajusta el componente y deja que otro nivel lo renderice.
|
||||
/// setup_component!(component, {
|
||||
/// Button => |btn| { btn.add_class("btn-primary"); },
|
||||
/// });
|
||||
/// // O renderizado completo:
|
||||
/// render_component!(component, {
|
||||
/// Button => |btn| Ok(html! { button.btn.btn-primary { (btn.label()) } }),
|
||||
/// Heading => |h| Ok(html! { h2.display-4 { (h.text()) } }),
|
||||
|
|
@ -275,9 +290,9 @@ pub trait Theme: Extension + Send + Sync {
|
|||
/// }
|
||||
/// ```
|
||||
#[allow(unused_variables)]
|
||||
async fn handle_component(
|
||||
async fn render_component(
|
||||
&self,
|
||||
component: &mut dyn Component,
|
||||
component: &dyn Component,
|
||||
cx: &mut Context,
|
||||
) -> Option<Result<Markup, ComponentError>> {
|
||||
None
|
||||
|
|
@ -390,9 +405,47 @@ pub trait Theme: Extension + Send + Sync {
|
|||
/// Referencia estática a un tema.
|
||||
pub type ThemeRef = &'static dyn Theme;
|
||||
|
||||
// **< setup_component! >***************************************************************************
|
||||
|
||||
/// Modifica un componente dentro de [`Theme::setup_component()`].
|
||||
///
|
||||
/// Evalúa `$component` contra cada tipo de componente listado en orden. En cuanto encuentra
|
||||
/// coincidencia, ejecuta el bloque asociado y detiene la evaluación. Si ningún tipo coincide, no
|
||||
/// hace nada.
|
||||
///
|
||||
/// Usa acceso mutable al componente mediante [`downcast_mut`], lo que permite modificar su estado.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// fn setup_component(&self, component: &mut dyn Component, cx: &mut Context) {
|
||||
/// setup_component!(component, { Button => |btn| { btn.add_class("btn-primary"); } });
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// El tipo mutado aquí puede además renderizarse en [`Theme::render_component()`] del mismo tema,
|
||||
/// que se ejecuta a continuación sobre el componente ya mutado.
|
||||
///
|
||||
/// [`Theme::setup_component()`]: crate::core::theme::Theme::setup_component
|
||||
/// [`downcast_mut`]: crate::core::AnyCast::downcast_mut
|
||||
/// [`Theme::render_component()`]: crate::core::theme::Theme::render_component
|
||||
#[macro_export]
|
||||
macro_rules! setup_component {
|
||||
($component:expr, { $($type:ty => |$var:ident| $body:expr),* $(,)? }) => {
|
||||
'setup_component: {
|
||||
$(
|
||||
if let Some($var) = ($component).downcast_mut::<$type>() {
|
||||
$body;
|
||||
break 'setup_component;
|
||||
}
|
||||
)*
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// **< render_component! >**************************************************************************
|
||||
|
||||
/// Sobrescribe el renderizado de componentes en [`Theme::handle_component()`].
|
||||
/// Sobrescribe el renderizado de componentes en [`Theme::render_component()`].
|
||||
///
|
||||
/// Evalúa `$component` contra cada tipo de componente listado en orden. En cuanto encuentra
|
||||
/// coincidencia, devuelve `Some(Ok(markup))` o `Some(Err(e))` según el resultado de la expresión
|
||||
|
|
@ -402,7 +455,7 @@ pub type ThemeRef = &'static dyn Theme;
|
|||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// fn handle_component(
|
||||
/// fn render_component(
|
||||
/// &self,
|
||||
/// component: &dyn Component,
|
||||
/// cx: &mut Context,
|
||||
|
|
@ -417,15 +470,14 @@ pub type ThemeRef = &'static dyn Theme;
|
|||
/// Ok(html! { h2.display-4 { (h.text()) } })
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// [`Theme::render_component()`]: crate::core::theme::Theme::render_component
|
||||
#[macro_export]
|
||||
macro_rules! render_component {
|
||||
($component:expr, { $($type:ty => |$var:ident| $body:expr),* $(,)? }) => {
|
||||
'render_component: {
|
||||
// Reborrow explícito como referencia compartida para que `downcast_ref` funcione
|
||||
// correctamente con `&mut dyn Component` (limitación del compilador con trait objects).
|
||||
let __c = &*($component);
|
||||
$(
|
||||
if let Some($var) = __c.downcast_ref::<$type>() {
|
||||
if let Some($var) = ($component).downcast_ref::<$type>() {
|
||||
break 'render_component Some($body);
|
||||
}
|
||||
)*
|
||||
|
|
@ -433,62 +485,3 @@ macro_rules! render_component {
|
|||
}
|
||||
};
|
||||
}
|
||||
|
||||
// **< setup_component! >***************************************************************************
|
||||
|
||||
/// Muta un componente dentro de [`Theme::handle_component()`].
|
||||
///
|
||||
/// Evalúa `$component` contra cada tipo de componente listado en orden. En cuanto encuentra
|
||||
/// coincidencia, ejecuta el bloque asociado y detiene la evaluación. Si ningún tipo coincide, no
|
||||
/// hace nada.
|
||||
///
|
||||
/// Usa acceso mutable al componente mediante [`downcast_mut`](crate::core::AnyCast::downcast_mut),
|
||||
/// lo que permite modificar su estado. El tema puede devolver `None` tras la mutación para que otro
|
||||
/// nivel de la cadena se encargue del renderizado.
|
||||
///
|
||||
/// # Ejemplos
|
||||
///
|
||||
/// Solo mutación: el tema ajusta el componente y delega el renderizado al siguiente nivel:
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// fn handle_component(
|
||||
/// &self,
|
||||
/// component: &mut dyn Component,
|
||||
/// cx: &mut Context,
|
||||
/// ) -> Option<Result<Markup, ComponentError>> {
|
||||
/// setup_component!(component, { Button => |btn| { btn.add_class("btn-primary"); } });
|
||||
/// None
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Mutación y renderizado combinados: el `Button` se muta y se renderiza aquí; el `Heading` se
|
||||
/// muta pero continúa la cadena para que otro nivel lo renderice:
|
||||
///
|
||||
/// ```rust,ignore
|
||||
/// fn handle_component(
|
||||
/// &self,
|
||||
/// component: &mut dyn Component,
|
||||
/// cx: &mut Context,
|
||||
/// ) -> Option<Result<Markup, ComponentError>> {
|
||||
/// setup_component!(component, {
|
||||
/// Button => |btn| { btn.add_class("btn-primary"); },
|
||||
/// Heading => |h| { h.add_class("display-4"); },
|
||||
/// });
|
||||
/// render_component!(component, {
|
||||
/// Button => |btn| Ok(html! { button.btn { (btn.label()) } }),
|
||||
/// })
|
||||
/// }
|
||||
/// ```
|
||||
#[macro_export]
|
||||
macro_rules! setup_component {
|
||||
($component:expr, { $($type:ty => |$var:ident| $body:expr),* $(,)? }) => {
|
||||
'setup_component: {
|
||||
$(
|
||||
if let Some($var) = ($component).downcast_mut::<$type>() {
|
||||
$body;
|
||||
break 'setup_component;
|
||||
}
|
||||
)*
|
||||
}
|
||||
};
|
||||
}
|
||||
|
|
|
|||
|
|
@ -21,14 +21,14 @@ use crate::locale::Lc;
|
|||
///
|
||||
/// Requiere [`AnyInfo`] para que un [`RegionRef`] pueda recuperarse mediante
|
||||
/// [`AnyCast::downcast_ref()`] hacia su tipo concreto (por ejemplo, para que un tema distinga en
|
||||
/// [`Theme::handle_component()`] qué variante concreta está renderizando el componente [`Region`]).
|
||||
/// [`Theme::render_component()`] qué variante concreta está renderizando el componente [`Region`]).
|
||||
///
|
||||
/// [`Context`]: crate::core::component::Context
|
||||
/// [`Contextual::with_child_in()`]: crate::core::component::Contextual::with_child_in
|
||||
/// [`ReservedRegions`]: crate::response::ReservedRegions
|
||||
/// [`Page`]: crate::response::Page
|
||||
/// [`AnyCast::downcast_ref()`]: crate::core::AnyCast::downcast_ref
|
||||
/// [`Theme::handle_component()`]: crate::core::theme::Theme::handle_component
|
||||
/// [`Theme::render_component()`]: crate::core::theme::Theme::render_component
|
||||
/// [`Region`]: crate::base::component::layout::Region
|
||||
pub trait RegionName: Send + Sync + AnyInfo {
|
||||
/// Devuelve el nombre de la región.
|
||||
|
|
@ -117,14 +117,18 @@ impl RegionName for CoreRegions {
|
|||
/// Interfaz común para las plantillas lógicas de una página.
|
||||
///
|
||||
/// Representa una variante identificada por un nombre. Un tema puede usar este nombre para decidir
|
||||
/// la composición del cuerpo de una página ([`Page`](crate::response::Page)), es decir, qué
|
||||
/// regiones ([`RegionName`]) renderizar y en qué orden.
|
||||
/// la composición del cuerpo de una página ([`Page`]), es decir, qué regiones ([`RegionName`])
|
||||
/// renderizar y en qué orden.
|
||||
///
|
||||
/// Requiere [`AnyInfo`] por el mismo motivo que [`RegionName`], para que un [`TemplateRef`] 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 [`Template`](crate::base::component::layout::Template)).
|
||||
/// recuperarse mediante [`AnyCast::downcast_ref()`] hacia su tipo concreto (por ejemplo, para que
|
||||
/// un tema distinga en [`Theme::render_component()`] qué variante concreta está renderizando el
|
||||
/// componente [`Template`]).
|
||||
///
|
||||
/// [`Page`]: crate::response::Page
|
||||
/// [`AnyCast::downcast_ref()`]: crate::core::AnyCast::downcast_ref
|
||||
/// [`Theme::render_component()`]: crate::core::theme::Theme::render_component
|
||||
/// [`Template`]: crate::base::component::layout::Template
|
||||
pub trait TemplateName: Send + Sync + AnyInfo {
|
||||
/// Devuelve el nombre de la plantilla.
|
||||
fn name(&self) -> &'static str;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue