+
+
Tema de PageTop que muestra esquemáticamente la composición de las páginas HTML.
+Tema para PageTop que muestra esquemáticamente la composición de las páginas HTML.
[](https://docs.rs/pagetop-aliner) [](https://crates.io/crates/pagetop-aliner) [](https://crates.io/crates/pagetop-aliner) [](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-aliner#licencia) +Extensión para PageTop que integra HTMX para enriquecer las páginas con interacciones dinámicas.
- -[](https://docs.rs/pagetop-htmx) -[](https://crates.io/crates/pagetop-htmx) -[](https://crates.io/crates/pagetop-htmx) -[](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-htmx#licencia) - -Extensión para PageTop que integra HTMX para enriquecer las páginas con interacciones dinámicas.
- -[](https://docs.rs/pagetop-htmx) -[](https://crates.io/crates/pagetop-htmx) -[](https://crates.io/crates/pagetop-htmx) -[](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-htmx#licencia) - -Genera o prepara archivos estáticos para servirlos o incluirlos en un proyecto PageTop.
+Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el binario de un proyecto PageTop.
[](https://docs.rs/pagetop-build) [](https://crates.io/crates/pagetop-build) @@ -11,85 +11,91 @@ -## Sobre PageTop +## 🧭 Sobre PageTop [PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript. -## Guía rápida -La convención recomendada para extensiones, temas o aplicaciones basadas en **PageTop** es separar -los archivos fuente de los generados siguiendo el patrón `assets/` -> `static/`: +## ⚡️ Guía rápida -- **`assets/`** - archivos versionados en el repositorio, por ejemplo archivos SCSS, JavaScript de - terceros, fuentes, etc. Todo lo que hay aquí se sube al repositorio y será la fuente para generar - el directorio final `static/`. -- **`static/`** - archivos generados en tiempo de compilación a partir de `assets/`. Se añade a - `.gitignore` y nunca se sube al repositorio. -- **`build.rs`** - orquesta la transformación: genera `static/` desde `assets/` para servirlos o - incluirlos en el proyecto. +Añadir en el archivo `Cargo.toml` del proyecto: -Durante el desarrollo, `static/` existe en disco y los archivos se sirven desde ahí. En producción, -el directorio no existe y los recursos salen del binario. La macro -[`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html) -gestiona esta dualidad de forma transparente. +```toml +[build-dependencies] +pagetop-build = { ... } +``` -### Funciones de transformación +Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los +archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso: -Estas funciones se usan en el `build.rs` de cada proyecto para generar `static/` a partir de -`assets/`. Todas crean el directorio padre del destino si no existe y devuelven `io::Result<()>` -para poder propagarse con `?` en caso de error. +### Incluir archivos estáticos desde un directorio -- `compile_scss()` - compila un archivo SCSS a CSS minificado. -- `copy_dir()` - copia recursivamente un directorio completo. Útil para copiar todos los archivos de - `assets/` o de un subdirectorio a `static/` sin transformación. -- `copy_file()` - copia un archivo al destino. -- `copy_file_replacing()` - copia un archivo aplicando una lista de sustituciones de texto en su - contenido; útil para actualizar referencias internas (p.ej. `sourceMappingURL`) al renombrar - archivos. -- `minify_js()` - minifica un archivo JavaScript. - -### Incluir los archivos estáticos en el proyecto - -Una vez generado `static/`, usaremos `StaticFilesBundle` para incluir su contenido en el binario. Se -pueden crear tantos paquetes de recursos como sea necesario, siempre que tengan nombres distintos: +Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por +ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos: ```rust,no_run use pagetop_build::StaticFilesBundle; fn main() -> std::io::Result<()> { - StaticFilesBundle::from_dir("./static/css", None) - .with_name("app_css") - .build()?; - StaticFilesBundle::from_dir("./static/fonts", None) - .with_name("app_fonts") + StaticFilesBundle::from_dir("./static", None) + .with_name("guides") .build() } ``` -Si es necesario excluir algunos archivos del paquete de recursos (p. ej. los archivos `.map` que no -son necesarios en producción), se puede pasar una función de filtro: +Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por +ejemplo: ```rust,no_run use pagetop_build::StaticFilesBundle; use std::path::Path; fn main() -> std::io::Result<()> { - StaticFilesBundle::from_dir("./static/js", Some(only_js)) - .with_name("app_js") - .build() -} + fn only_pdf_files(path: &Path) -> bool { + // Selecciona únicamente los archivos con extensión `.pdf`. + path.extension().map_or(false, |ext| ext == "pdf") + } -fn only_js(path: &Path) -> bool { - path.extension().map_or(false, |ext| ext == "js") + StaticFilesBundle::from_dir("./static", Some(only_pdf_files)) + .with_name("guides") + .build() } ``` -Cada paquete de recursos genera un archivo `.rs` en -[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts). -No es necesario acceder a él directamente: el nombre asignado con `.with_name()` se usa como -identificador en `serve_static_files!` para configurar la ruta del servicio: +### Compilar archivos SCSS a CSS + +Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con +el archivo CSS minificado obtenido. Por ejemplo: + +```rust,no_run +use pagetop_build::StaticFilesBundle; + +fn main() -> std::io::Result<()> { + StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css") + .with_name("main_styles") + .build() +} +``` + +Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso +llamado `main_styles` que contiene el archivo `styles.min.css` obtenido. + + +## 📦 Archivos generados + +Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar +[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts) +donde se incluye el código necesario para compilar el proyecto. Por ejemplo, para +`with_name("guides")` se genera un archivo llamado `guides.rs`. + +No hay ningún problema en generar más de un conjunto de recursos para cada proyecto siempre que se +usen nombres diferentes. + +Normalmente no habrá que acceder a estos módulos; sólo declarar el nombre del conjunto de recursos +en [`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html) +para configurar un servicio web que sirva los archivos desde la ruta indicada. Por ejemplo: ```rust,ignore use pagetop::prelude::*; @@ -97,54 +103,22 @@ use pagetop::prelude::*; pub struct MyExtension; impl Extension for MyExtension { - fn configure_router(&self, mut router: Router) -> Router { - serve_static_files!(router, ["./static/css", app_css] => "/public/css"); - router + // Servicio web que publica los recursos de `guides` en `/ruta/a/guides`. + fn configure_service(&self, scfg: &mut service::web::ServiceConfig) { + serve_static_files!(scfg, guides => "/ruta/a/guides"); } } ``` -## Ejemplo completo -```rust,no_run -use pagetop_build::StaticFilesBundle; -use pagetop_build::{compile_scss, copy_file, copy_file_replacing, minify_js}; -use std::path::Path; - -fn main() -> std::io::Result<()> { - // Regenera `static/` desde cero sólo si hay cambios en `assets/`. - println!("cargo:rerun-if-changed=assets"); - let _ = std::fs::remove_dir_all("static"); - - // Genera `static/` a partir de `assets/`. - compile_scss("assets/main.scss", "static/css/main.min.css")?; - copy_file("assets/fonts/icon.woff2", "static/fonts/icon.woff2")?; - copy_file_replacing( - "assets/lib.min.js", - "static/js/app.min.js", - &[("lib.min.js.map", "app.min.js.map")], - )?; - minify_js("assets/shell.js", "static/js/shell.min.js")?; - - // Prepara los paquetes de recursos para incluir en el proyecto. - StaticFilesBundle::from_dir("./static/css", None).with_name("app_css").build()?; - StaticFilesBundle::from_dir("./static/js", Some(only_js)).with_name("app_js").build()?; - StaticFilesBundle::from_dir("./static/fonts", None).with_name("app_fonts").build() -} - -// Los `.map` no se incluyen, se servirán desde disco durante el desarrollo. -fn only_js(path: &Path) -> bool { - path.extension().map_or(false, |ext| ext == "js") -} -``` - -## Advertencia +## 🚧 Advertencia **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión **1.0.0**. -## Licencia + +## 📜 Licencia El código está disponible bajo una doble licencia: diff --git a/helpers/pagetop-build/src/lib.rs b/helpers/pagetop-build/src/lib.rs index 5a9d24bb..eacb6180 100644 --- a/helpers/pagetop-build/src/lib.rs +++ b/helpers/pagetop-build/src/lib.rs @@ -3,7 +3,7 @@Genera o prepara archivos estáticos para servirlos o incluirlos en un proyecto PageTop.
+Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el binario de un proyecto PageTop.
[](https://docs.rs/pagetop-build) [](https://crates.io/crates/pagetop-build) @@ -18,79 +18,85 @@ clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript. -## Guía rápida -La convención recomendada para extensiones, temas o aplicaciones basadas en **PageTop** es separar -los archivos fuente de los generados siguiendo el patrón `assets/` -> `static/`: +# ⚡️ Guía rápida -- **`assets/`** - archivos versionados en el repositorio, por ejemplo archivos SCSS, JavaScript de - terceros, fuentes, etc. Todo lo que hay aquí se sube al repositorio y será la fuente para generar - el directorio final `static/`. -- **`static/`** - archivos generados en tiempo de compilación a partir de `assets/`. Se añade a - `.gitignore` y nunca se sube al repositorio. -- **`build.rs`** - orquesta la transformación: genera `static/` desde `assets/` para servirlos o - incluirlos en el proyecto. +Añadir en el archivo `Cargo.toml` del proyecto: -Durante el desarrollo, `static/` existe en disco y los archivos se sirven desde ahí. En producción, -el directorio no existe y los recursos salen del binario. La macro -[`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html) -gestiona esta dualidad de forma transparente. +```toml +[build-dependencies] +pagetop-build = { ... } +``` -### Funciones de transformación +Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los +archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso: -Estas funciones se usan en el `build.rs` de cada proyecto para generar `static/` a partir de -`assets/`. Todas crean el directorio padre del destino si no existe y devuelven `io::Result<()>` -para poder propagarse con `?` en caso de error. +## Incluir archivos estáticos desde un directorio -- `compile_scss()` - compila un archivo SCSS a CSS minificado. -- `copy_dir()` - copia recursivamente un directorio completo. Útil para copiar todos los archivos de - `assets/` o de un subdirectorio a `static/` sin transformación. -- `copy_file()` - copia un archivo al destino. -- `copy_file_replacing()` - copia un archivo aplicando una lista de sustituciones de texto en su - contenido; útil para actualizar referencias internas (p.ej. `sourceMappingURL`) al renombrar - archivos. -- `minify_js()` - minifica un archivo JavaScript. - -### Incluir los archivos estáticos en el proyecto - -Una vez generado `static/`, usaremos `StaticFilesBundle` para incluir su contenido en el binario. Se -pueden crear tantos paquetes de recursos como sea necesario, siempre que tengan nombres distintos: +Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por +ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos: ```rust,no_run use pagetop_build::StaticFilesBundle; fn main() -> std::io::Result<()> { - StaticFilesBundle::from_dir("./static/css", None) - .with_name("app_css") - .build()?; - StaticFilesBundle::from_dir("./static/fonts", None) - .with_name("app_fonts") + StaticFilesBundle::from_dir("./static", None) + .with_name("guides") .build() } ``` -Si es necesario excluir algunos archivos del paquete de recursos (p. ej. los archivos `.map` que no -son necesarios en producción), se puede pasar una función de filtro: +Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por +ejemplo: ```rust,no_run use pagetop_build::StaticFilesBundle; use std::path::Path; fn main() -> std::io::Result<()> { - StaticFilesBundle::from_dir("./static/js", Some(only_js)) - .with_name("app_js") - .build() -} + fn only_pdf_files(path: &Path) -> bool { + // Selecciona únicamente los archivos con extensión `.pdf`. + path.extension().map_or(false, |ext| ext == "pdf") + } -fn only_js(path: &Path) -> bool { - path.extension().map_or(false, |ext| ext == "js") + StaticFilesBundle::from_dir("./static", Some(only_pdf_files)) + .with_name("guides") + .build() } ``` -Cada paquete de recursos genera un archivo `.rs` en -[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts). -No es necesario acceder a él directamente: el nombre asignado con `.with_name()` se usa como -identificador en `serve_static_files!` para configurar la ruta del servicio: +## Compilar archivos SCSS a CSS + +Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con +el archivo CSS minificado obtenido. Por ejemplo: + +```rust,no_run +use pagetop_build::StaticFilesBundle; + +fn main() -> std::io::Result<()> { + StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css") + .with_name("main_styles") + .build() +} +``` + +Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso +llamado `main_styles` que contiene el archivo `styles.min.css` obtenido. + + +# 📦 Archivos generados + +Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar +[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts) +donde se incluye el código necesario para compilar el proyecto. Por ejemplo, para +`with_name("guides")` se genera un archivo llamado `guides.rs`. + +No hay ningún problema en generar más de un conjunto de recursos para cada proyecto siempre que se +usen nombres diferentes. + +Normalmente no habrá que acceder a estos módulos; sólo declarar el nombre del conjunto de recursos +en [`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html) +para configurar un servicio web que sirva los archivos desde la ruta indicada. Por ejemplo: ```rust,ignore use pagetop::prelude::*; @@ -98,77 +104,39 @@ use pagetop::prelude::*; pub struct MyExtension; impl Extension for MyExtension { + /// Registra los recursos de `guides` en el router bajo `/ruta/a/guides`. fn configure_router(&self, mut router: Router) -> Router { - serve_static_files!(router, ["./static/css", app_css] => "/public/css"); + serve_static_files!(router, [guides] => "/ruta/a/guides"); router } } ``` - -## Ejemplo completo - -```rust,no_run -use pagetop_build::StaticFilesBundle; -use pagetop_build::{compile_scss, copy_file, copy_file_replacing, minify_js}; -use std::path::Path; - -fn main() -> std::io::Result<()> { - // Regenera `static/` desde cero sólo si hay cambios en `assets/`. - println!("cargo:rerun-if-changed=assets"); - let _ = std::fs::remove_dir_all("static"); - - // Genera `static/` a partir de `assets/`. - compile_scss("assets/main.scss", "static/css/main.min.css")?; - copy_file("assets/fonts/icon.woff2", "static/fonts/icon.woff2")?; - copy_file_replacing( - "assets/lib.min.js", - "static/js/app.min.js", - &[("lib.min.js.map", "app.min.js.map")], - )?; - minify_js("assets/shell.js", "static/js/shell.min.js")?; - - // Prepara los paquetes de recursos para incluir en el proyecto. - StaticFilesBundle::from_dir("./static/css", None).with_name("app_css").build()?; - StaticFilesBundle::from_dir("./static/js", Some(only_js)).with_name("app_js").build()?; - StaticFilesBundle::from_dir("./static/fonts", None).with_name("app_fonts").build() -} - -// Los `.map` no se incluyen, se servirán desde disco durante el desarrollo. -fn only_js(path: &Path) -> bool { - path.extension().map_or(false, |ext| ext == "js") -} -``` */ #![doc( - html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico" + html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico" )] use grass::{Options, OutputStyle, from_path}; -use minify_js::{Session, TopLevelMode, minify}; -use pagetop_statics::resource_dir; +use pagetop_statics::{ResourceDir, resource_dir}; -use std::fs::{File, copy as fs_copy, create_dir_all, read_dir}; -use std::io::{self, Write}; -use std::path::{Path, PathBuf}; +use std::fs::{File, create_dir_all, remove_dir_all}; +use std::io::Write; +use std::path::Path; -// **< StaticFilesBundle >************************************************************************** - -/// Prepara un paquete de recursos para incluir en el binario del proyecto. +/// Prepara un conjunto de recursos para ser incluidos en el binario del proyecto. pub struct StaticFilesBundle { - dir: PathBuf, - filter: Option(dir: P, filter: Option (path: P, target_name: &str) -> Self
+ where
+ P: AsRef