✨ 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

@ -8,7 +8,8 @@ use crate::core::extension::all::StartupError;
use crate::core::theme;
use crate::datetime::Timezone;
use crate::locale::Locale;
use crate::response::{render_error_pages, response_for_panic, route_not_found};
use crate::response::route_not_found;
use crate::response::{keep_flash_messages, render_error_pages, response_for_panic};
use crate::web::{Request, Response, Router, http};
use crate::{PAGETOP_VERSION, global, trace};
@ -255,6 +256,9 @@ impl Application {
// cambio, se registra antes: la página 404 debe ver lo que el middleware añade a la petición
// (p. ej. el usuario actual).
//
// Los mensajes *flash* (`keep_flash_messages()`) se registran junto al middleware de las
// extensiones, también antes de los archivos estáticos, que no los muestran.
//
// El límite del cuerpo de las peticiones (`limit_body()`) sustituye al de Axum en todas las
// rutas.
//
@ -263,7 +267,8 @@ impl Application {
// del propio renderizado de una página de error.
fn build_router() -> Router {
let router = extension::all::configure_routes(Router::new()).fallback(route_not_found);
let router = extension::all::configure_middleware(router);
let router = extension::all::configure_middleware(router)
.layer(axum::middleware::from_fn(keep_flash_messages));
let router = extension::all::configure_static_files(router);
router
.layer(axum::middleware::from_fn(limit_body))

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
}
}

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! {};

View file

@ -75,8 +75,11 @@
//! [`AnyCast::downcast_ref()`](crate::core::AnyCast::downcast_ref) hacia el tipo concreto (por
//! ejemplo, [`CoreTemplates`] o el propio *enum* del tema). `pagetop-bootsier` hace exactamente
//! esto para maquetar `Standard` y `Admin` de forma distinta, sin necesitar sus propias
//! variantes de plantilla. Para ajustarlo sin rehacer su marcado (añadir una clase, un
//! atributo, etc.), se usa [`Theme::setup_component()`] en su lugar.
//! variantes de plantilla. Un tema que componga su propia plantilla debe incluir al menos
//! `Content`, renderizada con el componente [`Region`], que por defecto incluye al inicio de la
//! región el componente [`Messages`] para mostrar automáticamente los mensajes al usuario. Para
//! ajustarlo sin rehacer su marcado (añadir una clase, un atributo, etc.), se usa
//! [`Theme::setup_component()`] en su lugar.
//! 4. **Definir los anchos mínimos *mobile-first* para los puntos de corte** sobrescribiendo
//! [`Theme::breakpoint_entry()`]. [`Breakpoint`] no define ningún ancho propio; la
//! implementación por defecto de este método resuelve el ancho mínimo de cada variante (`Sm`,
@ -151,6 +154,7 @@
//! [`is_renderable()`]: crate::core::component::Component::is_renderable
//! [`Template`]: crate::base::component::layout::Template
//! [`Region`]: crate::base::component::layout::Region
//! [`Messages`]: crate::base::component::Messages
mod intent;
pub use intent::Intent;

View file

@ -24,8 +24,9 @@ pub fn enabled_themes() -> Vec<ThemeRef> {
THEMES.read().clone()
}
/// Devuelve el tema identificado por su [`short_name()`](crate::core::AnyInfo::short_name), si está
/// habilitado, sin distinguir mayúsculas y minúsculas.
/// Devuelve el tema identificado por su [`short_name()`](crate::core::AnyInfo::short_name).
///
/// No distingue mayúsculas y minúsculas, y devuelve `None` si el tema no está habilitado.
pub fn theme_by_short_name(short_name: &str) -> Option<ThemeRef> {
THEMES
.read()
@ -61,14 +62,16 @@ pub(crate) fn init_default_theme() {
}
}
/// Devuelve el tema predeterminado de la aplicación: el configurado en `app.theme` si está
/// habilitado o, en otro caso, [`Basic`](crate::base::theme::Basic). Se fija una sola vez, al
/// arrancar la aplicación, una vez habilitadas las extensiones.
/// Devuelve el tema predeterminado de la aplicación.
///
/// El configurado en `app.theme` si está habilitado o, en otro caso, [`Basic`]. Se fija una sola
/// vez, al arrancar la aplicación, una vez habilitadas las extensiones.
///
/// Es el tema del sitio, no necesariamente el que se usa en una petición concreta: para renderizar,
/// el tema efectivo es el de [`Contextual::theme()`], que tiene en cuenta el tema preferido del
/// usuario ([`CurrentUser::theme()`]).
///
/// [`Basic`]: crate::base::theme::Basic
/// [`Contextual::theme()`]: crate::core::component::Contextual::theme
/// [`CurrentUser::theme()`]: crate::auth::CurrentUser::theme
pub fn default_theme() -> ThemeRef {

View file

@ -80,7 +80,31 @@ pub enum CoreRegions {
/// 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.
/// región mínima imprescindible para que una página tenga sentido, y la única que cualquier
/// plantilla debe incluir.
///
/// [`Region`] le añade por defecto un componente [`Messages`] al inicio, para mostrar al
/// usuario los mensajes acumulados en el [`Context`] (ver [`Context::push_message()`]),
/// incluidos los que llegan de la página anterior (ver [`ResponseExt::with_message()`]). Las
/// aplicaciones no tienen que añadirlo.
///
/// Para poder mostrar todos los mensajes, este componente [`Messages`] se renderiza al final,
/// cuando ya se han renderizado los demás componentes de la página y se han acumulado sus
/// mensajes. Aun así, se muestra en su sitio, al inicio de la región.
///
/// Cada componente [`Messages`] retira los mensajes que muestra, para que no se repitan. Si la
/// página incluye otro (por ejemplo, junto a un formulario), éste muestra los acumulados hasta
/// el momento de renderizarse, esté donde esté, y el del inicio de la región sólo los que se
/// añadan después; si no queda ninguno, no muestra nada. Un [`Messages`] aplazado (ver
/// [`Messages::with_deferred()`]) colocado antes de esta región se renderiza antes que éste y
/// se queda con todos.
///
/// [`Region`]: crate::base::component::layout::Region
/// [`Messages`]: crate::base::component::Messages
/// [`Messages::with_deferred()`]: crate::base::component::Messages::with_deferred
/// [`Context`]: crate::core::component::Context
/// [`Context::push_message()`]: crate::core::component::Context::push_message
/// [`ResponseExt::with_message()`]: crate::response::ResponseExt::with_message
#[default]
Content,

View file

@ -9,5 +9,9 @@ pub use json::*;
mod redirect;
pub use redirect::*;
mod flash;
pub use flash::ResponseExt;
pub(crate) use flash::{keep_flash_messages, read_flash_messages};
mod waypoint;
pub use waypoint::*;

269
src/response/flash.rs Normal file
View file

@ -0,0 +1,269 @@
//! Mensajes para la página siguiente (mensajes *flash*).
//!
//! Viajan en una *cookie* de vida corta, sin guardar nada en el servidor ni necesitar sesión: la
//! respuesta que los añade la crea, la página siguiente los muestra y su respuesta la borra.
use crate::core::component::{Context, MessageLevel, StatusMessage};
use crate::locale::Lc;
use crate::response::ErrorPage;
use crate::trace;
use crate::web::{Request, Response, http, push_percent_encoded};
use axum::middleware::Next;
const COOKIE_NAME: &str = "pagetop_flash";
// Atributos de la *cookie*. Basta con un minuto: es el tiempo de seguir una redirección.
const COOKIE_ATTRS: &str = "; Path=/; HttpOnly; SameSite=Lax; Max-Age=60";
const EXPIRED_COOKIE: &str = "pagetop_flash=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0";
// Los navegadores admiten al menos 4096 bytes por *cookie*, contando nombre y atributos.
const MAX_VALUE_LEN: usize = 3800;
// Separa los mensajes en el valor de la *cookie*: no aparece en el texto codificado.
const SEPARATOR: char = '|';
// Mensajes añadidos a una respuesta con `with_message()`, pendientes de guardar en la *cookie*.
#[derive(Clone, Default)]
struct Pending(Vec<(MessageLevel, String)>);
/// Añade a una respuesta mensajes para mostrar en la página siguiente.
///
/// Es la forma de avisar del resultado de una acción tras redirigir a otra página (cuenta creada,
/// cambios guardados...), como los mensajes *flash* de otros *frameworks*. Los mensajes viajan en
/// una *cookie* de vida corta, ya traducidos al idioma de `cx`, y la página siguiente los añade a
/// su [`Context`] como si se hubieran acumulado con [`Context::push_message()`]. Los muestra el
/// componente [`Messages`] que encabeza la región [`CoreRegions::Content`], o uno propio de la
/// página.
///
/// Si la respuesta siguiente es otra redirección, los mensajes esperan a la página posterior.
///
/// La *cookie* (`pagetop_flash`) sólo se crea cuando una respuesta usa este método; una aplicación
/// que no lo usa no envía ninguna. Es una *cookie* técnica: surge de una acción del usuario, dura
/// como mucho un minuto, se borra en cuanto se muestran los mensajes y no contiene datos que lo
/// identifiquen. Como *cookie* estrictamente necesaria para el servicio que el usuario ha pedido,
/// suele quedar exenta de consentimiento, aunque conviene declararla en la política de *cookies* de
/// la aplicación.
///
/// El texto se muestra siempre como texto plano: el marcado que tenga una traducción aparecería
/// tal cual. Cada mensaje debe ser breve; los que no quepan en la *cookie* (unos 3,8 KB entre
/// todos) se descartan con un aviso en las trazas.
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// async fn save(request: HttpRequest) -> Response {
/// let cx = Context::new(request);
/// // ... guarda los cambios ...
/// Redirect::see_other(cx.route("/settings"))
/// .with_message(&cx, MessageLevel::Info, Lc::n("Settings saved."))
/// }
/// ```
///
/// [`Context::push_message()`]: crate::core::component::Context::push_message
/// [`CoreRegions::Content`]: crate::core::theme::CoreRegions::Content
/// [`Messages`]: crate::base::component::Messages
pub trait ResponseExt {
/// Añade un mensaje para la página siguiente, traducido con el idioma del contexto.
fn with_message(self, cx: &Context, level: MessageLevel, text: Lc) -> Response;
}
impl ResponseExt for Response {
fn with_message(mut self, cx: &Context, level: MessageLevel, text: Lc) -> Response {
if let Some(text) = text.lookup(cx).filter(|text| !text.is_empty()) {
self.extensions_mut()
.get_or_insert_default::<Pending>()
.0
.push((level, text));
}
self
}
}
// Lee los mensajes de la *cookie* de la petición, para el `Context` de la página. Con un valor
// manipulado no hace más que mostrar texto plano, que `Lc::n()` escapa al renderizarse.
pub(crate) fn read_flash_messages(headers: &http::HeaderMap) -> Vec<StatusMessage> {
let Some(value) = cookie_value(headers) else {
return Vec::new();
};
value
.split(SEPARATOR)
.filter_map(|entry| {
let level = match entry.as_bytes().first()? {
b'i' => MessageLevel::Info,
b'w' => MessageLevel::Warning,
b'e' => MessageLevel::Error,
_ => return None,
};
let text = percent_decode(&entry[1..])?;
Some(StatusMessage::new(level, Lc::n(text)))
})
.collect()
}
// Guarda en la *cookie* los mensajes que añade la respuesta y la borra cuando la página siguiente
// ya los ha mostrado. Sin *cookie* en la petición ni mensajes nuevos, no hace nada más.
pub(crate) async fn keep_flash_messages(request: Request, next: Next) -> Response {
let previous = cookie_value(request.headers()).map(str::to_owned);
let mut response = next.run(request).await;
let pending = response.extensions_mut().remove::<Pending>();
if previous.is_none() && pending.is_none() {
return response;
}
// Una página (también de error) ya ha mostrado los mensajes anteriores; una redirección, o
// algo que no sea una página (un archivo, JSON...), los conserva para la siguiente.
let shown = !is_redirect(&response) && is_page(&response);
let mut value = match previous {
Some(previous) if !shown => {
if pending.is_none() {
return response;
}
previous
}
_ => String::new(),
};
for (level, text) in pending.map(|pending| pending.0).unwrap_or_default() {
push_message(&mut value, level, &text);
}
let cookie = if value.is_empty() {
EXPIRED_COOKIE.to_owned()
} else {
crate::util::join!(COOKIE_NAME, "=", value, COOKIE_ATTRS)
};
if let Ok(cookie) = http::HeaderValue::from_str(&cookie) {
response
.headers_mut()
.append(http::header::SET_COOKIE, cookie);
}
response
}
fn is_redirect(response: &Response) -> bool {
response.status().is_redirection()
|| response.headers().contains_key("hx-redirect")
|| response.headers().contains_key("hx-location")
}
fn is_page(response: &Response) -> bool {
response.extensions().get::<ErrorPage>().is_some()
|| response
.headers()
.get(http::header::CONTENT_TYPE)
.and_then(|value| value.as_bytes().get(..9))
.is_some_and(|essence| essence.eq_ignore_ascii_case(b"text/html"))
}
// Añade un mensaje al valor de la *cookie*, si cabe.
fn push_message(value: &mut String, level: MessageLevel, text: &str) {
let mut entry = String::with_capacity(text.len() + 1);
entry.push(match level {
MessageLevel::Info => 'i',
MessageLevel::Warning => 'w',
MessageLevel::Error => 'e',
});
push_percent_encoded(&mut entry, text);
let separator = usize::from(!value.is_empty());
if value.len() + separator + entry.len() > MAX_VALUE_LEN {
trace::warn!("Flash message discarded, it does not fit in the cookie: {text:?}");
return;
}
if separator == 1 {
value.push(SEPARATOR);
}
value.push_str(&entry);
}
// Valor de la *cookie* de mensajes, si la petición la trae. Con HTTP/2 el navegador puede repartir
// las *cookies* en varias cabeceras `cookie`.
fn cookie_value(headers: &http::HeaderMap) -> Option<&str> {
headers
.get_all(http::header::COOKIE)
.iter()
.filter_map(|value| value.to_str().ok())
.flat_map(|cookies| cookies.split(';'))
.filter_map(|part| part.trim().strip_prefix(COOKIE_NAME)?.strip_prefix('='))
.find(|value| !value.is_empty())
}
// Decodifica `%XX`; devuelve `None` si la secuencia no es válida o el resultado no es UTF-8.
fn percent_decode(encoded: &str) -> Option<String> {
let mut bytes = Vec::with_capacity(encoded.len());
let mut input = encoded.bytes();
while let Some(byte) = input.next() {
if byte == b'%' {
let hex = [input.next()?, input.next()?];
bytes.push(u8::from_str_radix(std::str::from_utf8(&hex).ok()?, 16).ok()?);
} else {
bytes.push(byte);
}
}
String::from_utf8(bytes).ok()
}
#[cfg(test)]
mod tests {
use super::*;
fn headers(cookie: &str) -> http::HeaderMap {
let mut headers = http::HeaderMap::new();
headers.insert(http::header::COOKIE, cookie.parse().unwrap());
headers
}
fn texts(cookie: &str) -> Vec<(MessageLevel, String)> {
read_flash_messages(&headers(cookie))
.iter()
.map(|m| (*m.level(), m.text().get().unwrap()))
.collect()
}
#[test]
fn messages_round_trip_through_the_cookie_value() {
let mut value = String::new();
push_message(
&mut value,
MessageLevel::Info,
"Cuenta creada | ¡bienvenida!",
);
push_message(&mut value, MessageLevel::Error, "a;b=c, \"d\"");
assert!(
value
.bytes()
.all(|b| b.is_ascii_graphic() && !b"; ,\"\\".contains(&b))
);
let cookie = format!("sid=abc; {COOKIE_NAME}={value}");
assert_eq!(
texts(&cookie),
[
(
MessageLevel::Info,
"Cuenta creada | ¡bienvenida!".to_owned()
),
(MessageLevel::Error, "a;b=c, \"d\"".to_owned()),
]
);
}
#[test]
fn invalid_entries_are_skipped() {
let cookie = format!("{COOKIE_NAME}=iok|xbad|e%E2%28|w%4|i%41b");
assert_eq!(
texts(&cookie),
[
(MessageLevel::Info, "ok".to_owned()),
(MessageLevel::Info, "Ab".to_owned()),
]
);
assert!(texts("other=1").is_empty());
}
#[test]
fn messages_that_do_not_fit_are_discarded() {
let mut value = String::new();
let long = "x".repeat(MAX_VALUE_LEN - 10);
push_message(&mut value, MessageLevel::Info, &long);
push_message(&mut value, MessageLevel::Info, "does not fit");
assert_eq!(value.len(), MAX_VALUE_LEN - 9);
}
}

View file

@ -190,28 +190,40 @@ impl Page {
///
/// El proceso de renderizado de la página sigue esta secuencia:
///
/// 1. Ejecuta
/// [`Theme::before_render_page_body()`](crate::core::theme::Theme::before_render_page_body)
/// para que el tema pueda ejecutar acciones específicas antes de renderizar el `<body>`.
/// 1. Ejecuta [`Theme::before_render_page_body()`] para que el tema pueda ejecutar acciones
/// específicas antes de renderizar el `<body>`.
/// 2. Despacha [`action::page::BeforeRenderBody`] para que otras extensiones puedan realizar
/// ajustes previos sobre la página.
/// 3. **Construye el contenido del `<body>`**:
/// - Renderiza la región reservada superior ([`ReservedRegions::PageTop`]).
/// - Llama a [`Theme::render_page_body()`](crate::core::theme::Theme::render_page_body) para
/// renderizar las regiones del cuerpo principal de la página.
/// - Llama a [`Theme::render_page_body()`] para renderizar las regiones del cuerpo principal
/// de la página.
/// - Renderiza la región reservada inferior ([`ReservedRegions::PageBottom`]).
/// 4. Ejecuta
/// [`Theme::after_render_page_body()`](crate::core::theme::Theme::after_render_page_body)
/// para que el tema pueda aplicar ajustes finales.
///
/// Los componentes que se aplazan ([`Component::is_deferred()`]), como el componente
/// [`Messages`] que encabeza la región [`CoreRegions::Content`], dejan de momento una marca
/// en su lugar.
/// 4. Ejecuta [`Theme::after_render_page_body()`] para que el tema pueda aplicar ajustes
/// finales.
/// 5. Despacha [`action::page::AfterRenderBody`] para permitir que otras extensiones realicen
/// sus últimos ajustes tras generar el `<body>`.
/// 6. Renderiza el `<head>` llamando a
/// [`Theme::render_page_head()`](crate::core::theme::Theme::render_page_head).
/// 7. Obtiene el idioma y la dirección del texto a partir de
/// [`Context::langid()`](crate::core::component::Context::langid) e inserta los atributos
/// `lang` y `dir` en la etiqueta `<html>`.
/// 8. Compone el documento HTML completo (`<!DOCTYPE html>`, `<html>`, `<head>`, `<body>`) y
/// 6. Renderiza los componentes aplazados y sustituye sus marcas por el resultado; si alguno no
/// genera nada, su marca se queda. Así muestran también lo que se haya acumulado en el
/// contexto en los pasos anteriores (por ejemplo, los mensajes para el usuario).
/// 7. Renderiza el `<head>` llamando a [`Theme::render_page_head()`].
/// 8. Obtiene el idioma y la dirección del texto a partir de [`Context::langid()`] e inserta
/// los atributos `lang` y `dir` en la etiqueta `<html>`.
/// 9. Compone el documento HTML completo (`<!DOCTYPE html>`, `<html>`, `<head>`, `<body>`) y
/// devuelve un [`Result`] con el [`Markup`] final.
///
/// [`Theme::before_render_page_body()`]: crate::core::theme::Theme::before_render_page_body
/// [`Theme::render_page_body()`]: crate::core::theme::Theme::render_page_body
/// [`Theme::after_render_page_body()`]: crate::core::theme::Theme::after_render_page_body
/// [`Theme::render_page_head()`]: crate::core::theme::Theme::render_page_head
/// [`CoreRegions::Content`]: crate::core::theme::CoreRegions::Content
/// [`Component::is_deferred()`]: crate::core::component::Component::is_deferred
/// [`Context::langid()`]: crate::core::component::Context::langid
/// [`Messages`]: crate::base::component::Messages
pub async fn render(&mut self) -> Result<Markup, ErrorPage> {
// Acciones específicas del tema antes de renderizar el <body>.
self.context.theme().before_render_page_body(self);
@ -219,7 +231,8 @@ impl Page {
// Acciones de las extensiones antes de renderizar el <body>.
action::page::BeforeRenderBody::dispatch(self);
// Renderiza el <body>.
// Renderiza el <body>, aplazando los componentes que lo pidan.
self.context.start_deferring();
let body = html! {
(layout::Region::of(&ReservedRegions::PageTop).render(&mut self.context).await)
(self.context.theme().render_page_body(self).await)
@ -232,6 +245,9 @@ impl Page {
// Acciones de las extensiones después de renderizar el <body>.
action::page::AfterRenderBody::dispatch(self);
// Renderiza los componentes aplazados, antes del <head> para que lleguen sus recursos.
let body = self.context.render_deferred(body).await;
// Renderiza el <head>.
let head = self.context.theme().render_page_head(self).await;

View file

@ -36,6 +36,7 @@ pub use axum::middleware;
// Guardado de los archivos subidos en formularios `multipart/form-data`.
mod upload;
pub(crate) use upload::push_percent_encoded;
pub use upload::{Upload, UploadError, UploadedFile, UploadedForm};
// Respuestas con los archivos subidos.

View file

@ -739,7 +739,7 @@ fn file_extension(name: &str) -> Option<String> {
// Codifica como `%XX` todos los bytes salvo los no reservados de RFC 3986, igual que un navegador
// codifica los campos de un formulario; vale también para `filename*` de `Content-Disposition`.
pub(super) fn push_percent_encoded(out: &mut String, value: impl AsRef<[u8]>) {
pub(crate) fn push_percent_encoded(out: &mut String, value: impl AsRef<[u8]>) {
const HEX: &[u8; 16] = b"0123456789ABCDEF";
for &byte in value.as_ref() {
match byte {