diff --git a/drust/src/main.rs b/drust/src/main.rs index 76eb9426..87973883 100644 --- a/drust/src/main.rs +++ b/drust/src/main.rs @@ -1,6 +1,6 @@ use pagetop::prelude::*; -#[derive(BindHandle)] +#[derive(AssignHandle)] struct Drust; impl ModuleTrait for Drust { diff --git a/examples/basics/hello-name/src/main.rs b/examples/basics/hello-name/src/main.rs index 6d59d482..26d16c84 100644 --- a/examples/basics/hello-name/src/main.rs +++ b/examples/basics/hello-name/src/main.rs @@ -1,6 +1,6 @@ use pagetop::prelude::*; -#[derive(BindHandle)] +#[derive(AssignHandle)] struct HelloName; impl ModuleTrait for HelloName { diff --git a/examples/basics/hello-world/src/main.rs b/examples/basics/hello-world/src/main.rs index 22ee8bf3..f4c442f6 100644 --- a/examples/basics/hello-world/src/main.rs +++ b/examples/basics/hello-world/src/main.rs @@ -1,6 +1,6 @@ use pagetop::prelude::*; -#[derive(BindHandle)] +#[derive(AssignHandle)] struct HelloWorld; impl ModuleTrait for HelloWorld { diff --git a/pagetop-admin/src/lib.rs b/pagetop-admin/src/lib.rs index 26c66c66..acf69fa6 100644 --- a/pagetop-admin/src/lib.rs +++ b/pagetop-admin/src/lib.rs @@ -4,7 +4,7 @@ static_locales!(LOCALES_ADMIN); mod summary; -#[derive(BindHandle)] +#[derive(AssignHandle)] pub struct Admin; impl ModuleTrait for Admin { diff --git a/pagetop-bootsier/src/lib.rs b/pagetop-bootsier/src/lib.rs index 8ffa4b7c..b5451ee9 100644 --- a/pagetop-bootsier/src/lib.rs +++ b/pagetop-bootsier/src/lib.rs @@ -4,7 +4,7 @@ static_locales!(LOCALES_BOOTSIER); static_files!(bootsier); -#[derive(BindHandle)] +#[derive(AssignHandle)] pub struct Bootsier; impl ModuleTrait for Bootsier { diff --git a/pagetop-bulmix/src/lib.rs b/pagetop-bulmix/src/lib.rs index 6d7c0efb..5ea0a7dd 100644 --- a/pagetop-bulmix/src/lib.rs +++ b/pagetop-bulmix/src/lib.rs @@ -2,7 +2,7 @@ use pagetop::prelude::*; static_files!(bulmix); -#[derive(BindHandle)] +#[derive(AssignHandle)] pub struct Bulmix; impl ModuleTrait for Bulmix { diff --git a/pagetop-homedemo/src/lib.rs b/pagetop-homedemo/src/lib.rs index a8644494..bd70709c 100644 --- a/pagetop-homedemo/src/lib.rs +++ b/pagetop-homedemo/src/lib.rs @@ -4,7 +4,7 @@ static_locales!(LOCALES_HOMEDEMO); static_files!(homedemo); -#[derive(BindHandle)] +#[derive(AssignHandle)] pub struct HomeDemo; impl ModuleTrait for HomeDemo { diff --git a/pagetop-macros/src/lib.rs b/pagetop-macros/src/lib.rs index cb2d08e9..dbea55d1 100644 --- a/pagetop-macros/src/lib.rs +++ b/pagetop-macros/src/lib.rs @@ -103,25 +103,9 @@ pub fn test(_: TokenStream, item: TokenStream) -> TokenStream { output } -#[proc_macro_derive(ComponentClasses)] -pub fn component_classes_derive(input: TokenStream) -> TokenStream { - let input = parse_macro_input!(input as DeriveInput); - let name = &input.ident; - - let expanded = quote! { - impl ImplementClasses for #name { - fn alter_classes(&mut self, op: ClassesOp, classes: impl Into) -> &mut Self { - self.classes.alter_value(op, classes); - self - } - - fn classes(&self) -> &OptionClasses { - &self.classes - } - } - }; - - TokenStream::from(expanded) +#[proc_macro_derive(AssignHandle, attributes(handle))] +pub fn assign_handle_derive(input: TokenStream) -> TokenStream { + impl_handle(input, quote! { pagetop }) } #[proc_macro_derive(BaseHandle, attributes(handle))] @@ -129,11 +113,6 @@ pub fn base_handle_derive(input: TokenStream) -> TokenStream { impl_handle(input, quote! { crate }) } -#[proc_macro_derive(BindHandle, attributes(handle))] -pub fn bind_handle_derive(input: TokenStream) -> TokenStream { - impl_handle(input, quote! { pagetop }) -} - fn impl_handle(input: TokenStream, crate_name: TokenStream2) -> TokenStream { let input = parse_macro_input!(input as DeriveInput); let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl(); @@ -165,3 +144,24 @@ fn impl_handle(input: TokenStream, crate_name: TokenStream2) -> TokenStream { TokenStream::from(expanded) } + +#[proc_macro_derive(ComponentClasses)] +pub fn component_classes_derive(input: TokenStream) -> TokenStream { + let input = parse_macro_input!(input as DeriveInput); + let name = &input.ident; + + let expanded = quote! { + impl ImplementClasses for #name { + fn alter_classes(&mut self, op: ClassesOp, classes: impl Into) -> &mut Self { + self.classes.alter_value(op, classes); + self + } + + fn classes(&self) -> &OptionClasses { + &self.classes + } + } + }; + + TokenStream::from(expanded) +} diff --git a/pagetop-node/src/lib.rs b/pagetop-node/src/lib.rs index 26827674..c8f607d3 100644 --- a/pagetop-node/src/lib.rs +++ b/pagetop-node/src/lib.rs @@ -5,7 +5,7 @@ static_locales!(LOCALES_NODE); //mod entity; mod migration; -#[derive(BindHandle)] +#[derive(AssignHandle)] pub struct Node; impl ModuleTrait for Node { diff --git a/pagetop-user/src/lib.rs b/pagetop-user/src/lib.rs index 7285b873..1d26dd36 100644 --- a/pagetop-user/src/lib.rs +++ b/pagetop-user/src/lib.rs @@ -4,7 +4,7 @@ static_locales!(LOCALES_USER); mod migration; -#[derive(BindHandle)] +#[derive(AssignHandle)] pub struct User; impl ModuleTrait for User { diff --git a/pagetop/src/app.rs b/pagetop/src/app.rs index d4e4b1ed..226e2278 100644 --- a/pagetop/src/app.rs +++ b/pagetop/src/app.rs @@ -1,4 +1,4 @@ -//! Instancia y ejecuta una aplicación creada con **PageTop**. +//! Prepare and run an application created with **Pagetop**. mod figfont; diff --git a/pagetop/src/base.rs b/pagetop/src/base.rs index acfd1dbe..dd717d1b 100644 --- a/pagetop/src/base.rs +++ b/pagetop/src/base.rs @@ -1,3 +1,5 @@ +//! Base actions, components, modules, and themes. + pub mod action; pub mod component; diff --git a/pagetop/src/config.rs b/pagetop/src/config.rs index 65779f17..8faeb4f3 100644 --- a/pagetop/src/config.rs +++ b/pagetop/src/config.rs @@ -1,4 +1,4 @@ -//! Read configuration files and use settings. +//! Retrieve and apply settings values from configuration files. //! //! Carga la configuración de la aplicación en forma de pares `clave = valor` recogidos en archivos //! [TOML](https://toml.io). diff --git a/pagetop/src/core.rs b/pagetop/src/core.rs index aa9819b9..c6f28063 100644 --- a/pagetop/src/core.rs +++ b/pagetop/src/core.rs @@ -1,4 +1,4 @@ -//! Tipos y funciones esenciales para crear acciones, componentes, módulos y temas. +//! Key types and functions for creating actions, components, modules, and themes. // API to define functions that alter the behavior of PageTop core. pub mod action; diff --git a/pagetop/src/datetime.rs b/pagetop/src/datetime.rs index 618ce05c..732431df 100644 --- a/pagetop/src/datetime.rs +++ b/pagetop/src/datetime.rs @@ -1,4 +1,4 @@ -//! PageTop uses the [Chrono](https://docs.rs/chrono) Rust library to add -//! [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time related data. +//! [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time handling +//! ([chrono](https://docs.rs/chrono)). pub use chrono::prelude::*; diff --git a/pagetop/src/db.rs b/pagetop/src/db.rs index fb652c11..58730818 100644 --- a/pagetop/src/db.rs +++ b/pagetop/src/db.rs @@ -1,4 +1,4 @@ -//! Acceso unificado y normalizado a base de datos. +//! Database access. use crate::{config, trace, LazyStatic}; diff --git a/pagetop/src/html.rs b/pagetop/src/html.rs index 298fd41d..007a14ef 100644 --- a/pagetop/src/html.rs +++ b/pagetop/src/html.rs @@ -1,4 +1,4 @@ -//! HTML en código. +//! HTML in code. mod maud; pub use maud::{html, html_private, Markup, PreEscaped, DOCTYPE}; diff --git a/pagetop/src/lib.rs b/pagetop/src/lib.rs index eca5b591..78789835 100644 --- a/pagetop/src/lib.rs +++ b/pagetop/src/lib.rs @@ -9,42 +9,44 @@ //! //! //! -//! **PageTop** es un entorno de desarrollo basado en Rust que reúne algunos de los crates más -//! estables y populares para crear soluciones web modulares, extensibles y configurables. +//! **PageTop** is an opinionated Rust web development framework to build secure, modular and +//! configurable Server-Side Rendering (SSR) web solutions. //! -//! PageTop define un interfaz único para aplicaciones SSR (*Server-Side Rendering*) que ofrece: +//! PageTop brings together some of the most stable and popular Rust crates providing: //! -//! * Lectura y uso de ajustes de configuración ([`config`]). +//! * Retrieve and apply settings values from configuration files ([`config`]). //! -//! * Registro de trazas y eventos de la aplicación ([`trace`]). +//! * Application tracing and event logging ([`trace`]). //! -//! * HTML en código ([`html`]). +//! * HTML in code ([`html`]). //! -//! * Localización ([`locale`]). +//! * Localization ([`locale`]). //! -//! * [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time handling ([`datetime`]). +//! * [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time handling ([`datetime`]). //! -//! * Acceso unificado y normalizado a base de datos ([`db`]). +//! * Database access ([`db`]). //! -//! * Tipos y funciones esenciales para crear acciones, componentes, módulos y temas ([`core`]). +//! * Essential web framework ([`service`]). //! -//! * Tipos de respuestas a peticiones web ([`response`]) +//! * Key types and functions for creating actions, components, modules, and themes ([`core`]). //! -//! * Funciones útiles ([`util`]). +//! * Web request response variants ([`response`]). //! -//! # 🚧 Advertencia +//! * Base actions, components, modules, and themes ([`base`]). //! -//! **PageTop** sólo libera actualmente versiones de desarrollo. La API no es estable y los cambios -//! son constantes. No puede considerarse preparado hasta que se libere la versión **0.1.0**. +//! * Utility functions ([`util`]). //! -//! # ⚡️ Inicio rápido +//! # 🚧 Warning +//! +//! **PageTop** framework is currently in active development. The API is unstable and subject to +//! frequent changes. Production use is not recommended until version **0.1.0**. +//! +//! # ⚡️ Quick start //! -//! Puedes encontrar este código en el repositorio de ejemplos -//! [básicos](https://github.com/manuelcillero/pagetop/tree/main/examples/basics) de PageTop: //! ```rust //! use pagetop::prelude::*; //! -//! #[derive(BindHandle)] +//! #[derive(AssignHandle)] //! struct HelloWorld; //! //! impl ModuleTrait for HelloWorld { @@ -64,34 +66,34 @@ //! Application::prepare(&HelloWorld).unwrap().run()?.await //! } //! ``` -//! Este programa crea un módulo llamado `HelloWorld` con un servicio que devuelve una página web -//! saludando al mundo cada vez que se accede desde el navegador a `http://localhost:8088` (para -//! los [ajustes de configuración](`config::Server`) predeterminados). +//! This program implements a module named `HelloWorld` with one service that returns a web page +//! that greets the world whenever it is accessed from the browser at `http://localhost:8088` (using +//! the [default configuration settings](`config::Server`)). You can find this code in the PageTop +//! [basic examples repository](https://github.com/manuelcillero/pagetop/tree/main/examples/basics). //! -//! # 🧱 Extendiendo PageTop +//! # 🧱 Extending PageTop //! -//! La API de PageTop no sólo sirve para crear aplicaciones, también permite extender sus -//! funcionalidades con el desarrollo de acciones, componentes, módulos o nuevos temas: +//! The PageTop core API provides a comprehensive toolkit for extending its functionalities to +//! specific requirements and application scenarios through actions, components, modules, and +//! themes: //! -//! * Las **acciones** permiten alterar el comportamiento del propio funcionamiento interno de -//! PageTop. Las acciones se ofrecen al desarrollador para interactuar con la ejecución de -//! procesos que pueden ser modificados. -//! * Los **componentes** incluyen código HTML, CSS y/o Javascript en unidades que tienen una -//! funcionalidad bien definida y configurable durante la creación de páginas web. -//! * Los **módulos** añaden funcionalidades o modifican las ya existentes usando las APIs globales -//! o las de otros módulos de PageTop o de terceros. -//! * Los **temas** son módulos que permiten cambiar la disposición y el aspecto de las páginas y -//! componentes sin necesidad de alterar su funcionamiento. Estructuran las páginas en regiones -//! donde disponer los diferentes componentes. +//! * **Actions** serve as a mechanism to customize PageTop's internal behavior by intercepting its +//! execution flow. +//! * **Components** encapsulate HTML, CSS, and JavaScript into functional, configurable, and +//! well-defined units. +//! * **Modules** extend or customize existing functionality by interacting with PageTop APIs or +//! third-party module APIs. +//! * **Themes** enable developers to alter the appearance of pages and components without affecting +//! their functionality. //! -//! # 🧩 Dependencias +//! # 🧩 Dependency Management //! -//! Las aplicaciones usarán `cargo` para resolver las dependencias entre PageTop y las extensiones -//! de terceros que implementen acciones, componentes, módulos y/o temas; de la misma manera que se -//! hace en cualquier otro proyecto. +//! Projects leveraging PageTop will use `cargo` to resolve dependencies, similar to any other Rust +//! project. //! -//! Pero también deberán declararse explícitamente estas dependencias en cada módulo para ayudar a -//! PageTop a estructurar e inicializar modularmente la aplicación. +//! Nevertheless, it’s crucial that each module explicitly declares its +//! [dependencies](core::module::ModuleTrait#method.dependencies), if any, to assist PageTop in +//! structuring and initializing the application in a modular fashion. #![cfg_attr(docsrs, feature(doc_cfg))] @@ -108,7 +110,7 @@ pub use paste::paste; /// customized default values. pub use smart_default::SmartDefault; -pub use pagetop_macros::{fn_with, main, test, BindHandle, ComponentClasses}; +pub use pagetop_macros::{fn_with, main, test, AssignHandle, ComponentClasses}; pub(crate) use pagetop_macros::BaseHandle; @@ -146,35 +148,35 @@ static_locales!(LOCALES_PAGETOP); // Functions and macro helpers. pub mod util; -// Gestión de la configuración. +// Retrieve and apply settings values from configuration files. pub mod config; -// Registro de trazas y eventos de la aplicación. +// Application tracing and event logging. pub mod trace; -// HTML en código. +// HTML in code. pub mod html; -// Localización. +// Localization. pub mod locale; -// Date and time for PageTop. +// Date and time handling. pub mod datetime; -// Acceso a base de datos. +// Database access. #[cfg_attr(docsrs, doc(cfg(feature = "database")))] #[cfg(feature = "database")] pub mod db; -// API para operar con los servicios web. +// Essential web framework. pub mod service; -// APIs esenciales para crear acciones, componentes, módulos y temas. +// Key types and functions for creating actions, components, modules, and themes. pub mod core; -// Tipos de respuestas a peticiones web. +// Web request response variants. pub mod response; -// Base de acciones, componentes, módulos y temas. +// Base actions, components, modules, and themes. pub mod base; -// Prepara y ejecuta la aplicación. +// Prepare and run the application. pub mod app; // ************************************************************************************************* diff --git a/pagetop/src/locale.rs b/pagetop/src/locale.rs index 00833845..25c65613 100644 --- a/pagetop/src/locale.rs +++ b/pagetop/src/locale.rs @@ -1,4 +1,4 @@ -//! Localización (L10n). +//! Localization (L10n). //! //! PageTop usa el conjunto de especificaciones [Fluent](https://www.projectfluent.org/) para la //! localización de aplicaciones. diff --git a/pagetop/src/prelude.rs b/pagetop/src/prelude.rs index b12fe6d2..5fa6006d 100644 --- a/pagetop/src/prelude.rs +++ b/pagetop/src/prelude.rs @@ -8,7 +8,7 @@ pub use crate::{Handle, HashMapResources, ImplementHandle, LazyStatic, Weight}; // Functions and macro helpers. pub use crate::util; -pub use crate::{kv, BindHandle, ComponentClasses}; +pub use crate::{kv, AssignHandle, ComponentClasses}; // MACROS. diff --git a/pagetop/src/response.rs b/pagetop/src/response.rs index 72215229..638bfb0a 100644 --- a/pagetop/src/response.rs +++ b/pagetop/src/response.rs @@ -1,4 +1,4 @@ -//! Types of web request responses. +//! Web request response variants. pub use actix_web::ResponseError; diff --git a/pagetop/src/service.rs b/pagetop/src/service.rs index 9922e88c..f2cd24f2 100644 --- a/pagetop/src/service.rs +++ b/pagetop/src/service.rs @@ -1,4 +1,4 @@ -//! Tipos y funciones para operar con el servidor web ([actix-web](https://docs.rs/actix-web)). +//! Essential web framework ([actix-web](https://docs.rs/actix-web)). pub use actix_session::Session; pub use actix_web::body::BoxBody; diff --git a/pagetop/src/trace.rs b/pagetop/src/trace.rs index f37dd33c..2ebf6881 100644 --- a/pagetop/src/trace.rs +++ b/pagetop/src/trace.rs @@ -1,4 +1,4 @@ -//! Registro de trazas y eventos de la aplicación. +//! Application tracing and event logging. //! //! PageTop recopila la información de diagnóstico de la aplicación de manera estructurada y basada //! en eventos. diff --git a/pagetop/tests/server/health_check.rs b/pagetop/tests/server/health_check.rs index 0d3543ae..ba3df6de 100644 --- a/pagetop/tests/server/health_check.rs +++ b/pagetop/tests/server/health_check.rs @@ -1,6 +1,6 @@ use pagetop::prelude::*; -#[derive(BindHandle)] +#[derive(AssignHandle)] struct HealthCheck; impl ModuleTrait for HealthCheck {}