✨ Mensajes flash y Messages automático en Content

- Componentes aplazados: `Component::is_deferred()` deja una marca
  `<!-- placeholder ... -->` y `Page::render()` los renderiza al final
  del `<body>`, en su sitio. Si no generan nada, la marca se queda.
- `Region` empieza `Content` con un `Messages` aplazado, que recoge
  todos los mensajes de la página. Las aplicaciones ya no tienen que
  añadirlo.
- `Messages` retira los mensajes que muestra y admite `with_deferred()`.
- `ResponseExt::with_message()` deja mensajes para la página siguiente
  en una cookie técnica de vida corta, que sólo se crea si se usa.
- Basic y Bootsier ocultan las regiones vacías con `.region:empty`.
This commit is contained in:
Manuel Cillero 2026-11-02 13:20:36 +01:00
parent a110dd0482
commit c9fdc7afc7
18 changed files with 935 additions and 49 deletions

View file

@ -5,9 +5,10 @@ use crate::core::theme::{ChildrenInRegions, CoreRegions, CoreTemplates, default_
use crate::core::theme::{RegionRef, TemplateRef, ThemeRef};
use crate::datetime::Tz;
use crate::html::{Assets, Favicon, JavaScript, Preload, ResponsiveStyles, StyleSheet};
use crate::html::{Markup, Props, PropsOp, RoutePath, html};
use crate::html::{Markup, PreEscaped, Props, PropsOp, RoutePath, html};
use crate::locale::Lc;
use crate::locale::{LangId, LanguageIdentifier, RequestLocale};
use crate::response::read_flash_messages;
use crate::web::HttpRequest;
use crate::{builder_impl, util};
@ -107,11 +108,20 @@ pub struct Context {
responsives : ResponsiveStyles, // Estilos *responsive*.
body_props : Props, // Id, clases CSS y atributos del <body>.
regions : ChildrenInRegions, // Regiones de componentes para renderizar.
deferred : Option<Deferred>, // Componentes de renderizado aplazado.
params : HashMap<&'static str, (Box<dyn Any + Send + Sync>, &'static str)>, // Parámetros.
id_counters : Mutex<HashMap<TypeId, usize>>, // Mutex permite mutar desde build_id(&self).
messages : Vec<StatusMessage>, // Mensajes de usuario acumulados.
}
// Componentes aplazados mientras se renderiza el `<body>` de una página, cada uno con la marca que
// ocupa su lugar. El valor aleatorio de las marcas las distingue de cualquier comentario HTML que
// traiga el contenido.
struct Deferred {
nonce: u32,
components: Vec<(String, Box<dyn Component>)>,
}
impl Default for Context {
fn default() -> Self {
Self::base(None, &CoreTemplates::Standard)
@ -129,6 +139,10 @@ impl Context {
let current_user = Self::resolve_current_user(request.as_ref());
let timezone = current_user.timezone();
let theme = current_user.theme().unwrap_or_else(default_theme);
let messages = request
.as_ref()
.map(|request| read_flash_messages(request.headers()))
.unwrap_or_default();
Context {
request,
locale,
@ -143,9 +157,10 @@ impl Context {
responsives: ResponsiveStyles::new(),
body_props : Props::default(),
regions : ChildrenInRegions::default(),
deferred : None,
params : HashMap::default(),
id_counters: Mutex::new(HashMap::new()),
messages : Vec::new(),
messages,
}
}
@ -232,6 +247,66 @@ impl Context {
.await
}
// Empieza a aplazar los componentes que lo pidan (`Component::is_deferred()`), mientras
// `Page::render()` renderiza el `<body>`.
pub(crate) fn start_deferring(&mut self) {
use std::hash::{BuildHasher, Hasher, RandomState};
self.deferred = Some(Deferred {
nonce: RandomState::new().build_hasher().finish() as u32,
components: Vec::new(),
});
}
// Guarda un clon del componente para renderizarlo cuando termine el resto del `<body>`, y
// devuelve la marca que ocupa su lugar, o `None` si no se está renderizando una página.
pub(crate) fn defer(&mut self, component: &dyn Component) -> Option<Markup> {
let deferred = self.deferred.as_mut()?;
let mark = format!(
"<!-- placeholder {} {:08x}-{} -->",
component.short_name(),
deferred.nonce,
deferred.components.len()
);
// Se guarda una copia de la marca para buscarla después: clonarla cuesta menos que volver
// a formatearla.
deferred
.components
.push((mark.clone(), component.clone_box()));
Some(PreEscaped(mark))
}
// Deja de aplazar, renderiza los componentes aplazados y sustituye sus marcas en `body`. Un
// componente aplazado que contenga otro lo renderiza ya en el momento.
pub(crate) async fn render_deferred(&mut self, body: Markup) -> Markup {
let Some(deferred) = self.deferred.take() else {
return body;
};
let mut body = body.into_string();
for (mark, mut component) in deferred.components {
let markup = component.render(self).await.into_string();
// Sin nada que mostrar, la marca se queda: es un comentario HTML, y así no hay que
// buscarla ni copiar el cuerpo, que es lo habitual (p. ej. `Messages` sin mensajes).
if markup.is_empty() {
continue;
}
// Una transformación del marcado que quite los comentarios (p. ej. un minificador) la
// haría desaparecer, y sin este aviso el componente no se vería.
let Some(start) = body.find(&mark) else {
crate::trace::warn!(
path = self.request().map(|r| r.path()).unwrap_or("<unknown>"),
component = component.name(),
"deferred component mark not found in the page body, component not shown"
);
continue;
};
// Una sola reserva con la longitud exacta. `String::replace_range()` sería más lento,
// porque copia la inserción byte a byte.
body = util::join!(&body[..start], markup, &body[start + mark.len()..]);
}
PreEscaped(body)
}
// **< Context HELPERS >************************************************************************
/// Construye una ruta aplicada al contexto actual.
@ -300,8 +375,11 @@ impl Context {
/// Acumula un [`StatusMessage`] en el contexto para notificar al usuario.
///
/// Pueden generarse en cualquier punto del ciclo de una petición web (handlers, renderizado,
/// lógica de negocio, etc.) que tengan acceso al contexto, y mostrarlos luego, por ejemplo, en
/// la página final devuelta al usuario.
/// lógica de negocio, etc.) que tengan acceso al contexto. Los muestra, y los retira, el primer
/// componente [`Messages`](crate::base::component::Messages) que se renderice después de
/// añadirlos: uno propio de la página, si lo hay, o el que encabeza la región
/// [`CoreRegions::Content`], que se renderiza una vez renderizado el resto del `<body>` y
/// recoge los que queden.
///
/// # Ejemplo
///
@ -314,15 +392,22 @@ impl Context {
self.messages.push(StatusMessage::new(level, text));
}
/// Devuelve todos los mensajes de usuario acumulados.
/// Devuelve los mensajes de usuario acumulados que aún no ha mostrado ningún componente
/// [`Messages`](crate::base::component::Messages).
pub fn messages(&self) -> &[StatusMessage] {
&self.messages
}
/// Indica si hay mensajes de usuario acumulados.
/// Indica si hay mensajes de usuario acumulados que aún no ha mostrado ningún componente
/// [`Messages`](crate::base::component::Messages).
pub fn has_messages(&self) -> bool {
!self.messages.is_empty()
}
// Retira los mensajes acumulados, para que el componente `Messages` los muestre una sola vez.
pub(crate) fn take_messages(&mut self) -> Vec<StatusMessage> {
std::mem::take(&mut self.messages)
}
}
/// Permite a [`Context`] actuar como proveedor de idioma.
@ -351,6 +436,13 @@ impl Contextual for Context {
// **< Contextual BUILDER >*********************************************************************
fn with_request(mut self, request: Option<HttpRequest>) -> Self {
// Los mensajes para la página siguiente se leen una sola vez, con la primera petición (las
// páginas de error, p. ej., parten de un contexto sin petición).
if self.request.is_none()
&& let Some(request) = &request
{
self.messages.extend(read_flash_messages(request.headers()));
}
self.request = request;
// Recalcula el *locale*, el usuario actual, la zona horaria y el tema según la nueva
// petición y la política de negociación configurada.

View file

@ -87,6 +87,43 @@ pub trait Component: AnyInfo + ComponentClone + ComponentRender + Send + Sync {
true
}
/// Indica si el renderizado del componente se aplaza hasta haber renderizado el resto de la
/// página.
///
/// Si devuelve `true` y el componente forma parte del `<body>` de una página
/// ([`Page::render()`]), su [ciclo de renderizado](ComponentRender) completo se aplaza hasta
/// que se ha renderizado el resto del `<body>`, y el resultado se coloca en el mismo lugar que
/// ocupa el componente. Se aplaza el *momento* del renderizado, no la *posición*. El componente
/// se muestra en su sitio, no al final de la página. Si no se trata de una página, se
/// renderiza en el momento, como cualquier otro componente.
///
/// Mientras tanto, en su lugar queda una marca en forma de comentario HTML usando el patrón
/// `<!-- placeholder ... -->`. Los componentes que lo contienen ven la marca y no su HTML
/// final, y la tratan como contenido aunque el componente acabe sin generar nada. Sus acciones
/// y transformaciones no pueden alterar el resultado del componente, sólo la marca, que deben
/// conservar. Si finalmente el componente no genera nada, la marca se queda en la página. Un
/// contenedor que sólo tenga la marca cumple el selector CSS `:empty`, así que los estilos
/// pueden ocultarlo (ver [`Region`]). Si una transformación de un componente que lo contiene
/// quita la marca (por ejemplo, un minificador que elimine los comentarios), el resultado del
/// componente no se muestra y se registra un aviso en la traza.
///
/// Los componentes aplazados se renderizan en el orden en que se encontraron al renderizar el
/// `<body>` (normalmente, el orden en que aparecen en la página). Un componente aplazado no
/// debe añadir mensajes para el usuario: si se renderiza después del componente [`Messages`]
/// que encabeza la región [`CoreRegions::Content`], no se mostrarán. Un componente aplazado
/// dentro de otro también aplazado no espera: se renderiza en el momento, con el que lo
/// contiene.
///
/// Por defecto, ningún componente se aplaza (`false`).
///
/// [`Page::render()`]: crate::response::Page::render
/// [`Region`]: crate::base::component::layout::Region
/// [`Messages`]: crate::base::component::Messages
/// [`CoreRegions::Content`]: crate::core::theme::CoreRegions::Content
fn is_deferred(&self) -> bool {
false
}
/// Configura el estado interno del componente antes de generar el marcado.
///
/// Segundo paso del [ciclo de renderizado](ComponentRender). Se ejecuta tras comprobar
@ -164,7 +201,10 @@ impl<T: Component + Clone + 'static> ComponentClone for T {
/// Implementa [`render()`] para todos los componentes.
///
/// El proceso de renderizado de cada componente sigue esta secuencia:
/// Si el componente se aplaza ([`is_deferred()`]) y se está renderizando el `<body>` de una página,
/// devuelve una marca que [`Page::render()`] sustituirá por el resultado de este mismo proceso una
/// vez renderizado el resto del `<body>` (si no genera nada, la marca se queda). Si no, el proceso
/// de renderizado de cada componente sigue esta secuencia:
///
/// 1. Ejecuta [`is_renderable()`] para ver si puede renderizarse en el contexto actual. Si no es
/// así, devuelve un [`Markup`] vacío.
@ -183,7 +223,9 @@ impl<T: Component + Clone + 'static> ComponentClone for T {
/// 7. Devuelve el [`Markup`] resultante.
///
/// [`render()`]: ComponentRender::render
/// [`Page::render()`]: crate::response::Page::render
/// [`is_renderable()`]: Component::is_renderable
/// [`is_deferred()`]: Component::is_deferred
/// [`setup()`]: Component::setup
/// [`Component::prepare()`]: Component::prepare
/// [`action::component::BeforeRender<C>`]: crate::base::action::component::BeforeRender
@ -194,6 +236,13 @@ impl<T: Component + Clone + 'static> ComponentClone for T {
#[async_trait]
impl<C: Component> ComponentRender for C {
async fn render(&mut self, cx: &mut Context) -> Markup {
// Si se aplaza, deja una marca y se renderiza al terminar el resto del <body>.
if self.is_deferred()
&& let Some(mark) = cx.defer(&*self)
{
return mark;
}
// Si no es renderizable, devuelve un bloque HTML vacío.
if !self.is_renderable(cx) {
return html! {};