diff --git a/assets/scss/basic/_regions.scss b/assets/scss/basic/_regions.scss index 3fb08467..62190135 100644 --- a/assets/scss/basic/_regions.scss +++ b/assets/scss/basic/_regions.scss @@ -1,3 +1,9 @@ +// A region holding only comments (such as the mark of a deferred component that rendered nothing) +// matches `:empty`, so it takes no space. +.region:empty { + display: none; +} + .region-footer { padding: .75rem 0 3rem; text-align: center; diff --git a/extensions/pagetop-bootsier/assets/_bootsier-custom.scss b/extensions/pagetop-bootsier/assets/_bootsier-custom.scss index 2ab7aa7a..2884411e 100644 --- a/extensions/pagetop-bootsier/assets/_bootsier-custom.scss +++ b/extensions/pagetop-bootsier/assets/_bootsier-custom.scss @@ -87,6 +87,12 @@ fieldset > legend { margin-left: 1rem; } +// A region holding only comments (such as the mark of a deferred component that rendered nothing) +// matches `:empty`, so it takes no space. +.region:empty { + display: none; +} + // Footer region. .region-footer { padding: 0.75rem 0 3rem; diff --git a/src/app.rs b/src/app.rs index c7b2312d..700f805a 100644 --- a/src/app.rs +++ b/src/app.rs @@ -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)) diff --git a/src/base/action/component.rs b/src/base/action/component.rs index d745ae00..8a2a93d1 100644 --- a/src/base/action/component.rs +++ b/src/base/action/component.rs @@ -23,6 +23,13 @@ pub type FnActionWithComponent = 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 ``, 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 = fn(component: &C, cx: &Context, markup: Markup) -> Markup; mod before_render_component; diff --git a/src/base/component/layout/region.rs b/src/base/component/layout/region.rs index 98ef1807..7f34c266 100644 --- a/src/base/component/layout/region.rs +++ b/src/base/component/layout/region.rs @@ -5,13 +5,25 @@ use std::fmt; /// Componente que renderiza una región del ``. /// /// 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 { 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 diff --git a/src/base/component/messages.rs b/src/base/component/messages.rs index 6ca3cedb..0b7e292c 100644 --- a/src/base/component/messages.rs +++ b/src/base/component/messages.rs @@ -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 { +/// 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 { /// 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 { - 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 + /// ``, 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 + } } diff --git a/src/core/component/context.rs b/src/core/component/context.rs index 45ab618a..6e5a41cc 100644 --- a/src/core/component/context.rs +++ b/src/core/component/context.rs @@ -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 . regions : ChildrenInRegions, // Regiones de componentes para renderizar. + deferred : Option, // Componentes de renderizado aplazado. params : HashMap<&'static str, (Box, &'static str)>, // Parámetros. id_counters : Mutex>, // Mutex permite mutar desde build_id(&self). messages : Vec, // Mensajes de usuario acumulados. } +// Componentes aplazados mientras se renderiza el `` 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)>, +} + 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 ``. + 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 ``, 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 { + let deferred = self.deferred.as_mut()?; + let mark = format!( + "", + 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(""), + 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 `` 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 { + 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) -> 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. diff --git a/src/core/component/definition.rs b/src/core/component/definition.rs index 060b44bf..b20e6ff9 100644 --- a/src/core/component/definition.rs +++ b/src/core/component/definition.rs @@ -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 `` de una página + /// ([`Page::render()`]), su [ciclo de renderizado](ComponentRender) completo se aplaza hasta + /// que se ha renderizado el resto del ``, 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 + /// ``. 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 + /// `` (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 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 `` de una página, +/// devuelve una marca que [`Page::render()`] sustituirá por el resultado de este mismo proceso una +/// vez renderizado el resto del `` (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 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`]: crate::base::action::component::BeforeRender @@ -194,6 +236,13 @@ impl ComponentClone for T { #[async_trait] impl 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 . + 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! {}; diff --git a/src/core/theme.rs b/src/core/theme.rs index 43048338..e136abf8 100644 --- a/src/core/theme.rs +++ b/src/core/theme.rs @@ -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; diff --git a/src/core/theme/all.rs b/src/core/theme/all.rs index fe7e90f4..67542e61 100644 --- a/src/core/theme/all.rs +++ b/src/core/theme/all.rs @@ -24,8 +24,9 @@ pub fn enabled_themes() -> Vec { 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 { 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 { diff --git a/src/core/theme/layout.rs b/src/core/theme/layout.rs index 01b4b348..09313df1 100644 --- a/src/core/theme/layout.rs +++ b/src/core/theme/layout.rs @@ -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, diff --git a/src/response.rs b/src/response.rs index a427a1f7..cff674f8 100644 --- a/src/response.rs +++ b/src/response.rs @@ -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::*; diff --git a/src/response/flash.rs b/src/response/flash.rs new file mode 100644 index 00000000..61216df5 --- /dev/null +++ b/src/response/flash.rs @@ -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::() + .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 { + 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::(); + 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::().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 { + 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); + } +} diff --git a/src/response/page.rs b/src/response/page.rs index bfcde2d5..b31db6aa 100644 --- a/src/response/page.rs +++ b/src/response/page.rs @@ -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 ``. + /// 1. Ejecuta [`Theme::before_render_page_body()`] para que el tema pueda ejecutar acciones + /// específicas antes de renderizar el ``. /// 2. Despacha [`action::page::BeforeRenderBody`] para que otras extensiones puedan realizar /// ajustes previos sobre la página. /// 3. **Construye el contenido del ``**: /// - 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 ``. - /// 6. Renderiza el `` 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 ``. - /// 8. Compone el documento HTML completo (``, ``, ``, ``) 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 `` 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 ``. + /// 9. Compone el documento HTML completo (``, ``, ``, ``) 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 { // Acciones específicas del tema antes de renderizar el . self.context.theme().before_render_page_body(self); @@ -219,7 +231,8 @@ impl Page { // Acciones de las extensiones antes de renderizar el . action::page::BeforeRenderBody::dispatch(self); - // Renderiza el . + // Renderiza el , 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 . action::page::AfterRenderBody::dispatch(self); + // Renderiza los componentes aplazados, antes del para que lleguen sus recursos. + let body = self.context.render_deferred(body).await; + // Renderiza el . let head = self.context.theme().render_page_head(self).await; diff --git a/src/web.rs b/src/web.rs index 4a2e950c..cc50a09f 100644 --- a/src/web.rs +++ b/src/web.rs @@ -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. diff --git a/src/web/upload.rs b/src/web/upload.rs index 684d5c39..ef00be9e 100644 --- a/src/web/upload.rs +++ b/src/web/upload.rs @@ -739,7 +739,7 @@ fn file_extension(name: &str) -> Option { // 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 { diff --git a/tests/component_deferred.rs b/tests/component_deferred.rs new file mode 100644 index 00000000..ca33d3ff --- /dev/null +++ b/tests/component_deferred.rs @@ -0,0 +1,208 @@ +use pagetop::prelude::*; + +// Rendering regions looks up localized labels, so the localization subsystem must be loaded. +async fn setup() { + Application::new().await; +} + +fn request() -> HttpRequest { + web::test::TestRequest::get().to_http_request() +} + +/// Pushes a message while it renders, like a form that reports its own errors. +#[derive(AutoDefault, Clone)] +struct Pusher(&'static str); + +#[async_trait] +impl Component for Pusher { + fn new() -> Self { + Self::default() + } + + async fn prepare(&self, cx: &mut Context) -> Result { + cx.push_message(MessageLevel::Error, Lc::n(self.0)); + Ok(html! { p { "pusher-" (self.0) } }) + } +} + +/// Deferred component that shows how many messages the context holds when it renders. +#[derive(Clone)] +struct Counter; + +#[async_trait] +impl Component for Counter { + fn new() -> Self { + Self + } + + fn is_deferred(&self) -> bool { + true + } + + async fn prepare(&self, cx: &mut Context) -> Result { + Ok(html! { span { "count-" (cx.messages().len()) } }) + } +} + +/// Deferred component that adds a stylesheet to the page while it renders. +#[derive(Clone)] +struct Styled; + +#[async_trait] +impl Component for Styled { + fn new() -> Self { + Self + } + + fn is_deferred(&self) -> bool { + true + } + + fn setup(&mut self, cx: &mut Context) { + cx.alter_assets(StyleSheet::from("/deferred.css")); + } +} + +/// Renders a deferred component and throws its output away, so its mark never reaches the body. +#[derive(Clone)] +struct Discarder; + +#[async_trait] +impl Component for Discarder { + fn new() -> Self { + Self + } + + async fn prepare(&self, cx: &mut Context) -> Result { + Counter.render(cx).await; + Ok(html! { "discarded" }) + } +} + +async fn render(mut page: Page) -> String { + page.render().await.expect("page renders").into_string() +} + +#[pagetop::test] +async fn messages_pushed_while_rendering_are_shown_first_in_the_content() { + setup().await; + let page = Page::new(request()) + .with_child(Pusher("from-content")) + .with_child_in(&CoreRegions::Footer, Pusher("from-footer")); + let body = render(page).await; + + let messages = body.find(r#"class="messages""#).expect("messages"); + assert!(body.find("region-content").unwrap() < messages); + assert!(messages < body.find("pusher-from-content").unwrap()); + assert!(messages < body.find("pusher-from-footer").unwrap()); + assert_eq!(body.matches("message message-error").count(), 2); + assert!(!body.contains("