136 lines
5.4 KiB
Markdown
136 lines
5.4 KiB
Markdown
<div align="center">
|
|
|
|
<img src="https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/banner.png" />
|
|
|
|
<h1>PageTop</h1>
|
|
|
|
<p>Un entorno para el desarrollo de soluciones web modulares, extensibles y configurables.</p>
|
|
|
|
[](#-license)
|
|
[](https://docs.rs/pagetop)
|
|
[](https://crates.io/crates/pagetop)
|
|
[](https://crates.io/crates/pagetop)
|
|
|
|
</div>
|
|
|
|
`PageTop` reivindica la esencia de la web clásica usando [Rust](https://www.rust-lang.org/es) para
|
|
la creación de soluciones web SSR (*renderizadas en el servidor*) basadas en HTML, CSS y JavaScript.
|
|
Ofrece un conjunto de herramientas que los desarrolladores pueden implementar, extender o adaptar
|
|
según las necesidades de cada proyecto, incluyendo:
|
|
|
|
* **Acciones** (*actions*): alteran la lógica interna de una funcionalidad interceptando su flujo
|
|
de ejecución.
|
|
* **Componentes** (*components*): encapsulan HTML, CSS y JavaScript en unidades funcionales,
|
|
configurables y reutilizables.
|
|
* **Extensiones** (*extensions*): añaden, extienden o personalizan funcionalidades usando las APIs
|
|
de `PageTop` o de terceros.
|
|
* **Temas** (*themes*): son extensiones que permiten modificar la apariencia de páginas y
|
|
componentes sin comprometer su funcionalidad.
|
|
|
|
|
|
# ⚡️ Guía rápida
|
|
|
|
La aplicación más sencilla de `PageTop` se ve así:
|
|
|
|
```rust
|
|
use pagetop::prelude::*;
|
|
|
|
#[pagetop::main]
|
|
async fn main() -> std::io::Result<()> {
|
|
Application::new().run()?.await
|
|
}
|
|
```
|
|
|
|
Este código arranca el servidor de `PageTop` que, con la configuración por defecto, muestra una
|
|
página de bienvenida accesible desde un navegador local en `http://localhost:8080`.
|
|
|
|
Para personalizar el servicio, se puede crear una extensión de `PageTop` de la siguiente manera:
|
|
|
|
```rust
|
|
use pagetop::prelude::*;
|
|
|
|
struct HelloWorld;
|
|
|
|
impl Extension for HelloWorld {
|
|
fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {
|
|
scfg.route("/", service::web::get().to(hello_world));
|
|
}
|
|
}
|
|
|
|
async fn hello_world(request: HttpRequest) -> ResultPage<Markup, ErrorPage> {
|
|
Page::new(Some(request))
|
|
.with_component(Html::with(move |_| html! { h1 { "Hello World!" } }))
|
|
.render()
|
|
}
|
|
|
|
#[pagetop::main]
|
|
async fn main() -> std::io::Result<()> {
|
|
Application::prepare(&HelloWorld).run()?.await
|
|
}
|
|
```
|
|
|
|
Este programa implementa una extensión llamada `HelloWorld` que sirve una página web en la ruta raíz
|
|
(`/`) mostrando el texto "Hello world!" dentro de un elemento HTML `<h1>`.
|
|
|
|
|
|
# 📂 Repositorio
|
|
|
|
El código se organiza en un *workspace* donde actualmente se incluyen los siguientes subproyectos:
|
|
|
|
* **[pagetop](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/src)**, con el código
|
|
fuente de la librería principal. Reúne algunos de los *crates* más estables y populares del
|
|
ecosistema Rust para proporcionar APIs y recursos para la creación avanzada de soluciones web.
|
|
|
|
## Auxiliares
|
|
|
|
* **[pagetop-build](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/helpers/pagetop-build)**,
|
|
permite incluir fácilmente archivos estáticos o archivos SCSS compilados directamente en el
|
|
binario de las aplicaciones `PageTop`.
|
|
|
|
* **[pagetop-macros](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/helpers/pagetop-macros)**,
|
|
proporciona una colección de macros que mejoran la experiencia de desarrollo con `PageTop`.
|
|
|
|
|
|
# 🧪 Pruebas
|
|
|
|
Para simplificar el flujo de trabajo, el repositorio incluye varios **alias de Cargo** declarados en
|
|
`.cargo/config.toml`. Basta con ejecutarlos desde la raíz del proyecto:
|
|
|
|
| Comando | Descripción |
|
|
| ------- | ----------- |
|
|
| `cargo ts` | Ejecuta los tests de `pagetop` (*unit + integration*) con la *feature* `testing`. |
|
|
| `cargo ts --test util` | Lanza sólo las pruebas de integración del módulo `util`. |
|
|
| `cargo ts --doc locale` | Lanza las pruebas de la documentación del módulo `locale`. |
|
|
| `cargo tw` | Ejecuta los tests de **todos los paquetes** del *workspace*. |
|
|
|
|
> **Nota**
|
|
> Estos alias ya compilan con la configuración adecuada. No requieren `--no-default-features`.
|
|
> Si quieres **activar** las trazas del registro de eventos entonces usa simplemente `cargo test`.
|
|
|
|
|
|
# 🚧 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
|
|
|
|
El código está disponible bajo una doble licencia:
|
|
|
|
* **Licencia MIT**
|
|
([LICENSE-MIT](LICENSE-MIT) o también https://opensource.org/licenses/MIT)
|
|
|
|
* **Licencia Apache, Versión 2.0**
|
|
([LICENSE-APACHE](LICENSE-APACHE) o también https://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
Puedes elegir la licencia que prefieras. Este enfoque de doble licencia es el estándar de facto en
|
|
el ecosistema Rust.
|
|
|
|
|
|
# ✨ Contribuir
|
|
|
|
Cualquier contribución para añadir al proyecto se considerará automáticamente bajo la doble licencia
|
|
indicada arriba (MIT o Apache v2.0), sin términos o condiciones adicionales, tal y como permite la
|
|
licencia *Apache v2.0*.
|