pagetop/lib.rs
1/*!
2<div align="center">
3
4<img src="https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/banner.png" />
5
6<h1>PageTop</h1>
7
8<p>Un entorno para el desarrollo de soluciones web modulares, extensibles y configurables.</p>
9
10[](#-licencia)
11[](https://docs.rs/pagetop)
12[](https://crates.io/crates/pagetop)
13[](https://crates.io/crates/pagetop)
14
15<br>
16</div>
17
18PageTop reivindica la esencia de la web clásica usando [Rust](https://www.rust-lang.org/es) para la
19creación de soluciones web SSR (*renderizadas en el servidor*) basadas en HTML, CSS y JavaScript.
20Ofrece un conjunto de herramientas que los desarrolladores pueden implementar, extender o adaptar
21según las necesidades de cada proyecto, incluyendo:
22
23 * **Acciones** (*actions*): alteran la lógica interna de una funcionalidad interceptando su flujo
24 de ejecución.
25 * **Componentes** (*components*): encapsulan HTML, CSS y JavaScript en unidades funcionales,
26 configurables y reutilizables.
27 * **Extensiones** (*extensions*): añaden, extienden o personalizan funcionalidades usando las APIs
28 de PageTop o de terceros.
29 * **Temas** (*themes*): son extensiones que permiten modificar la apariencia de páginas y
30 componentes sin comprometer su funcionalidad.
31
32
33# ⚡️ Guía rápida
34
35La aplicación más sencilla de PageTop se ve así:
36
37```rust,no_run
38use pagetop::prelude::*;
39
40#[pagetop::main]
41async fn main() -> std::io::Result<()> {
42 Application::new().run()?.await
43}
44```
45
46Este código arranca el servidor de PageTop. Con la configuración por defecto, muestra una página de
47bienvenida accesible desde un navegador local en la dirección `http://localhost:8080`.
48
49Para personalizar el servicio, se puede crear una extensión de PageTop de la siguiente manera:
50
51```rust,no_run
52use pagetop::prelude::*;
53
54struct HelloWorld;
55
56impl Extension for HelloWorld {
57 fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {
58 scfg.route("/", service::web::get().to(hello_world));
59 }
60}
61
62async fn hello_world(request: HttpRequest) -> ResultPage<Markup, ErrorPage> {
63 Page::new(request)
64 .add_component(Html::with(move |_| html! { h1 { "Hello World!" } }))
65 .render()
66}
67
68#[pagetop::main]
69async fn main() -> std::io::Result<()> {
70 Application::prepare(&HelloWorld).run()?.await
71}
72```
73
74Este programa implementa una extensión llamada `HelloWorld` que sirve una página web en la ruta raíz
75(`/`) mostrando el texto "Hello world!" dentro de un elemento HTML `<h1>`.
76
77
78# 🧩 Gestión de Dependencias
79
80Los proyectos que utilizan PageTop gestionan las dependencias con `cargo`, como cualquier otro
81proyecto en Rust.
82
83Sin embargo, es fundamental que cada extensión declare explícitamente sus
84[dependencias](core::extension::Extension::dependencies), si las tiene, para que PageTop pueda
85estructurar e inicializar la aplicación de forma modular.
86*/
87
88#![cfg_attr(docsrs, feature(doc_cfg))]
89#![doc(
90 html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
91)]
92
93// Alias para que las rutas absolutas `::pagetop::...` generadas por las macros funcionen en el
94// propio *crate*, en *crates* externos y en *doctests*.
95extern crate self as pagetop;
96
97use std::collections::HashMap;
98use std::ops::Deref;
99
100// RE-EXPORTED *************************************************************************************
101
102pub use pagetop_macros::{builder_fn, html, main, test, AutoDefault};
103
104pub use pagetop_statics::{resource, StaticResource};
105
106/// Contenedor para un conjunto de recursos embebidos.
107#[derive(AutoDefault)]
108pub struct StaticResources {
109 bundle: HashMap<&'static str, StaticResource>,
110}
111
112impl StaticResources {
113 /// Crea un contenedor para un conjunto de recursos generado por `build.rs` (consultar
114 /// [`pagetop_build`](https://docs.rs/pagetop-build)).
115 pub fn new(bundle: HashMap<&'static str, StaticResource>) -> Self {
116 Self { bundle }
117 }
118}
119
120impl Deref for StaticResources {
121 type Target = HashMap<&'static str, StaticResource>;
122
123 fn deref(&self) -> &Self::Target {
124 &self.bundle
125 }
126}
127
128/// Identificador único de un tipo estático durante la ejecución de la aplicación.
129///
130/// **Nota:** El valor es único sólo dentro del proceso actual y cambia en cada compilación.
131pub type UniqueId = std::any::TypeId;
132
133/// Representa el peso lógico de una instancia en una colección ordenada por pesos.
134///
135/// Las instancias con pesos **más bajos**, incluyendo valores negativos (`-128..127`), se situarán
136/// antes en la ordenación.
137pub type Weight = i8;
138
139// API *********************************************************************************************
140
141// Macros y funciones útiles.
142pub mod util;
143// Carga las opciones de configuración.
144pub mod config;
145// Opciones de configuración globales.
146pub mod global;
147// Gestión de trazas y registro de eventos de la aplicación.
148pub mod trace;
149// HTML en código.
150pub mod html;
151// Localización.
152pub mod locale;
153// Soporte a fechas y horas.
154pub mod datetime;
155// Tipos y funciones esenciales para crear acciones, componentes, extensiones y temas.
156pub mod core;
157// Respuestas a peticiones web en sus diferentes formatos.
158pub mod response;
159// Gestión del servidor y servicios web.
160pub mod service;
161// Reúne acciones, componentes, extensiones y temas predefinidos.
162pub mod base;
163// Prepara y ejecuta la aplicación.
164pub mod app;
165
166// PRELUDE *****************************************************************************************
167
168pub mod prelude;