diff --git a/src/base/component/messages.rs b/src/base/component/messages.rs index 0b7e292c..fd980035 100644 --- a/src/base/component/messages.rs +++ b/src/base/component/messages.rs @@ -3,7 +3,7 @@ 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, y retira los +/// [`push_message()`](Contextual::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 @@ -36,8 +36,7 @@ use crate::prelude::*; /// /// async fn homepage(request: HttpRequest) -> Result { /// let mut page = Page::new(request); -/// page.context() -/// .push_message(MessageLevel::Info, Lc::n("Settings saved.")); +/// page.push_message(MessageLevel::Info, Lc::n("Settings saved.")); /// page.with_child(Html::with(|_| html! { p { "..." } })) /// .render() /// .await diff --git a/src/core/component/context.rs b/src/core/component/context.rs index 6e5a41cc..654f2655 100644 --- a/src/core/component/context.rs +++ b/src/core/component/context.rs @@ -1,16 +1,15 @@ use crate::auth::CurrentUser; -use crate::core::TypeInfo; -use crate::core::component::{ChildOp, Component, MessageLevel, StatusMessage}; -use crate::core::theme::{ChildrenInRegions, CoreRegions, CoreTemplates, default_theme}; +use crate::core::component::{Component, StatusMessage}; +use crate::core::theme::{ChildrenInRegions, CoreTemplates, default_theme}; use crate::core::theme::{RegionRef, TemplateRef, ThemeRef}; use crate::datetime::Tz; use crate::html::{Assets, Favicon, JavaScript, Preload, ResponsiveStyles, StyleSheet}; -use crate::html::{Markup, PreEscaped, Props, PropsOp, RoutePath, html}; +use crate::html::{Markup, PreEscaped, Props, html}; use crate::locale::Lc; -use crate::locale::{LangId, LanguageIdentifier, RequestLocale}; +use crate::locale::RequestLocale; use crate::response::read_flash_messages; use crate::web::HttpRequest; -use crate::{builder_impl, util}; +use crate::{CowStr, util}; use parking_lot::Mutex; @@ -29,25 +28,18 @@ pub use contextual::Contextual; /// Implementa un **contexto de renderizado** para un documento HTML. /// /// Se crea una sola vez por petición usando [`Context::new()`] (típicamente a través de -/// [`Page::new()`](crate::response::Page::new) o [`Page::admin()`](crate::response::Page::admin)), -/// y es la única vía por la que un componente, una acción o el tema activo conocen: la petición -/// HTTP de origen, el idioma negociado y la zona horaria efectiva, el usuario autenticado -/// ([`current_user()`](Contextual::current_user)), el tema y la plantilla en uso, y los recursos -/// (favicon, hojas de estilo, scripts) acumulados hasta ese momento. Otros datos que los +/// [`Page::new()`] o [`Page::admin()`]), y es la única vía por la que un componente, una acción o +/// el tema activo conocen la petición HTTP de origen, el idioma negociado y la zona horaria +/// efectiva, el usuario autenticado ([`current_user()`]), el tema y la plantilla en uso, y los +/// recursos (favicon, hojas de estilo, scripts) acumulados hasta ese momento. Otros datos que los /// componentes necesiten durante el renderizado pueden ser parámetros dinámicos tipados con -/// [`with_param()`](Contextual::with_param)/[`param()`](Contextual::param). +/// [`with_param()`]/[`param()`]. /// -/// La implementación extiende [`Contextual`], que aporta los métodos *builder* (`with_*`) y los -/// *getters* comunes a cualquier estructura que gestione un contexto de renderizado (también los -/// implementa [`Page`](crate::response::Page)). Además, `Context` añade: -/// -/// - [`route()`](Self::route) para construir URLs que preserven `?lang=...` cuando corresponda. -/// - [`build_id()`](Self::build_id)/[`required_id()`](Self::required_id) para generar -/// identificadores HTML únicos por tipo de componente. -/// - [`push_message()`](Self::push_message)/[`messages()`](Self::messages) para acumular -/// [`StatusMessage`] que mostrar en algún momento del renderizado. -/// - [`render_assets()`](Self::render_assets)/[`render_region()`](Self::render_region), usados -/// internamente por [`Page`](crate::response::Page) para producir el HTML final del documento. +/// Su interfaz la aporta [`Contextual`]: los métodos *builder* (`with_*`), los *getters* y las +/// utilidades como [`route()`], [`build_id()`] o [`push_message()`]. Como también lo implementa +/// [`Page`], sobre el contexto que contiene, ambos se usan exactamente igual. Además de sus +/// constructores, `Context` sólo añade [`render_assets()`] y [`render_region()`], con los que los +/// temas y la página producen el HTML final del documento. /// /// # Ejemplos /// @@ -93,6 +85,18 @@ pub use contextual::Contextual; /// let _unique_id = cx.build_id::(1); // => "menu-1" si es el primero /// } /// ``` +/// +/// [`Page`]: crate::response::Page +/// [`Page::new()`]: crate::response::Page::new +/// [`Page::admin()`]: crate::response::Page::admin +/// [`current_user()`]: Contextual::current_user +/// [`with_param()`]: Contextual::with_param +/// [`param()`]: Contextual::param +/// [`route()`]: Contextual::route +/// [`build_id()`]: Contextual::build_id +/// [`push_message()`]: Contextual::push_message +/// [`render_assets()`]: Self::render_assets +/// [`render_region()`]: Self::render_region #[rustfmt::skip] pub struct Context { request : Option, // Petición HTTP de origen. @@ -106,6 +110,10 @@ pub struct Context { stylesheets : Assets, // Hojas de estilo CSS. javascripts : Assets, // Scripts JavaScript. responsives : ResponsiveStyles, // Estilos *responsive*. + title : Lc, // Título del documento. + description : Lc, // Descripción del documento. + metadata : Vec<(&'static str, CowStr)>, // Entradas . + properties : Vec<(&'static str, CowStr)>, // Entradas . body_props : Props, // Id, clases CSS y atributos del . regions : ChildrenInRegions, // Regiones de componentes para renderizar. deferred : Option, // Componentes de renderizado aplazado. @@ -130,7 +138,7 @@ impl Default for Context { impl Context { // Construye el `Context` compartido por `new()`, `admin()` y `Default::default()`, evitando - // duplicar la lista de campos entre ambos (y la recursión que tendría `new()` llamando a + // duplicar la lista de campos entre ellos (y la recursión que tendría `new()` llamando a // `Default::default()`, o viceversa). Recibe la plantilla para que `admin()` no tenga que // construir con la plantilla estándar y sobrescribirla después. #[rustfmt::skip] @@ -155,6 +163,10 @@ impl Context { stylesheets: Assets::::new(), javascripts: Assets::::new(), responsives: ResponsiveStyles::new(), + title : Lc::none(), + description: Lc::none(), + metadata : Vec::new(), + properties : Vec::new(), body_props : Props::default(), regions : ChildrenInRegions::default(), deferred : None, @@ -247,6 +259,8 @@ impl Context { .await } + // **< Context HELPERS >************************************************************************ + // Empieza a aplazar los componentes que lo pidan (`Component::is_deferred()`), mientras // `Page::render()` renderiza el ``. pub(crate) fn start_deferring(&mut self) { @@ -307,293 +321,20 @@ impl Context { PreEscaped(body) } - // **< Context HELPERS >************************************************************************ - - /// Construye una ruta aplicada al contexto actual. - /// - /// Acepta cualquier tipo convertible a [`RoutePath`] (un literal, un `String`, un `&str` de - /// cualquier vida, o un [`RoutePath`] ya construido con sus propios parámetros). Si la política - /// de negociación del idioma ([`LangNegotiation`](crate::global::LangNegotiation)) indica que - /// debe propagarse el idioma para esta petición, se añade o actualiza automáticamente el - /// parámetro de *query* `lang=...` con el identificador de idioma definido en el contexto. - /// - /// Esto garantiza que los enlaces generados desde el contexto preservan la preferencia de - /// idioma del usuario durante la navegación. Si `path` **parece** una URL externa (ver - /// [`util::url_looks_external()`](crate::util::url_looks_external)), nunca se le añade `lang`. - /// - /// Este método asume que ya tienes `cx` a mano en el momento de construir la ruta (dentro de - /// `prepare()`, un *handler* HTTP, etc.). Si lo que estás definiendo es un campo de componente - /// que se construye una sola vez y se reutiliza en peticiones futuras (un menú, un botón, - /// etc.), usa [`Route`](crate::core::component::Route) en su lugar (su documentación explica el - /// criterio completo para elegir entre ambos). - pub fn route(&self, path: impl Into) -> RoutePath { - let mut route = path.into(); - if !route.is_external() && self.locale.needs_lang_query() { - route.alter_param("lang", self.locale.lang_query_value()); - } - route - } - - /// Construye un identificador HTML único para el tipo de componente `C`. - /// - /// Toma los `segments` finales del *path* completo del tipo, los une con `-` y los convierte a - /// minúsculas, y añade un contador independiente por tipo. Por ejemplo, para `MyApp::ui::Menu` - /// con `segments = 2` devuelve `ui-menu-1` la primera vez que se invoca para ese tipo, - /// `ui-menu-2` la segunda, etc. - /// - /// Con `segments = 1` se usa sólo el nombre corto del tipo. Si `segments` es `0` o supera el - /// número de segmentos del *path*, se usan todos. - /// - /// Es útil para asignar identificadores cuando el componente no recibe uno explícito. El - /// contador es local a este contexto y se reinicia para cada nueva petición. - pub fn build_id(&self, segments: usize) -> String { - let path: Vec<&str> = TypeInfo::FullName.of::().split("::").collect(); - let segments = if segments == 0 || segments >= path.len() { - path.len() - } else { - segments - }; - let count = { - let mut map = self.id_counters.lock(); - let n = map.entry(TypeId::of::()).or_insert(0); - *n += 1; - *n - }; - let prefix = path[path.len() - segments..].join("-").to_lowercase(); - util::join!(prefix, "-", count.to_string()) - } - - /// Devuelve `id` si contiene un valor, o genera uno único con [`build_id`](Self::build_id) - /// si es `None`. - pub fn required_id(&self, id: Option, segments: usize) -> String { - match id { - Some(id) => id, - None => self.build_id::(segments), - } - } - - /// 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. 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 - /// - /// ```rust,no_run - /// # use pagetop::prelude::*; - /// # let mut cx = Context::default(); - /// cx.push_message(MessageLevel::Warning, Lc::n("Session is not valid")); - /// ``` - pub fn push_message(&mut self, level: MessageLevel, text: Lc) { - self.messages.push(StatusMessage::new(level, text)); - } - - /// 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 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. -/// -/// Internamente delega en [`RequestLocale`], que tiene en cuenta la petición HTTP (parámetro -/// `?lang` e idioma preferido del usuario), la configuración global de idioma de la aplicación, la -/// cabecera `Accept-Language` y/o el idioma de respaldo. -/// -/// Todo ello según la negociación indicada en [`global::SETTINGS.app.lang_negotiation`]. Esto -/// permite que el [`Context`] se use como fuente de idioma coherente en [`Lc::lookup()`] o -/// [`Lc::using()`]. -/// -/// [`Context`]: crate::core::component::Context -/// [`global::SETTINGS.app.lang_negotiation`]: crate::global::AppSettings::lang_negotiation -/// [`Lc::lookup()`]: crate::locale::Lc::lookup -/// [`Lc::using()`]: crate::locale::Lc::using -impl LangId for Context { - #[inline] - fn langid(&self) -> &'static LanguageIdentifier { - self.locale.langid() - } -} - -#[builder_impl] 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. - self.locale = RequestLocale::from_request(self.request.as_ref()); - self.current_user = Self::resolve_current_user(self.request.as_ref()); - self.timezone = self.current_user.timezone(); - self.theme = self.current_user.theme().unwrap_or_else(default_theme); + #[inline] + fn context(&self) -> &Context { self } - fn with_langid(mut self, language: &impl LangId) -> Self { - self.locale.with_langid(language); + #[inline] + fn context_mut(&mut self) -> &mut Context { self } - - fn with_timezone(mut self, tz: Tz) -> Self { - self.timezone = tz; - self - } - - fn with_theme(mut self, theme: ThemeRef) -> Self { - self.theme = theme; - self - } - - fn with_template(mut self, template: TemplateRef) -> Self { - self.template = template; - self - } - - fn with_param(mut self, key: &'static str, value: T) -> Self { - let type_name = TypeInfo::FullName.of::(); - self.params.insert(key, (Box::new(value), type_name)); - self - } - - fn with_assets(mut self, op: impl Into) -> Self { - match op.into() { - // Favicon. - AssetsOp::SetFavicon(favicon) => { - self.favicon = favicon; - } - AssetsOp::SetFaviconIfNone(icon) => { - if self.favicon.is_none() { - self.favicon = Some(icon); - } - } - // Preloads. - AssetsOp::AddPreload(preload) => { - self.preloads.add(preload); - } - AssetsOp::RemovePreload(path) => { - self.preloads.remove(path); - } - // Stylesheets. - AssetsOp::AddStyleSheet(css) => { - self.stylesheets.add(css); - } - AssetsOp::RemoveStyleSheet(path) => { - self.stylesheets.remove(path); - } - // Scripts JavaScript. - AssetsOp::AddJavaScript(js) => { - self.javascripts.add(js); - } - AssetsOp::RemoveJavaScript(path) => { - self.javascripts.remove(path); - } - // Estilos responsive. - AssetsOp::AddResponsiveStyle(breakpoint, classes, property, value) => { - self.responsives - .add_style(breakpoint, classes, property, value); - } - AssetsOp::AddResponsiveStyles(breakpoint, classes, styles) => { - self.responsives.add_styles(breakpoint, classes, styles); - } - } - self - } - - fn with_body_props(mut self, op: PropsOp) -> Self { - self.body_props.alter_prop(op); - self - } - - fn with_child(mut self, op: impl Into) -> Self { - self.regions - .alter_child_in(&CoreRegions::Content, op.into()); - self - } - - fn with_child_in(mut self, region: RegionRef, op: impl Into) -> Self { - self.regions.alter_child_in(region, op.into()); - self - } - - // **< Contextual GETTERS >********************************************************************* - - fn request(&self) -> Option<&HttpRequest> { - self.request.as_ref() - } - - fn current_user(&self) -> &CurrentUser { - &self.current_user - } - - fn timezone(&self) -> Tz { - self.timezone - } - - fn theme(&self) -> ThemeRef { - self.theme - } - - fn template(&self) -> TemplateRef { - self.template - } - - fn param(&self, key: &'static str) -> Result<&T, ContextError> { - let (any, type_name) = self.params.get(key).ok_or(ContextError::ParamNotFound)?; - any.downcast_ref::() - .ok_or_else(|| ContextError::ParamTypeMismatch { - key, - expected: TypeInfo::FullName.of::(), - saved: type_name, - }) - } - - fn favicon(&self) -> Option<&Favicon> { - self.favicon.as_ref() - } - - fn stylesheets(&self) -> &Assets { - &self.stylesheets - } - - fn javascripts(&self) -> &Assets { - &self.javascripts - } - - fn responsive_styles(&self) -> &ResponsiveStyles { - &self.responsives - } - - fn body_props(&self) -> &Props { - &self.body_props - } - - // **< Contextual HELPERS >********************************************************************* - - fn remove_param(&mut self, key: &'static str) -> bool { - self.params.remove(key).is_some() - } } diff --git a/src/core/component/context/contextual.rs b/src/core/component/context/contextual.rs index 19e2d3e5..63c54eaa 100644 --- a/src/core/component/context/contextual.rs +++ b/src/core/component/context/contextual.rs @@ -1,14 +1,19 @@ -use super::{AssetsOp, ContextError}; +use super::{AssetsOp, Context, ContextError}; use crate::auth::CurrentUser; -use crate::builder_impl; -use crate::core::component::ChildOp; -use crate::core::theme::{RegionRef, TemplateRef, ThemeRef}; +use crate::core::TypeInfo; +use crate::core::component::{ChildOp, Component, MessageLevel, StatusMessage}; +use crate::core::theme::{CoreRegions, RegionRef, TemplateRef, ThemeRef, default_theme}; use crate::datetime::{DateFormat, DatePrecision, RelativeFormat, TimeFormat}; use crate::datetime::{DateInputError, DateTime, NaiveDate, NaiveTime, Tz, Utc}; -use crate::html::{Assets, Favicon, JavaScript, Props, PropsOp, ResponsiveStyles, StyleSheet}; -use crate::locale::{LangId, Lc}; +use crate::html::StyleSheet; +use crate::html::{Assets, Favicon, JavaScript, Props, PropsOp, ResponsiveStyles, RoutePath}; +use crate::locale::{LangId, LanguageIdentifier, Lc, RequestLocale}; +use crate::response::read_flash_messages; use crate::web::HttpRequest; +use crate::{CowStr, builder_impl, util}; + +use std::any::TypeId; // RFC 3339 con el offset de la zona horaria activa (no UTC fijo): igual en todos los idiomas, no // es una clave Fluent. Usado sólo por `format_iso_datetime()`. @@ -16,22 +21,31 @@ const ISO_DATETIME: &str = "%Y-%m-%dT%H:%M:%S%:z"; /// Interfaz para gestionar el **contexto de renderizado** de un documento HTML. /// -/// `Contextual` extiende [`LangId`] para establecer el idioma del documento y añade métodos para: +/// Todo lo que implementa `Contextual` es también proveedor de idioma ([`LangId`]), con el idioma +/// del documento, así que puede usarse directamente en [`Lc::lookup()`] o [`Lc::using()`]. Además, +/// ofrece métodos para: /// -/// - Almacenar la **petición HTTP** de origen. +/// - Establecer el **idioma** del documento ([`with_langid()`](Self::with_langid)). +/// - Almacenar la **petición HTTP** de origen ([`with_request()`](Self::with_request)). /// - Conocer la **identidad del usuario actual** ([`current_user()`](Self::current_user)) y la /// **zona horaria efectiva** del documento ([`timezone()`](Self::timezone)). /// - Seleccionar el **tema** y la **plantilla** de renderizado. +/// - Definir el **título**, la **descripción** y los **metadatos** del documento. /// - Administrar **recursos** del documento como el icono [`Favicon`], las hojas de estilo /// [`StyleSheet`] o los scripts [`JavaScript`], directamente o mediante una operación /// [`AssetsOp`]. /// - Leer y mantener **parámetros dinámicos tipados** de contexto. +/// - Construir **rutas** que preserven el idioma ([`route()`](Self::route)) e **identificadores** +/// únicos ([`build_id()`](Self::build_id)). +/// - Acumular **mensajes para el usuario** ([`push_message()`](Self::push_message)). /// - Formatear **fechas y horas** ([`format_date()`](Self::format_date), /// [`format_time()`](Self::format_time), [`format_datetime()`](Self::format_datetime) y demás) /// para la zona horaria e idioma del documento. /// -/// Lo implementan, típicamente, estructuras que manejan el contexto de renderizado, como -/// [`Context`](crate::core::component::Context) o [`Page`](crate::response::Page). +/// Todos los métodos actúan sobre el [`Context`] que devuelven [`context()`](Self::context) y +/// [`context_mut()`](Self::context_mut), los únicos que hay que implementar. Lo implementan +/// [`Context`] (que se devuelve a sí mismo) y [`Page`](crate::response::Page) (que devuelve el +/// suyo), así que ambos ofrecen exactamente la misma interfaz. /// /// # Ejemplo /// @@ -49,11 +63,23 @@ const ISO_DATETIME: &str = "%Y-%m-%dT%H:%M:%S%:z"; /// } /// ``` #[builder_impl] -pub trait Contextual: LangId { +pub trait Contextual { + /// Devuelve una referencia al contexto de renderizado. + fn context(&self) -> &Context; + + /// Devuelve una referencia mutable al contexto de renderizado. + /// + /// Resulta útil para pasar el contexto a funciones o componentes que lo reciben como parámetro + /// (`&mut Context`). + fn context_mut(&mut self) -> &mut Context; + // **< Contextual BUILDER >********************************************************************* /// Establece el idioma del documento. - fn with_langid(self, language: &impl LangId) -> Self; + fn with_langid(self, language: &impl LangId) -> Self { + self.context_mut().locale.with_langid(language); + self + } /// Fuerza la zona horaria que se utilizará para mostrar fechas y horas en el documento. /// @@ -61,7 +87,10 @@ pub trait Contextual: LangId { /// aplicación) por otra explícita. Ver [`CurrentUser::timezone()`]. /// /// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone - fn with_timezone(self, tz: Tz) -> Self; + fn with_timezone(self, tz: Tz) -> Self { + self.context_mut().timezone = tz; + self + } /// Almacena la petición HTTP de origen en el contexto. /// @@ -77,13 +106,36 @@ pub trait Contextual: LangId { /// [`current_user()`]: Self::current_user /// [`timezone()`]: Self::timezone /// [`theme()`]: Self::theme - fn with_request(self, request: Option) -> Self; + fn with_request(self, request: Option) -> Self { + let cx = self.context_mut(); + // 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 cx.request.is_none() + && let Some(request) = &request + { + cx.messages.extend(read_flash_messages(request.headers())); + } + cx.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. + cx.locale = RequestLocale::from_request(cx.request.as_ref()); + cx.current_user = Context::resolve_current_user(cx.request.as_ref()); + cx.timezone = cx.current_user.timezone(); + cx.theme = cx.current_user.theme().unwrap_or_else(default_theme); + self + } /// Especifica el tema para renderizar el documento. - fn with_theme(self, theme: ThemeRef) -> Self; + fn with_theme(self, theme: ThemeRef) -> Self { + self.context_mut().theme = theme; + self + } /// Especifica la plantilla para renderizar el documento. - fn with_template(self, template: TemplateRef) -> Self; + fn with_template(self, template: TemplateRef) -> Self { + self.context_mut().template = template; + self + } /// Añade o modifica un parámetro dinámico del contexto. /// @@ -100,28 +152,122 @@ pub trait Contextual: LangId { /// .with_param("title", "Hello".to_string()) /// .with_param("flags", vec!["a", "b"]); /// ``` - fn with_param(self, key: &'static str, value: T) -> Self; + fn with_param(self, key: &'static str, value: T) -> Self { + let type_name = TypeInfo::FullName.of::(); + self.context_mut() + .params + .insert(key, (Box::new(value), type_name)); + self + } /// Añade un recurso ([`Favicon`], [`StyleSheet`], [`JavaScript`] o /// [`Preload`](crate::html::Preload)) directamente, o aplica una operación [`AssetsOp`] sobre /// los recursos del contexto. - fn with_assets(self, op: impl Into) -> Self; + fn with_assets(self, op: impl Into) -> Self { + let cx = self.context_mut(); + match op.into() { + // Favicon. + AssetsOp::SetFavicon(favicon) => { + cx.favicon = favicon; + } + AssetsOp::SetFaviconIfNone(icon) => { + if cx.favicon.is_none() { + cx.favicon = Some(icon); + } + } + // Preloads. + AssetsOp::AddPreload(preload) => { + cx.preloads.add(preload); + } + AssetsOp::RemovePreload(path) => { + cx.preloads.remove(path); + } + // Stylesheets. + AssetsOp::AddStyleSheet(css) => { + cx.stylesheets.add(css); + } + AssetsOp::RemoveStyleSheet(path) => { + cx.stylesheets.remove(path); + } + // Scripts JavaScript. + AssetsOp::AddJavaScript(js) => { + cx.javascripts.add(js); + } + AssetsOp::RemoveJavaScript(path) => { + cx.javascripts.remove(path); + } + // Estilos responsive. + AssetsOp::AddResponsiveStyle(breakpoint, classes, property, value) => { + cx.responsives + .add_style(breakpoint, classes, property, value); + } + AssetsOp::AddResponsiveStyles(breakpoint, classes, styles) => { + cx.responsives.add_styles(breakpoint, classes, styles); + } + } + self + } + + /// Establece el título del documento como un valor traducible. + /// + /// Además de usarse en el ``, lo ven las plantillas y los componentes al renderizarse, + /// como el marco de las páginas del panel de administración + /// ([`AdminFrame`](crate::base::component::AdminFrame)), que lo muestra como encabezado. + fn with_title(self, title: Lc) -> Self { + self.context_mut().title = title; + self + } + + /// Establece la descripción del documento como un valor traducible. + /// + /// Se usa en la etiqueta `` del ``. + fn with_description(self, description: Lc) -> Self { + self.context_mut().description = description; + self + } + + /// Añade una entrada `` al ``. + fn with_metadata(self, name: &'static str, content: impl Into) -> Self { + self.context_mut().metadata.push((name, content.into())); + self + } + + /// Añade una entrada `` al ``. + fn with_property(self, property: &'static str, content: impl Into) -> Self { + self.context_mut() + .properties + .push((property, content.into())); + self + } /// Modifica identificador, clases CSS, atributos HTML o valores extra del elemento ``. - fn with_body_props(self, op: PropsOp) -> Self; + fn with_body_props(self, op: PropsOp) -> Self { + self.context_mut().body_props.alter_prop(op); + self + } /// Añade un componente o aplica una operación [`ChildOp`] en la región por defecto del /// documento. - fn with_child(self, op: impl Into) -> Self; + fn with_child(self, op: impl Into) -> Self { + self.context_mut() + .regions + .alter_child_in(&CoreRegions::Content, op.into()); + self + } /// Añade un componente o aplica una operación [`ChildOp`] en una región específica del /// documento. - fn with_child_in(self, region: RegionRef, op: impl Into) -> Self; + fn with_child_in(self, region: RegionRef, op: impl Into) -> Self { + self.context_mut().regions.alter_child_in(region, op.into()); + self + } // **< Contextual GETTERS >********************************************************************* /// Devuelve una referencia a la petición HTTP asociada, si existe. - fn request(&self) -> Option<&HttpRequest>; + fn request(&self) -> Option<&HttpRequest> { + self.context().request.as_ref() + } /// Devuelve la identidad del usuario actual. /// @@ -141,7 +287,9 @@ pub trait Contextual: LangId { /// page.render().await /// } /// ``` - fn current_user(&self) -> &CurrentUser; + fn current_user(&self) -> &CurrentUser { + &self.context().current_user + } /// Devuelve la zona horaria efectiva para mostrar fechas y horas en el documento. /// @@ -154,13 +302,19 @@ pub trait Contextual: LangId { /// /// [`with_request()`]: Self::with_request /// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone - fn timezone(&self) -> Tz; + fn timezone(&self) -> Tz { + self.context().timezone + } /// Devuelve el tema que se usará para renderizar el documento. - fn theme(&self) -> ThemeRef; + fn theme(&self) -> ThemeRef { + self.context().theme + } /// Devuelve la plantilla configurada para renderizar el documento. - fn template(&self) -> TemplateRef; + fn template(&self) -> TemplateRef { + self.context().template + } /// Recupera una *referencia tipada* al parámetro solicitado. /// @@ -184,7 +338,19 @@ pub trait Contextual: LangId { /// // Error de tipo: /// assert!(cx.param::("user_id").is_err()); /// ``` - fn param(&self, key: &'static str) -> Result<&T, ContextError>; + fn param(&self, key: &'static str) -> Result<&T, ContextError> { + let (any, type_name) = self + .context() + .params + .get(key) + .ok_or(ContextError::ParamNotFound)?; + any.downcast_ref::() + .ok_or_else(|| ContextError::ParamTypeMismatch { + key, + expected: TypeInfo::FullName.of::(), + saved: type_name, + }) + } /// Devuelve el parámetro clonado o el **valor por defecto del tipo** (`T::default()`). fn param_or_default(&self, key: &'static str) -> T { @@ -202,22 +368,164 @@ pub trait Contextual: LangId { } /// Devuelve el Favicon de los recursos del contexto. - fn favicon(&self) -> Option<&Favicon>; + fn favicon(&self) -> Option<&Favicon> { + self.context().favicon.as_ref() + } /// Devuelve las hojas de estilo de los recursos del contexto. - fn stylesheets(&self) -> &Assets; + fn stylesheets(&self) -> &Assets { + &self.context().stylesheets + } /// Devuelve los scripts JavaScript de los recursos del contexto. - fn javascripts(&self) -> &Assets; + fn javascripts(&self) -> &Assets { + &self.context().javascripts + } /// Devuelve los estilos *responsive* acumulados en el contexto. - fn responsive_styles(&self) -> &ResponsiveStyles; + fn responsive_styles(&self) -> &ResponsiveStyles { + &self.context().responsives + } + + /// Devuelve el título del documento, o [`Lc::none()`] si no tiene. + fn title(&self) -> &Lc { + &self.context().title + } + + /// Devuelve la descripción del documento, o [`Lc::none()`] si no tiene. + fn description(&self) -> &Lc { + &self.context().description + } + + /// Devuelve la lista de metadatos ``. + fn metadata(&self) -> &[(&'static str, CowStr)] { + &self.context().metadata + } + + /// Devuelve la lista de propiedades ``. + fn properties(&self) -> &[(&'static str, CowStr)] { + &self.context().properties + } /// Devuelve identificador, clases CSS, atributos HTML y valores extra del elemento ``. - fn body_props(&self) -> &Props; + fn body_props(&self) -> &Props { + &self.context().body_props + } + + /// Devuelve los mensajes de usuario acumulados que aún no ha mostrado ningún componente + /// [`Messages`](crate::base::component::Messages). + fn messages(&self) -> &[StatusMessage] { + &self.context().messages + } + + /// Indica si hay mensajes de usuario acumulados que aún no ha mostrado ningún componente + /// [`Messages`](crate::base::component::Messages). + fn has_messages(&self) -> bool { + !self.context().messages.is_empty() + } // **< Contextual HELPERS >********************************************************************* + /// Construye una ruta aplicada al contexto actual. + /// + /// Acepta cualquier tipo convertible a [`RoutePath`] (un literal, un `String`, un `&str` de + /// cualquier vida, o un [`RoutePath`] ya construido con sus propios parámetros). Si la política + /// de negociación del idioma ([`LangNegotiation`](crate::global::LangNegotiation)) indica que + /// debe propagarse el idioma para esta petición, se añade o actualiza automáticamente el + /// parámetro de *query* `lang=...` con el identificador de idioma definido en el contexto. + /// + /// Esto garantiza que los enlaces generados desde el contexto preservan la preferencia de + /// idioma del usuario durante la navegación. Si `path` **parece** una URL externa (ver + /// [`util::url_looks_external()`](crate::util::url_looks_external)), nunca se le añade `lang`. + /// + /// Este método asume que ya tienes `cx` a mano en el momento de construir la ruta (dentro de + /// `prepare()`, un *handler* HTTP, etc.). Si lo que estás definiendo es un campo de componente + /// que se construye una sola vez y se reutiliza en peticiones futuras (un menú, un botón, + /// etc.), usa [`Route`](crate::core::component::Route) en su lugar (su documentación explica el + /// criterio completo para elegir entre ambos). + fn route(&self, path: impl Into) -> RoutePath { + let locale = &self.context().locale; + let mut route = path.into(); + if !route.is_external() && locale.needs_lang_query() { + route.alter_param("lang", locale.lang_query_value()); + } + route + } + + /// Construye un identificador HTML único para el tipo de componente `C`. + /// + /// Toma los `segments` finales del *path* completo del tipo, los une con `-` y los convierte a + /// minúsculas, y añade un contador independiente por tipo. Por ejemplo, para `MyApp::ui::Menu` + /// con `segments = 2` devuelve `ui-menu-1` la primera vez que se invoca para ese tipo, + /// `ui-menu-2` la segunda, etc. + /// + /// Con `segments = 1` se usa sólo el nombre corto del tipo. Si `segments` es `0` o supera el + /// número de segmentos del *path*, se usan todos. + /// + /// Es útil para asignar identificadores cuando el componente no recibe uno explícito. El + /// contador es local a este contexto y se reinicia para cada nueva petición. + fn build_id(&self, segments: usize) -> String { + let path: Vec<&str> = TypeInfo::FullName.of::().split("::").collect(); + let segments = if segments == 0 || segments >= path.len() { + path.len() + } else { + segments + }; + let count = { + let mut map = self.context().id_counters.lock(); + let n = map.entry(TypeId::of::()).or_insert(0); + *n += 1; + *n + }; + let prefix = path[path.len() - segments..].join("-").to_lowercase(); + util::join!(prefix, "-", count.to_string()) + } + + /// Devuelve `id` si contiene un valor, o genera uno único con [`build_id`](Self::build_id) + /// si es `None`. + fn required_id(&self, id: Option, segments: usize) -> String { + match id { + Some(id) => id, + None => self.build_id::(segments), + } + } + + /// 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. 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 + /// + /// ```rust,no_run + /// # use pagetop::prelude::*; + /// # let mut cx = Context::default(); + /// cx.push_message(MessageLevel::Warning, Lc::n("Session is not valid")); + /// ``` + fn push_message(&mut self, level: MessageLevel, text: Lc) { + self.context_mut() + .messages + .push(StatusMessage::new(level, text)); + } + + /// Elimina un parámetro del contexto. Devuelve `true` si la clave existía y se eliminó. + /// + /// # Ejemplo + /// + /// ```rust + /// # use pagetop::prelude::*; + /// let mut cx = Context::default().with_param("temp", 1u8); + /// assert!(cx.remove_param("temp")); + /// assert!(!cx.remove_param("temp")); // ya no existe + /// ``` + fn remove_param(&mut self, key: &'static str) -> bool { + self.context_mut().params.remove(key).is_some() + } + /// Formatea una fecha y hora completas en la zona horaria efectiva del documento /// ([`timezone()`](Self::timezone)), combinando un [`DateFormat`] y un [`TimeFormat`] /// independientes (posiblemente distintos entre sí, como una fecha larga con la hora corta), @@ -471,16 +779,19 @@ pub trait Contextual: LangId { { crate::datetime::input::parse_datetime(text, self, self.timezone()) } - - /// Elimina un parámetro del contexto. Devuelve `true` si la clave existía y se eliminó. - /// - /// # Ejemplo - /// - /// ```rust - /// # use pagetop::prelude::*; - /// let mut cx = Context::default().with_param("temp", 1u8); - /// assert!(cx.remove_param("temp")); - /// assert!(!cx.remove_param("temp")); // ya no existe - /// ``` - fn remove_param(&mut self, key: &'static str) -> bool; +} + +/// Cualquier contexto de renderizado es proveedor de idioma, con el idioma del documento. +/// +/// El idioma lo resuelve [`RequestLocale`], que tiene en cuenta la petición HTTP (parámetro `?lang` +/// e idioma preferido del usuario), la configuración global de idioma de la aplicación, la cabecera +/// `Accept-Language` y/o el idioma de respaldo, según la negociación indicada en +/// [`global::SETTINGS.app.lang_negotiation`]. +/// +/// [`global::SETTINGS.app.lang_negotiation`]: crate::global::AppSettings::lang_negotiation +impl LangId for T { + #[inline] + fn langid(&self) -> &'static LanguageIdentifier { + self.context().locale.langid() + } } diff --git a/src/core/component/route.rs b/src/core/component/route.rs index 2b118b26..e2eb317d 100644 --- a/src/core/component/route.rs +++ b/src/core/component/route.rs @@ -1,4 +1,4 @@ -use crate::core::component::Context; +use crate::core::component::{Context, Contextual}; use crate::html::RoutePath; use crate::util; diff --git a/src/core/theme/definition.rs b/src/core/theme/definition.rs index e8934daf..00624fd6 100644 --- a/src/core/theme/definition.rs +++ b/src/core/theme/definition.rs @@ -192,7 +192,9 @@ pub trait Theme: Extension + Send + Sync { parent.render_page_body(page).await } else { let template = page.template(); - layout::Template::of(template).render(page.context()).await + layout::Template::of(template) + .render(page.context_mut()) + .await } } @@ -240,13 +242,13 @@ pub trait Theme: Extension + Send + Sync { html! { meta charset="utf-8"; - @if let Some(title) = page.title() { + @if let Some(title) = page.title().lookup(page) { title { (global::SETTINGS.app.name) (" | ") (title) } } @else { title { (global::SETTINGS.app.name) } } - @if let Some(description) = page.description() { + @if let Some(description) = page.description().lookup(page) { meta name="description" content=(description); } @@ -260,7 +262,7 @@ pub trait Theme: Extension + Send + Sync { meta property=(property) content=(content) {} } - (page.context().render_assets()) + (page.context_mut().render_assets()) } } diff --git a/src/global/lang_negotiation.rs b/src/global/lang_negotiation.rs index 6ab4de40..7a211689 100644 --- a/src/global/lang_negotiation.rs +++ b/src/global/lang_negotiation.rs @@ -11,7 +11,7 @@ use serde::{Deserialize, Deserializer}; /// /// [`global::SETTINGS.app.lang_negotiation`]: crate::global::AppSettings::lang_negotiation /// [`RequestLocale`]: crate::locale::RequestLocale -/// [`Context::route()`]: crate::core::component::Context::route +/// [`Context::route()`]: crate::core::component::Contextual::route #[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)] pub enum LangNegotiation { /// Usa todas las fuentes disponibles para determinar el idioma, en este orden: comprueba el diff --git a/src/response/flash.rs b/src/response/flash.rs index 61216df5..c61b6543 100644 --- a/src/response/flash.rs +++ b/src/response/flash.rs @@ -61,7 +61,7 @@ struct Pending(Vec<(MessageLevel, String)>); /// } /// ``` /// -/// [`Context::push_message()`]: crate::core::component::Context::push_message +/// [`Context::push_message()`]: crate::core::component::Contextual::push_message /// [`CoreRegions::Content`]: crate::core::theme::CoreRegions::Content /// [`Messages`]: crate::base::component::Messages pub trait ResponseExt { diff --git a/src/response/page.rs b/src/response/page.rs index b31db6aa..9c2eb966 100644 --- a/src/response/page.rs +++ b/src/response/page.rs @@ -18,19 +18,14 @@ mod error; pub use error::ErrorPage; pub(crate) use error::{render_error_pages, response_for_panic, route_not_found}; -use crate::auth::CurrentUser; +use crate::AutoDefault; use crate::base::action; use crate::base::component::layout; -use crate::core::component::{AssetsOp, ChildOp, ComponentRender}; -use crate::core::component::{Context, ContextError, Contextual}; -use crate::core::theme::{CoreRegions, RegionName, RegionRef, TemplateRef, ThemeRef}; -use crate::datetime::Tz; -use crate::html::{Assets, Favicon, JavaScript, ResponsiveStyles, StyleSheet}; +use crate::core::component::{ComponentRender, Context, Contextual}; +use crate::core::theme::RegionName; use crate::html::{DOCTYPE, Markup, html}; -use crate::html::{Props, PropsOp}; -use crate::locale::{CharacterDirection, LangId, LanguageIdentifier, Lc}; +use crate::locale::{CharacterDirection, LangId, Lc}; use crate::web::HttpRequest; -use crate::{AutoDefault, builder_impl}; // **< ReservedRegions >**************************************************************************** @@ -83,36 +78,35 @@ impl RegionName for ReservedRegions { /// Representa una página HTML completa lista para renderizar. /// -/// Una instancia de `Page` se compone dinámicamente permitiendo establecer título, descripción, -/// regiones donde disponer los componentes, atributos de `` y otros aspectos del contexto de -/// renderizado. -#[rustfmt::skip] +/// Envuelve el [`Context`] de renderizado de la página e implementa [`Contextual`] sobre él, así +/// que una página se mantiene con los mismos métodos que un contexto: título, descripción, regiones +/// donde disponer los componentes, atributos de ``, recursos, etc. Lo que añade `Page` es el +/// renderizado del documento completo ([`Page::render()`]). #[derive(AutoDefault)] pub struct Page { - title : Lc, - description: Lc, - metadata : Vec<(&'static str, &'static str)>, - properties : Vec<(&'static str, &'static str)>, - context : Context, + context: Context, } -#[builder_impl] impl Page { /// Crea una nueva instancia de página. /// /// La petición HTTP se guarda en el contexto de renderizado, que extrae automáticamente el - /// [`CurrentUser`] inyectado por middleware en sus extensiones (ver + /// [`CurrentUser`](crate::auth::CurrentUser) inyectado por middleware en sus extensiones (ver /// [`Context::new`](crate::core::component::Context::new)). Cualquier handler tiene acceso al /// usuario actual desde el momento en que se crea la página, sin llamadas adicionales. pub fn new(request: HttpRequest) -> Self { Page { context: Context::new(request), - ..Default::default() } } /// Crea una nueva instancia de página con la plantilla [`CoreTemplates::Admin`]. /// + /// Es la forma de crear una página del panel de administración: la plantilla añade la + /// navegación del panel y, alrededor del contenido, las migas de pan, el título + /// ([`with_title()`](Contextual::with_title)) y las pestañas y botones declarados para su ruta + /// (ver el módulo [`admin`](crate::admin)). + /// /// Cada tema puede maquetarla de forma distinta capturando [`Template`] vía /// [`Theme::render_component()`], pero la plantilla en sí es la misma constante para cualquier /// tema. @@ -123,69 +117,9 @@ impl Page { pub fn admin(request: HttpRequest) -> Self { Page { context: Context::admin(request), - ..Default::default() } } - // **< Page BUILDER >*************************************************************************** - - /// Establece el título de la página como un valor traducible. - pub fn with_title(mut self, title: Lc) -> Self { - self.title = title; - self - } - - /// Establece la descripción de la página como un valor traducible. - pub fn with_description(mut self, description: Lc) -> Self { - self.description = description; - self - } - - /// Añade una entrada `` al ``. - pub fn with_metadata(mut self, name: &'static str, content: &'static str) -> Self { - self.metadata.push((name, content)); - self - } - - /// Añade una entrada `` al ``. - pub fn with_property(mut self, property: &'static str, content: &'static str) -> Self { - self.properties.push((property, content)); - self - } - - // **< Page GETTERS >*************************************************************************** - - /// Devuelve el título traducido para el idioma de la página, si existe. - pub fn title(&self) -> Option { - self.title.lookup(&self.context) - } - - /// Devuelve la descripción traducida para el idioma de la página, si existe. - pub fn description(&self) -> Option { - self.description.lookup(&self.context) - } - - /// Devuelve la lista de metadatos ``. - pub fn metadata(&self) -> &Vec<(&'static str, &'static str)> { - &self.metadata - } - - /// Devuelve la lista de propiedades ``. - pub fn properties(&self) -> &Vec<(&'static str, &'static str)> { - &self.properties - } - - /// Devuelve una referencia mutable al [`Context`] de la página. - /// - /// El [`Context`] actúa como intermediario para muchos métodos de `Page` (idioma, tema, - /// *layout*, recursos, petición HTTP, etc.). Resulta especialmente útil cuando un componente - /// o un tema necesita recibir el contexto como parámetro. - pub fn context(&mut self) -> &mut Context { - &mut self.context - } - - // **< Page RENDER >**************************************************************************** - /// Renderiza la página completa en formato HTML. /// /// El proceso de renderizado de la página sigue esta secuencia: @@ -222,7 +156,7 @@ impl Page { /// [`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 + /// [`Context::langid()`]: crate::locale::LangId::langid /// [`Messages`]: crate::base::component::Messages pub async fn render(&mut self) -> Result { // Acciones específicas del tema antes de renderizar el . @@ -272,121 +206,14 @@ impl Page { } } -/// Permite a [`Page`] actuar como proveedor de idioma usando el [`Context`] de la página. -/// -/// Resulta útil para usar [`Page`] directamente como fuente de traducción en [`Lc::lookup()`] o -/// [`Lc::using()`]. -impl LangId for Page { - #[inline] - fn langid(&self) -> &'static LanguageIdentifier { - self.context.langid() - } -} - -#[builder_impl] impl Contextual for Page { - // **< Contextual BUILDER >********************************************************************* - - fn with_request(mut self, request: Option) -> Self { - self.context.alter_request(request); - self + #[inline] + fn context(&self) -> &Context { + &self.context } - fn with_langid(mut self, language: &impl LangId) -> Self { - self.context.alter_langid(language); - self - } - - fn with_timezone(mut self, tz: Tz) -> Self { - self.context.alter_timezone(tz); - self - } - - fn with_theme(mut self, theme: ThemeRef) -> Self { - self.context.alter_theme(theme); - self - } - - fn with_template(mut self, template: TemplateRef) -> Self { - self.context.alter_template(template); - self - } - - fn with_param(mut self, key: &'static str, value: T) -> Self { - self.context.alter_param(key, value); - self - } - - fn with_assets(mut self, op: impl Into) -> Self { - self.context.alter_assets(op); - self - } - - fn with_body_props(mut self, op: PropsOp) -> Self { - self.context.alter_body_props(op); - self - } - - fn with_child(mut self, op: impl Into) -> Self { - self.context - .alter_child_in(&CoreRegions::Content, op.into()); - self - } - - fn with_child_in(mut self, region: RegionRef, op: impl Into) -> Self { - self.context.alter_child_in(region, op.into()); - self - } - - // **< Contextual GETTERS >********************************************************************* - - fn request(&self) -> Option<&HttpRequest> { - self.context.request() - } - - fn current_user(&self) -> &CurrentUser { - self.context.current_user() - } - - fn timezone(&self) -> Tz { - self.context.timezone() - } - - fn theme(&self) -> ThemeRef { - self.context.theme() - } - - fn template(&self) -> TemplateRef { - self.context.template() - } - - fn param(&self, key: &'static str) -> Result<&T, ContextError> { - self.context.param(key) - } - - fn favicon(&self) -> Option<&Favicon> { - self.context.favicon() - } - - fn stylesheets(&self) -> &Assets { - self.context.stylesheets() - } - - fn javascripts(&self) -> &Assets { - self.context.javascripts() - } - - fn responsive_styles(&self) -> &ResponsiveStyles { - self.context.responsive_styles() - } - - fn body_props(&self) -> &Props { - self.context.body_props() - } - - // **< Contextual HELPERS >********************************************************************* - - fn remove_param(&mut self, key: &'static str) -> bool { - self.context.remove_param(key) + #[inline] + fn context_mut(&mut self) -> &mut Context { + &mut self.context } } diff --git a/src/response/waypoint.rs b/src/response/waypoint.rs index ba200fae..84d56910 100644 --- a/src/response/waypoint.rs +++ b/src/response/waypoint.rs @@ -52,9 +52,9 @@ impl Waypoint { /// Crea un valor explícito. /// /// Sólo acepta una ruta local que empiece por `/`, pero no por `//` ni `/\` que el navegador - /// interpretaría como una URL *protocol-relative*, y sin caracteres de control. Una cadena vacía, una URL absoluta - /// (`https://...`), un esquema arbitrario (`javascript:...`) o cualquier otro valor que no - /// cumpla esa forma se trata igual que `None`. + /// interpretaría como una URL *protocol-relative*, y sin caracteres de control. Una cadena + /// vacía, una URL absoluta (`https://...`), un esquema arbitrario (`javascript:...`) o + /// cualquier otro valor que no cumpla esa forma se trata igual que `None`. /// /// Este filtro protege contra *open redirect*; el `waypoint` viaja en la *query string* de la /// petición, así que un cliente malicioso lo controla por completo. Por eso se aplica siempre, @@ -96,7 +96,7 @@ impl Waypoint { /// hacia otras pantallas (ver el ejemplo). /// /// Preserva cualquier *query string* ya presente en `route` sin romperla (como `lang=...` si - /// `route` se construyó con [`Context::route()`](crate::core::component::Context::route)). + /// `route` se construyó con [`Context::route()`](crate::core::component::Contextual::route)). /// /// # Ejemplo /// diff --git a/src/util.rs b/src/util.rs index c81ef5fd..4b3a86b4 100644 --- a/src/util.rs +++ b/src/util.rs @@ -262,7 +262,7 @@ pub fn normalize_token(s: impl AsRef) -> Option { /// /// La usan [`RoutePath::is_external()`](crate::html::RoutePath::is_external) y las conversiones /// `From<&str>`/`From` de [`Route`](crate::core::component::Route) para decidir si una -/// ruta debe evitar [`Context::route()`](crate::core::component::Context::route). +/// ruta debe evitar [`Context::route()`](crate::core::component::Contextual::route). /// /// Cualquier otro código que necesite el mismo criterio (por ejemplo, para decidir si un enlace /// debe llevar `target="_blank"`) puede usarla en lugar de reimplementar su propia versión. diff --git a/tests/response_page.rs b/tests/response_page.rs index 947670e4..724723b1 100644 --- a/tests/response_page.rs +++ b/tests/response_page.rs @@ -4,12 +4,29 @@ fn request() -> HttpRequest { web::test::TestRequest::get().to_http_request() } +// Sets the document description and metadata from its own context while it renders. +#[derive(Clone)] +struct Article; + +#[async_trait] +impl Component for Article { + fn new() -> Self { + Self + } + + fn setup(&mut self, cx: &mut Context) { + cx.alter_description(Lc::n("Article summary")) + .alter_metadata("author", String::from("Article author")) + .alter_property("og:type", "article"); + } +} + #[pagetop::test] async fn title_and_description_are_absent_by_default() { let page = Page::new(request()); - assert_eq!(page.title(), None); - assert_eq!(page.description(), None); + assert!(page.title().is_none()); + assert!(page.description().is_none()); } #[pagetop::test] @@ -18,9 +35,9 @@ async fn title_and_description_reflect_the_values_set() { .with_title(Lc::n("Dashboard")) .with_description(Lc::n("Overview of recent activity")); - assert_eq!(page.title(), Some("Dashboard".to_string())); + assert_eq!(page.title().lookup(&page), Some("Dashboard".to_string())); assert_eq!( - page.description(), + page.description().lookup(&page), Some("Overview of recent activity".to_string()) ); } @@ -33,6 +50,34 @@ async fn lc_none_clears_a_previously_set_title_and_description() { .with_title(Lc::none()) .with_description(Lc::none()); - assert_eq!(page.title(), None); - assert_eq!(page.description(), None); + assert!(page.title().is_none()); + assert!(page.description().is_none()); +} + +#[pagetop::test] +async fn page_and_its_context_share_the_same_state() { + let mut page = Page::new(request()) + .with_title(Lc::n("Dashboard")) + .with_metadata("robots", "noindex"); + page.context_mut().alter_property("og:title", "Dashboard"); + + let cx = page.context(); + assert_eq!(cx.title().lookup(cx), Some("Dashboard".to_string())); + assert_eq!(cx.metadata(), &[("robots", CowStr::from("noindex"))]); + assert_eq!( + page.properties(), + &[("og:title", CowStr::from("Dashboard"))] + ); +} + +#[pagetop::test] +async fn components_can_set_the_description_and_metadata_of_the_page() { + Application::new().await; + + let mut page = Page::new(request()).with_child(Article); + let html = page.render().await.expect("page renders").into_string(); + + assert!(html.contains(r#""#)); + assert!(html.contains(r#""#)); + assert!(html.contains(r#""#)); }