✨ 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

@ -23,6 +23,13 @@ pub type FnActionWithComponent<C> = fn(component: &mut C, cx: &mut Context);
///
/// Devuelve el nuevo [`Markup`] transformado, que se encadena como entrada para la siguiente acción
/// registrada, si la hay.
///
/// Dentro de una página, el [`Markup`] puede contener marcas asociadas a componentes aplazados (en
/// forma de comentarios HTML `<!-- placeholder ... -->`, ver [`Component::is_deferred()`]) en lugar
/// de su HTML correspondiente. Una transformación debe respetarlas para que estos componentes se
/// muestren en su sitio al renderizarse.
///
/// [`Component::is_deferred()`]: crate::core::component::Component::is_deferred
pub type FnActionTransformMarkup<C> = fn(component: &C, cx: &Context, markup: Markup) -> Markup;
mod before_render_component;

View file

@ -5,13 +5,25 @@ use std::fmt;
/// Componente que renderiza una región del `<body>`.
///
/// No recibe ningún contenido de quien lo construye. Lo obtiene directamente del [`Context`] en el
/// momento de renderizarse (ver [`Context::render_region()`]). Si la región no tiene contenido, no
/// se renderiza nada.
/// momento de renderizarse (ver [`Context::render_region()`]). Salvo `Content` (ver más abajo), si
/// la región no tiene contenido, no renderiza nada.
///
/// Si un tema necesita maquetar una región determinada de forma distinta, puede capturar este
/// componente en [`Theme::render_component()`](crate::core::theme::Theme::render_component) y
/// hacer [`downcast_ref()`](crate::core::AnyCast::downcast_ref) sobre el [`RegionRef`] que devuelve
/// [`Self::region()`], para compararlo con la variante deseada.
/// [`Self::region()`], y compararlo con la variante deseada.
///
/// Por defecto, el renderizado de [`CoreRegions::Content`] añade al inicio un componente
/// [`Messages`] aplazado (ver [`Messages::with_deferred()`]) para mostrar los mensajes pendientes
/// al usuario. Por eso, en una página, `Content` se renderiza siempre, aunque esté vacía y no haya
/// mensajes, ya que queda la marca del componente aplazado como un comentario HTML. Como los
/// elementos que sólo contienen comentarios cumplen el selector CSS `:empty`, un tema puede ocultar
/// las regiones vacías usando la regla `.region:empty { display: none; }`.
///
/// Para llevar los mensajes a otro lugar, un tema puede capturar este componente, renderizar
/// `Content` sin el [`Messages`] y añadirlo a otra región o directamente a la plantilla, con
/// [`Messages::with_deferred()`] para que siga recogiendo todos los mensajes. Si se captura
/// `Content` por otro motivo, hay que incluir el [`Messages`] para no perder los mensajes.
///
/// Como cualquier otro componente, participa también en el despacho de las
/// [acciones de componentes](crate::base::action::component) para que otras extensiones puedan
@ -37,6 +49,9 @@ use std::fmt;
/// let header = layout::Region::header();
/// let sidebar = layout::Region::of(&Sidebar);
/// ```
///
/// [`Messages`]: crate::base::component::Messages
/// [`Messages::with_deferred()`]: crate::base::component::Messages::with_deferred
#[derive(Clone, Getters)]
pub struct Region {
/// Devuelve la región subyacente.
@ -73,7 +88,15 @@ impl Component for Region {
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
let name = self.region().name();
let content = cx.render_region(self.region()).await;
// Por el nombre, como el contenido de las regiones (ver `RegionName`).
let content = if name == CoreRegions::Content.name() {
html! {
(Messages::new().with_deferred(true).render(cx).await)
(cx.render_region(self.region()).await)
}
} else {
cx.render_region(self.region()).await
};
Ok(html! {
@if !content.is_empty() {
div

View file

@ -3,28 +3,60 @@ use crate::prelude::*;
/// Componente que muestra los **mensajes de usuario** acumulados en el contexto.
///
/// No recibe ningún contenido de quien lo construye. Lo obtiene directamente del [`Context`] (ver
/// [`Context::push_message()`](Context::push_message)) en el momento de renderizarse (ver
/// [`Context::messages()`]). Si no hay ninguno acumulado, no se renderiza nada.
/// [`Context::push_message()`](Context::push_message)) en el momento de renderizarse, y retira los
/// mensajes que muestra para que no se repitan. Si no hay ninguno acumulado, no renderiza nada.
///
/// [`Region`] añade uno al inicio de la región [`CoreRegions::Content`], así que no hace falta
/// incluirlo para ver los mensajes, tampoco los que llegan de la página anterior con
/// [`ResponseExt::with_message()`]. Ese componente está aplazado: se renderiza cuando ya se ha
/// renderizado el resto de la página, así que recoge también los mensajes que añadan los demás
/// componentes, aunque se muestra en su sitio.
///
/// Sólo hay que añadirlo a mano para mostrar los mensajes en un lugar concreto (por ejemplo, junto
/// a un formulario) o en un fragmento HTML que se renderiza sin página. Por defecto no se aplaza;
/// se renderiza en su turno, como cualquier otro componente, y muestra los mensajes acumulados
/// hasta ese momento, que ya no aparecerán al inicio de `Content`. También se puede aplazar con
/// [`with_deferred()`](Self::with_deferred) (ver en [`CoreRegions::Content`] cómo se reparten
/// entonces los mensajes).
///
/// [`Region`]: crate::base::component::layout::Region
///
/// # Clases CSS
///
/// Cada nivel de severidad renderiza siempre las mismas clases fijas: `.message.message-info`,
/// `.message.message-warning` o `.message.message-error`. Será el tema activo quien decide el
/// aspecto visual de cada nivel, proporcionando las reglas CSS para esas clases.
/// `.message.message-warning` o `.message.message-error`. Es el tema activo quien decide el aspecto
/// visual de cada nivel, proporcionando las reglas CSS para esas clases.
///
/// # Ejemplo
/// # Ejemplos
///
/// Los mensajes se muestran al inicio de `Content` sin añadir el componente:
///
/// ```rust,no_run
/// use pagetop::prelude::*;
///
/// async fn save_settings(cx: &mut Context) {
/// cx.push_message(MessageLevel::Info, Lc::n("Settings saved."));
/// }
///
/// async fn homepage(request: HttpRequest) -> Result<Markup, ErrorPage> {
/// let mut page = Page::new(request);
/// page.context()
/// .push_message(MessageLevel::Info, Lc::n("Settings saved."));
/// page.with_child(Html::with(|_| html! { p { "..." } }))
/// .render()
/// .await
/// }
/// ```
///
/// Para mostrarlos junto antes de un formulario:
///
/// ```rust,no_run
/// use pagetop::prelude::*;
///
/// async fn contact(request: HttpRequest) -> Result<Markup, ErrorPage> {
/// Page::new(request)
/// .with_child(Messages::new())
/// // ... resto del contenido de la página ...
/// .with_child(
/// Form::new()
/// .with_action("/contact")
/// .with_child(Button::submit(Lc::n("Send"))),
/// )
/// .render()
/// .await
/// }
@ -33,6 +65,8 @@ use crate::prelude::*;
pub struct Messages {
/// Devuelve identificador, clases CSS, atributos HTML y valores extra del componente.
props: Props,
#[getters(skip)]
deferred: bool,
}
#[async_trait]
@ -45,17 +79,22 @@ impl Component for Messages {
self.props.get_id()
}
fn is_deferred(&self) -> bool {
self.deferred
}
fn setup(&mut self, _cx: &mut Context) {
self.alter_prop(PropsOp::prepend_classes("messages"));
}
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
if !cx.has_messages() {
let messages = cx.take_messages();
if messages.is_empty() {
return Ok(html! {});
}
Ok(html! {
div (self.props().unpack(cx)) role="alert" {
@for message in cx.messages() {
@for message in &messages {
div class=(match message.level() {
MessageLevel::Info => "message message-info",
MessageLevel::Warning => "message message-warning",
@ -84,4 +123,16 @@ impl Messages {
self.props.alter_prop(op);
self
}
/// Establece si el componente se aplaza (ver [`Component::is_deferred()`]).
///
/// Dentro de una página, un componente aplazado se renderiza una vez renderizado el resto del
/// `<body>`, aunque se muestre en su sitio, y así recoge también los mensajes que añadan los
/// componentes que se renderizan después. Es lo que hace el que encabeza la región
/// [`CoreRegions::Content`]. Por defecto no se aplaza, y muestra sólo los mensajes acumulados
/// hasta el momento de renderizarse.
pub fn with_deferred(mut self, deferred: bool) -> Self {
self.deferred = deferred;
self
}
}