🚚 Gran actualización de Paquetes a Extensiones
This commit is contained in:
parent
f6b76caf8d
commit
3faaaa76ee
443 changed files with 1123 additions and 444 deletions
|
|
@ -7,11 +7,11 @@
|
|||
- [Comenzando](getting-started.md)
|
||||
- [Prepara tu entorno](configuration.md)
|
||||
- [Aplicaciones](apps.md)
|
||||
- [Paquetes](packages.md)
|
||||
- [Extensiones](extensions.md)
|
||||
- [Componentes](components.md)
|
||||
- [Acciones](actions.md)
|
||||
- [Temas](themes.md)
|
||||
|
||||
# Tutoriales
|
||||
|
||||
- [Cómo crear un paquete desde cero](tutorials/create-a-package-from-scratch.md)
|
||||
- [Cómo crear una extensión desde cero](tutorials/create-a-extension-from-scratch.md)
|
||||
|
|
|
|||
|
|
@ -30,10 +30,10 @@ Sin embargo, aún no hemos indicado a nuestra aplicación qué hacer.
|
|||
|
||||
La [API de PageTop](https://docs.rs/pagetop) ofrece cuatro instrumentos esenciales para construir una aplicación:
|
||||
|
||||
- [**Paquetes**](packages.md), que añaden, amplían o personalizan funcionalidades interactuando con la API de PageTop o las APIs de paquetes de terceros.
|
||||
- [**Extensiones**](extensions.md), que añaden, amplían o personalizan funcionalidades interactuando con la API de PageTop o las APIs de extensiones de terceros.
|
||||
- [**Componentes**](components.md), para encapsular HTML, CSS y JavaScript en unidades funcionales, configurables y bien definidas.
|
||||
- [**Acciones**](actions.md), alteran el comportamiento interno de otros elementos de PageTop interceptando su flujo de ejecución.
|
||||
- [**Temas**](themes.md), son *paquetes* que permiten a los desarrolladores cambiar la apariencia de páginas y componentes sin afectar su funcionalidad.
|
||||
- [**Temas**](themes.md), son *extensiones* que permiten a los desarrolladores cambiar la apariencia de páginas y componentes sin afectar su funcionalidad.
|
||||
|
||||
Si quieres saber más sobre el funcionamiento interno de las aplicaciones, continúa leyendo. Si no, puedes saltar a la siguiente página y empezar a añadir lógica a nuestra primera aplicación.
|
||||
|
||||
|
|
@ -48,14 +48,14 @@ Como hemos visto arriba, primero se instancia la [Aplicación](https://docs.rs/p
|
|||
|
||||
3. Conecta con la base de datos.
|
||||
|
||||
4. Registra los paquetes de la aplicación según sus dependencias internas.
|
||||
4. Registra las extensiones de la aplicación según sus dependencias internas.
|
||||
|
||||
5. Registra las acciones de los paquetes.
|
||||
5. Registra las acciones de las extensiones.
|
||||
|
||||
6. Inicializa los paquetes.
|
||||
6. Inicializa las extensiones.
|
||||
|
||||
7. Ejecuta las actualizaciones pendientes de la base de datos.
|
||||
|
||||
Pero no ejecuta la aplicación. Para eso se usa el método [`run()`](https://docs.rs/pagetop/latest/pagetop/app/struct.Application.html#method.run), que arranca el servidor web para empezar a responder las peticiones desde cualquier navegador.
|
||||
|
||||
Hablaremos más de todos estos subsistemas en próximas páginas. Mientras tanto, ¡vamos a añadir algo de lógica a nuestra aplicación creando un paquete con un nuevo servicio web!
|
||||
Hablaremos más de todos estos subsistemas en próximas páginas. Mientras tanto, ¡vamos a añadir algo de lógica a nuestra aplicación creando una extensión con un nuevo servicio web!
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ PageTop depende en gran medida de las mejoras que se aplican en el lenguaje y el
|
|||
|
||||
Puedes instalar Rust siguiendo la [Guía de Inicio Rápido de Rust](https://www.rust-lang.org/learn/get-started).
|
||||
|
||||
Una vez completada la instalación, tendrás disponibles en tu sistema el compilador `rustc` y `cargo` para la construcción y gestión de paquetes (*crates*) de Rust.
|
||||
Una vez completada la instalación, tendrás disponibles en tu sistema el compilador `rustc` y `cargo` para la construcción y gestión de *crates* de Rust.
|
||||
|
||||
## Recursos para aprender Rust
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ edition = "2021"
|
|||
|
||||
## Añade PageTop como dependencia
|
||||
|
||||
PageTop está disponible como [biblioteca en crates.io](https://crates.io/crates/pagetop), el repositorio oficial de paquetes (*crates*) Rust.
|
||||
PageTop está disponible como [biblioteca en crates.io](https://crates.io/crates/pagetop), el repositorio oficial de *crates* Rust.
|
||||
|
||||
La forma más fácil de incorporarlo en tu proyecto es usar `cargo add`:
|
||||
|
||||
|
|
|
|||
1
website/doc/v0.0/es/src/extensions.md
Normal file
1
website/doc/v0.0/es/src/extensions.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
# Extensiones
|
||||
|
|
@ -7,7 +7,7 @@ Si quieres aprender a construir soluciones web que rescaten la esencia de los or
|
|||
|
||||
**PageTop** es un marco de desarrollo web que proporciona herramientas y patrones de diseño predefinidos para el desarrollo de soluciones web seguras, modulares y personalizables con *Renderizado desde el Servidor* ([SSR](#ssr)).
|
||||
|
||||
PageTop está desarrollado en el [lenguaje de programación Rust](https://www.rust-lang.org/) y se apoya sobre los hombros de auténticos gigantes, porque utiliza algunas de las librerías (*crates*) más estables y reconocidas del [ecosistema Rust](https://lib.rs) como:
|
||||
PageTop está desarrollado en el [lenguaje de programación Rust](https://www.rust-lang.org/) y se apoya sobre los hombros de auténticos gigantes, porque utiliza algunas de las librerías más estables y reconocidas del [ecosistema Rust](https://lib.rs) como:
|
||||
|
||||
- [Actix Web](https://github.com/actix/actix-web), para la gestión de los servicios y del servidor web.
|
||||
- [Tracing](https://github.com/tokio-rs/tracing), para el sistema de diagnóstico y mensajes de registro estructurados.
|
||||
|
|
@ -28,7 +28,7 @@ PageTop usa SSR como una solución robusta para la creación de soluciones web c
|
|||
|
||||
# Contribuciones
|
||||
|
||||
PageTop [empezó como un proyecto personal](https://manuel.cillero.es/blog/aprendiendo-rust-presentando-pagetop/) para aprender a programar con Rust. Es [libre y de código abierto](https://github.com/manuelcillero/pagetop#-license), para siempre. Y puedes contribuir aumentando su versatilidad, documentando, traduciendo o corrigiendo errores. Pero también puedes crear tus propios paquetes o temas que otros desarrolladores podrán utilizar en sus proyectos.
|
||||
PageTop [empezó como un proyecto personal](https://manuel.cillero.es/blog/aprendiendo-rust-presentando-pagetop/) para aprender a programar con Rust. Es [libre y de código abierto](https://github.com/manuelcillero/pagetop#-license), para siempre. Y puedes contribuir aumentando su versatilidad, documentando, traduciendo o corrigiendo errores. Pero también puedes crear tus propias extensiones o temas que otros desarrolladores podrán utilizar en sus proyectos.
|
||||
|
||||
|
||||
# Advertencia
|
||||
|
|
|
|||
|
|
@ -1,21 +1,21 @@
|
|||
# Paquetes
|
||||
# Extensiones
|
||||
|
||||
Una de las características más poderosas de PageTop es su extensibilidad mediante el uso de [Paquetes](https://docs.rs/pagetop/latest/pagetop/core/package/index.html). Los paquetes añaden, amplían o personalizan funcionalidades para nuestra aplicación.
|
||||
Una de las características más poderosas de PageTop es su extensibilidad mediante el uso de [Extensiones](https://docs.rs/pagetop/latest/pagetop/core/extension/index.html). Las extensiones añaden, amplían o personalizan funcionalidades para nuestra aplicación.
|
||||
|
||||
Un paquete es una [estructura unitaria](https://stackoverflow.com/questions/67689613/what-is-a-real-world-example-of-using-a-unit-struct) (*unit struct*) que implementa el *trait* [`PackageTrait`](https://docs.rs/pagetop/latest/pagetop/core/package/trait.PackageTrait.html). Los métodos de [`PackageTrait`](https://docs.rs/pagetop/latest/pagetop/core/package/trait.PackageTrait.html) tienen un funcionamiento predefinido que se puede personalizar.
|
||||
Una extensión es una [estructura unitaria](https://stackoverflow.com/questions/67689613/what-is-a-real-world-example-of-using-a-unit-struct) (*unit struct*) que implementa el *trait* [`ExtensionTrait`](https://docs.rs/pagetop/latest/pagetop/core/extension/trait.ExtensionTrait.html). Los métodos de [`ExtensionTrait`](https://docs.rs/pagetop/latest/pagetop/core/extension/trait.ExtensionTrait.html) tienen un funcionamiento predefinido que se puede personalizar.
|
||||
|
||||
Los paquetes tienen acceso a puntos de nuestra aplicación donde PageTop permite que el código de terceros haga ciertas cosas.
|
||||
Las extensiones tienen acceso a puntos de nuestra aplicación donde PageTop permite que el código de terceros haga ciertas cosas.
|
||||
|
||||
## ¡Hola mundo!
|
||||
|
||||
Para añadir lógica a nuestra [aplicación](apps.html) puedes crear un paquete en tu archivo `main.rs` sustituyendo el código de ejemplo por este nuevo código:
|
||||
Para añadir lógica a nuestra [aplicación](apps.html) puedes crear una extensión en tu archivo `main.rs` sustituyendo el código de ejemplo por este nuevo código:
|
||||
|
||||
```rust
|
||||
use pagetop::prelude::*;
|
||||
|
||||
struct HelloWorld;
|
||||
|
||||
impl PackageTrait for HelloWorld {
|
||||
impl ExtensionTrait for HelloWorld {
|
||||
fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {
|
||||
scfg.route("/", service::web::get().to(hello_world));
|
||||
}
|
||||
|
|
@ -33,7 +33,7 @@ async fn main() -> std::io::Result<()> {
|
|||
}
|
||||
```
|
||||
|
||||
La función `main()` instancia la aplicación usando el método `prepare()` con una referencia ([`PackageRef`](https://docs.rs/pagetop/latest/pagetop/core/package/type.PackageRef.html)) al paquete `HelloWorld`. Así se indica a PageTop que debe incluirlo en su registro interno de paquetes.
|
||||
La función `main()` instancia la aplicación usando el método `prepare()` con una referencia ([`ExtensionRef`](https://docs.rs/pagetop/latest/pagetop/core/extension/type.ExtensionRef.html)) a la extensión `HelloWorld`. Así se indica a PageTop que debe incluirlo en su registro interno de extensiones.
|
||||
|
||||
`HelloWorld` configura un servicio en la ruta de inicio ("/") que se implementa en `hello_world()`. Esta función devuelve una página web con un componente que directamente renderiza código HTML para mostrar un título con el texto *Hello World!*.
|
||||
|
||||
|
|
@ -41,16 +41,16 @@ Ahora si compilamos y ejecutamos nuestra aplicación con `cargo run` y en el nav
|
|||
|
||||
## Librerías
|
||||
|
||||
Los paquetes en PageTop son *crates* de biblioteca, usualmente publicados en [crates.io](https://crates.io/search?q=pagetop), que puedes usar como dependencias en tu aplicación.
|
||||
Las extensiones en PageTop son *crates* de biblioteca, usualmente publicados en [crates.io](https://crates.io/search?q=pagetop), que puedes usar como dependencias en tu aplicación.
|
||||
|
||||
|
||||
# Seguridad
|
||||
|
||||
Los paquetes ajenos a PageTop contienen código desarrollado por terceros y, dado que pueden hacer básicamente lo que quieran, pueden representar un serio riesgo para la seguridad de tu sistema. Por ejemplo, un paquete podría indicar que está analizando la entrada del usuario y realmente está descargando ransomware en tu computadora.
|
||||
Las extensiones ajenas a PageTop contienen código desarrollado por terceros y, dado que pueden hacer básicamente lo que quieran, pueden representar un serio riesgo para la seguridad de tu sistema. Por ejemplo, una extensión podría indicar que está analizando la entrada del usuario y realmente está descargando ransomware en tu computadora.
|
||||
|
||||
Cualquier sospecha sobre paquetes malintencionados debe ser reportado confidencialmente al administrador de PageTop para ser analizado por la comunidad.
|
||||
Cualquier sospecha sobre extensiones malintencionadas debe ser reportada confidencialmente al administrador de PageTop para ser analizado por la comunidad.
|
||||
<!--
|
||||
## El registro de paquetes
|
||||
## El registro de extensiones
|
||||
|
||||
En este sitio web, se mantiene un registro de todos los paquetes conocidos. El ecosistema es joven. Los paquetes respaldados por la comunidad de PageTop tendrán una marca de verificación, aunque PageTop no se responsabiliza de ningún modo por paquetes malintencionados al ser código de terceros. Puedes añadir tus propios paquetes al registro siguiendo las instrucciones en nuestro sistema de reporte de issues, que te guiará a través del proceso.
|
||||
En este sitio web, se mantiene un registro de todas las extensiones conocidas. El ecosistema es joven. Las extensiones respaldadas por la comunidad de PageTop tendrán una marca de verificación, aunque PageTop no se responsabiliza de ningún modo por extensiones malintencionadas al ser código de terceros. Puedes añadir tus propias extensiones al registro siguiendo las instrucciones en nuestro sistema de reporte de issues, que te guiará a través del proceso.
|
||||
-->
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
# Cómo crear una extensión desde cero
|
||||
|
|
@ -1,156 +0,0 @@
|
|||
# Cómo crear un paquete desde cero
|
||||
|
||||
Este tutorial describe cómo se ha creado el módulo `pagetop-jquery` para incluir la librería [jQuery](https://jquery.com) en las páginas web generadas por otros módulos o aplicaciones desarrolladas con **PageTop**.
|
||||
|
||||
|
||||
# Primeros pasos
|
||||
|
||||
Para este tutorial se suponen conocimientos de programación con [Rust](https://www.rust-lang.org), del gestor de paquetes [`cargo`](https://doc.rust-lang.org/stable/cargo), así como de la [API de PageTop](https://docs.rs/pagetop). Los ejemplos están pensados para entornos Linux pero no deberían ser muy diferentes en otros sistemas operativos.
|
||||
|
||||
## Crear el proyecto
|
||||
|
||||
La forma más sencilla de empezar es rompiendo el hielo con el gestor de paquetes `cargo` siguiendo los mismos pasos que en cualquier otro proyecto Rust:
|
||||
|
||||
```bash
|
||||
cargo new --lib pagetop-jquery
|
||||
```
|
||||
|
||||
Accede al proyecto recién creado y añade la dependiencia a **PageTop**:
|
||||
|
||||
```bash
|
||||
cd pagetop-jquery
|
||||
cargo add pagetop
|
||||
```
|
||||
|
||||
## Soporte multilingüe
|
||||
|
||||
La [API de localización](https://docs.rs/pagetop/latest/pagetop/locale/index.html) de **PageTop** proporciona soporte multilingüe a los módulos. Primero crea la estructura de carpetas para los archivos de los textos en inglés y español (únicos idiomas soportados actualmente):
|
||||
|
||||
```bash
|
||||
mkdir src/locale
|
||||
mkdir src/locale/en-US
|
||||
mkdir src/locale/es-ES
|
||||
```
|
||||
|
||||
Crea el archivo `src\locale\en-US\module.flt` con las siguientes asignaciones para identificar y describir el módulo:
|
||||
|
||||
```ini
|
||||
package_name = jQuery support
|
||||
package_description = Integrate the jQuery library into web pages generated by other modules.
|
||||
```
|
||||
|
||||
Y su archivo equivalente `src\locale\es-ES\module.flt` para las mismas asignaciones en español:
|
||||
|
||||
```ini
|
||||
package_name = Soporte a jQuery
|
||||
package_description = Incorpora la librería jQuery en páginas web generadas por otros módulos.
|
||||
```
|
||||
|
||||
Estas primeras asignaciones suelen ser habituales en todos los módulos.
|
||||
|
||||
## Iniciar el módulo
|
||||
|
||||
Para desarrollar un módulo **PageTop** hay que implementar los métodos necesarios del *trait* [`ModuleTrait`](https://docs.rs/pagetop/latest/pagetop/core/module/trait.ModuleTrait.html) sobre una estructura vacía que se puede inicializar en el archivo `src/lib.rs`:
|
||||
|
||||
```rust
|
||||
use pagetop::prelude::*;
|
||||
|
||||
static_locales!(LOCALES_JQUERY);
|
||||
|
||||
#[derive(AssignHandle)]
|
||||
pub struct JQuery;
|
||||
|
||||
impl ModuleTrait for JQuery {
|
||||
fn name(&self) -> L10n {
|
||||
L10n::t("package_name", &LOCALES_JQUERY)
|
||||
}
|
||||
|
||||
fn description(&self) -> L10n {
|
||||
L10n::t("package_description", &LOCALES_JQUERY)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
La función [`handle()`](https://docs.rs/pagetop/latest/pagetop/core/module/trait.ModuleTrait.html#method.handle) es la única que obligatoriamente debe implementarse porque permite asignar al módulo un identificador único creado previamente con la macro [`create_handle!()`](https://docs.rs/pagetop/latest/pagetop/macro.create_handle.html).
|
||||
|
||||
El soporte multilingüe se incorpora con la macro [`static_locales!()`](https://docs.rs/pagetop/latest/pagetop/macro.static_locales.html) asignando un identificador a la ruta de los archivos de localización (que puede omitirse si la ruta es `src/locale`).
|
||||
|
||||
Las funciones [`name()`](https://docs.rs/pagetop/latest/pagetop/core/module/trait.ModuleTrait.html#method.name) y [`description()`](https://docs.rs/pagetop/latest/pagetop/core/module/trait.ModuleTrait.html#method.description) son opcionales, aunque se recomienda su implementación para identificar y describir adecuadamente el módulo. Hacen uso del componente [`L10n`](https://docs.rs/pagetop/latest/pagetop/base/component/struct.L10n.html) y de los archivos de localización creados en el apartado anterior para devolver los textos en el idioma del contexto.
|
||||
|
||||
# Archivos estáticos
|
||||
|
||||
Seguimos en el directorio del proyecto, al mismo nivel de `src`. Es buena práctica crear una carpeta de nombre `static` para los archivos estáticos. En ella descargaremos los archivos `jquery.min.js` y `jquery.min.map` de la librería **jQuery**:
|
||||
|
||||
```bash
|
||||
mkdir static
|
||||
```
|
||||
|
||||
## Crear el archivo build.rs
|
||||
|
||||
Para que estos archivos estáticos formen parte del binario de la aplicación hay que añadir dos nuevas dependencias al proyecto:
|
||||
|
||||
```bash
|
||||
cargo add static-files
|
||||
cargo add pagetop-build --build
|
||||
```
|
||||
|
||||
Y crear un archivo `build.rs` con el siguiente código para incorporar el directorio `./static` en los recursos de compilación del proyecto:
|
||||
|
||||
```rust
|
||||
use pagetop_build::StaticFilesBundle;
|
||||
|
||||
fn main() -> std::io::Result<()> {
|
||||
StaticFilesBundle::from_dir("./static")
|
||||
.with_name("jquery")
|
||||
.build()
|
||||
}
|
||||
```
|
||||
|
||||
En este momento el proyecto tiene la siguiente estructura de directorios y archivos:
|
||||
|
||||
```bash
|
||||
pagetop-jquery/
|
||||
├── src/
|
||||
│ ├── locale/
|
||||
│ │ ├── en-ES/
|
||||
│ │ │ └── module.flt
|
||||
│ │ └── es-ES/
|
||||
│ │ └── module.flt
|
||||
│ └── lib.rs
|
||||
├── static/
|
||||
│ ├── jquery.min.js
|
||||
│ └── jquery.min.map
|
||||
└── Cargo.toml
|
||||
```
|
||||
|
||||
## Declarar los archivos en el módulo
|
||||
|
||||
En `src/lib.rs` incorpora los recursos estáticos con `static_files!()` usando como identificador el nombre proporcionado al *bundle* de archivos en `build.rs` con `.with_name("jquery")`, pero ahora sin las comillas dobles:
|
||||
|
||||
```rust
|
||||
static_files!(jquery);
|
||||
```
|
||||
|
||||
Y en la implementación de `JQuery` añade la función `configure_service()` para configurar el servicio web que responderá a las peticiones cuando el *path* comience por `/jquery/*` usando la macro [`configure_service_for_static_files!()`]():
|
||||
|
||||
```rust
|
||||
impl ModuleTrait for JQuery {
|
||||
...
|
||||
fn configure_service(&self, cfg: &mut service::web::ServiceConfig) {
|
||||
configure_service_for_static_files!(cfg, jquery => "/jquery");
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
De esta forma, a la petición `/jquery/jquery.min.js` el servidor web responderá devolviendo el archivo estático `./static/jquery.min.js`.
|
||||
|
||||
# La API del módulo
|
||||
|
||||
Este módulo proporciona funciones públicas para añadir o quitar del contexto los recursos de **jQuery**:
|
||||
|
||||
--------------------
|
||||
|
||||
***Notas***
|
||||
|
||||
* Puede que el código del módulo no sea el mismo que aquí se reproduce. El sentido de este tutorial es proporcionar una explicación sencilla de los principales elementos de un módulo.
|
||||
|
|
@ -8,7 +8,7 @@ include_locales!(LOCALES_WEBSITE);
|
|||
|
||||
struct PageTopWebSite;
|
||||
|
||||
impl PackageTrait for PageTopWebSite {
|
||||
impl ExtensionTrait for PageTopWebSite {
|
||||
fn name(&self) -> L10n {
|
||||
L10n::t("app_name", &LOCALES_WEBSITE)
|
||||
}
|
||||
|
|
@ -17,9 +17,9 @@ impl PackageTrait for PageTopWebSite {
|
|||
L10n::t("app_description", &LOCALES_WEBSITE)
|
||||
}
|
||||
|
||||
fn dependencies(&self) -> Vec<PackageRef> {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![
|
||||
// Paquetes.
|
||||
// Extensiones.
|
||||
&pagetop_mdbook::MdBook,
|
||||
// Temas.
|
||||
&pagetop_bootsier::Bootsier,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue