✨ [website] Añade la web que presenta PageTop
This commit is contained in:
parent
ae2fa9d992
commit
265be3011d
38 changed files with 2030 additions and 46 deletions
11
website/doc/v0.0/en/book.toml
Normal file
11
website/doc/v0.0/en/book.toml
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
[book]
|
||||
authors = ["Manuel Cillero"]
|
||||
language = "en"
|
||||
src = "src"
|
||||
title = "PageTop Guides"
|
||||
|
||||
[build]
|
||||
build-dir = "../../../static/doc/v0.0/en"
|
||||
|
||||
[output.html]
|
||||
theme = "../../theme"
|
||||
3
website/doc/v0.0/en/src/404.md
Normal file
3
website/doc/v0.0/en/src/404.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Document not found (404)
|
||||
|
||||
This URL is invalid, sorry. Try the search instead!
|
||||
3
website/doc/v0.0/en/src/SUMMARY.md
Normal file
3
website/doc/v0.0/en/src/SUMMARY.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Summary
|
||||
|
||||
[Introduction](intro.md)
|
||||
3
website/doc/v0.0/en/src/intro.md
Normal file
3
website/doc/v0.0/en/src/intro.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
<div style="border: 1px solid black; padding: 10px; text-align: center;">
|
||||
<strong>This website is under construction</strong>.<br>If you're curious, you can read the <a href="/doc/latest/es">latest version of this guide in Spanish</a>.
|
||||
</div>
|
||||
11
website/doc/v0.0/es/book.toml
Normal file
11
website/doc/v0.0/es/book.toml
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
[book]
|
||||
authors = ["Manuel Cillero"]
|
||||
language = "es"
|
||||
src = "src"
|
||||
title = "Guías de PageTop"
|
||||
|
||||
[build]
|
||||
build-dir = "../../../static/doc/v0.0/es"
|
||||
|
||||
[output.html]
|
||||
theme = "../../theme"
|
||||
3
website/doc/v0.0/es/src/404.md
Normal file
3
website/doc/v0.0/es/src/404.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Documento no encontrado (404)
|
||||
|
||||
Esta URL no es válida, lo sentimos. ¡Intenta buscar en su lugar!
|
||||
17
website/doc/v0.0/es/src/SUMMARY.md
Normal file
17
website/doc/v0.0/es/src/SUMMARY.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
# Summary
|
||||
|
||||
[Introducción](intro.md)
|
||||
|
||||
# Inicio rápido
|
||||
|
||||
- [Comenzando](getting-started.md)
|
||||
- [Prepara tu entorno](configuration.md)
|
||||
- [Aplicaciones](apps.md)
|
||||
- [Paquetes](packages.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)
|
||||
1
website/doc/v0.0/es/src/actions.md
Normal file
1
website/doc/v0.0/es/src/actions.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
# Acciones
|
||||
61
website/doc/v0.0/es/src/apps.md
Normal file
61
website/doc/v0.0/es/src/apps.md
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
# Aplicaciones
|
||||
|
||||
Los programas de PageTop se denominan [Aplicaciones](https://docs.rs/pagetop/latest/pagetop/app/struct.Application.html). La aplicación PageTop más simple luce así:
|
||||
|
||||
```rust
|
||||
use pagetop::prelude::*;
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::new().run()?.await
|
||||
}
|
||||
```
|
||||
|
||||
La línea `use pagetop::prelude::*;` sirve para importar la API esencial de PageTop. Por brevedad, esta guía podría omitirla en ejemplos posteriores.
|
||||
|
||||
Ahora sólo tienes que copiar el código anterior en tu archivo `main.rs` y desde la carpeta del proyecto ejecutar:
|
||||
|
||||
```bash
|
||||
cargo run
|
||||
```
|
||||
|
||||
Si todo ha ido bien, después de compilar el código se ejecutará la aplicación. El terminal quedará en espera mostrando el *nombre* y *lema* predefinidos.
|
||||
|
||||
Ahora abre un navegador en el mismo equipo y escribe `http://localhost:8088` en la barra de direcciones. Y ya está, ¡la página de presentación de PageTop te dará la bienvenida!
|
||||
|
||||
Sin embargo, aún no hemos indicado a nuestra aplicación qué hacer.
|
||||
|
||||
|
||||
# Extendiendo PageTop
|
||||
|
||||
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.
|
||||
- [**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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
# ¿Qué hace una aplicación?
|
||||
|
||||
Como hemos visto arriba, primero se instancia la [Aplicación](https://docs.rs/pagetop/latest/pagetop/app/struct.Application.html). Podemos hacerlo usando [`new()`](https://docs.rs/pagetop/latest/pagetop/app/struct.Application.html#method.new), como en el ejemplo, o con [`prepare()`](https://docs.rs/pagetop/latest/pagetop/app/struct.Application.html#method.prepare), que veremos en la siguiente página. Ambos se encargan de iniciar los diferentes subsistemas de PageTop por este orden:
|
||||
|
||||
1. Inicializa la traza de mensajes de registro y eventos.
|
||||
|
||||
2. Valida el identificador global de idioma.
|
||||
|
||||
3. Conecta con la base de datos.
|
||||
|
||||
4. Registra los paquetes de la aplicación según sus dependencias internas.
|
||||
|
||||
5. Registra las acciones de los paquetes.
|
||||
|
||||
6. Inicializa los paquetes.
|
||||
|
||||
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!
|
||||
1
website/doc/v0.0/es/src/components.md
Normal file
1
website/doc/v0.0/es/src/components.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
# Componentes
|
||||
90
website/doc/v0.0/es/src/configuration.md
Normal file
90
website/doc/v0.0/es/src/configuration.md
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
# Prepara tu entorno
|
||||
|
||||
PageTop está escrito en Rust. Antes de empezar a crear tu aplicación web, es importante dedicar un tiempo a preparar tu entorno de desarrollo con Rust.
|
||||
|
||||
## Instalación de Rust
|
||||
|
||||
PageTop depende en gran medida de las mejoras que se aplican en el lenguaje y el compilador Rust. Procura tener instalada "*la última versión estable*" para admitir la Versión Mínima de Rust Soportada (MSRV) por PageTop.
|
||||
|
||||
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.
|
||||
|
||||
## Recursos para aprender Rust
|
||||
|
||||
El objetivo de esta guía es aprender a programar con PageTop rápidamente, por lo que no te va a servir como material de aprendizaje de Rust. Si deseas saber más sobre el [lenguaje de programación Rust](https://www.rust-lang.org), consulta los siguientes recursos:
|
||||
|
||||
* **[El Libro de Rust](https://doc.rust-lang.org/book/)**: el mejor lugar para aprender Rust desde cero.
|
||||
* **[Rust con Ejemplos](https://doc.rust-lang.org/rust-by-example/)**: aprende Rust programando ejemplos de todo tipo.
|
||||
* **[Rustlings](https://github.com/rust-lang/rustlings)**: una serie de ejercicios divertidos e interactivos para conocer Rust.
|
||||
|
||||
## Editor de código / IDE
|
||||
|
||||
Puedes usar tu editor de código preferido, pero se recomienda uno que permita instalar la extensión de [rust-analyzer](https://github.com/rust-lang/rust-analyzer). Aunque aún está en desarrollo, proporciona autocompletado y una inteligencia de código avanzada. [Visual Studio Code](https://code.visualstudio.com/) tiene una [extensión de rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) oficialmente soportada.
|
||||
|
||||
|
||||
# Tu primer proyecto PageTop
|
||||
|
||||
¡Ha llegado el momento de programar con PageTop! Inicialmente PageTop es sólo una dependencia más en tu proyecto. Puedes añadirlo a un proyecto ya existente o crear uno nuevo. Para ser completos, asumiremos que estás empezando desde cero.
|
||||
|
||||
## Crea un nuevo proyecto de ejecutable Rust
|
||||
|
||||
Primero, navega a una carpeta donde quieras crear tu nuevo proyecto. Luego, ejecuta el siguiente comando para crear una nueva carpeta que contenga nuestro proyecto de ejecutable Rust:
|
||||
|
||||
```bash
|
||||
cargo new my_pagetop_app
|
||||
cd my_pagetop_app
|
||||
```
|
||||
|
||||
Ahora ejecuta `cargo run` para compilar y ejecutar tu proyecto. Deberías ver el texto "Hello, world!" en tu terminal. Abre la carpeta "my_pagetop_app" en tu editor de código preferido y tómate un tiempo para revisar los archivos.
|
||||
|
||||
`main.rs` es el punto de entrada de tu programa:
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
println!("Hello, world!");
|
||||
}
|
||||
```
|
||||
|
||||
`Cargo.toml` es tu "archivo de proyecto". Contiene metadatos sobre tu proyecto, como su nombre, dependencias y configuración para compilarlo.
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "my_pagetop_app"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
La forma más fácil de incorporarlo en tu proyecto es usar `cargo add`:
|
||||
|
||||
```bash
|
||||
cargo add pagetop
|
||||
```
|
||||
|
||||
O puedes añadirlo manualmente en el archivo `Cargo.toml` del proyecto escribiendo:
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "my_pagetop_app"
|
||||
version = "0.1.0"
|
||||
edition = "2021" # debe ser 2021, o necesitarás configurar "resolver=2"
|
||||
|
||||
[dependencies]
|
||||
pagetop = "0.0.X" # siendo X la última versión de desarrollo
|
||||
```
|
||||
|
||||
Asegúrate de que se añade la última versión disponible de PageTop:
|
||||
|
||||
[](https://crates.io/crates/pagetop)
|
||||
|
||||
## Construye PageTop
|
||||
|
||||
Ahora ejecuta `cargo run` nuevamente. Las dependencias de PageTop deberían comenzar a compilarse. Tomará algo de tiempo ya que es la primera compilación de tu proyecto con PageTop. Esto sólo ocurrirá la primera vez. ¡Cada compilación después de esta será más rápida!
|
||||
|
||||
Ahora que tenemos nuestro proyecto PageTop preparado, ¡estamos listos para programar nuestra primera aplicación PageTop!
|
||||
40
website/doc/v0.0/es/src/getting-started.md
Normal file
40
website/doc/v0.0/es/src/getting-started.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# Comenzando
|
||||
|
||||
Esta sección te ayudará a conocer PageTop de la manera más rápida posible. Te enseñará a preparar un entorno de desarrollo apropiado para crear una aplicación web sencilla usando PageTop.
|
||||
|
||||
|
||||
# Inicio rápido
|
||||
|
||||
Si quieres entrar de lleno en el código de PageTop y ya cuentas con un entorno de Rust operativo puedes seguir leyendo este apartado de "inicio rápido".
|
||||
|
||||
En otro caso puedes pasar a la siguiente página para preparar un entorno de Rust desde cero y empezar a programar tu primera aplicación web con PageTop.
|
||||
|
||||
<!-- Nota: la configuración para "compilaciones rápidas" se encuentra en la próxima página, por lo que podrías querer leer esa sección primero. -->
|
||||
|
||||
## Empieza con los ejemplos
|
||||
|
||||
1. Clona el [repositorio de PageTop](https://github.com/manuelcillero/pagetop):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/manuelcillero/pagetop
|
||||
```
|
||||
|
||||
2. Cambia a la carpeta recién creada "pagetop":
|
||||
|
||||
```bash
|
||||
cd pagetop
|
||||
```
|
||||
|
||||
3. Asegurate de que trabajas con la última versión de PageTop (ya que por defecto se descarga la rama principal de git):
|
||||
|
||||
```bash
|
||||
git checkout latest
|
||||
```
|
||||
|
||||
4. Prueba los ejemplos de la [carpeta de ejemplos](https://github.com/manuelcillero/pagetop/tree/latest/examples):
|
||||
|
||||
```bash
|
||||
cargo run --example hello-world
|
||||
```
|
||||
|
||||
Recuerda que cada ejecución pone en marcha un servidor web. Tendrás que abrir un navegador y acceder a la dirección `http://localhost:8088` (según configuración predeterminada) para comprobar el funcionamiento de los servicios web ofrecidos por cada ejemplo. Para detener la ejecución del servidor bastará con pulsar `Ctrl-C` en el terminal.
|
||||
42
website/doc/v0.0/es/src/intro.md
Normal file
42
website/doc/v0.0/es/src/intro.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# Introducción
|
||||
|
||||
Si quieres aprender a construir soluciones web que rescaten la esencia de los orígenes usando HTML, CSS y JavaScript para crear páginas web ofrecidas desde un servidor, pero con la potencia de un lenguaje de programación rápido y seguro como Rust, entonces... ¡has llegado a buen puerto!
|
||||
|
||||
|
||||
# ¿Qué es PageTop?
|
||||
|
||||
**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:
|
||||
|
||||
- [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.
|
||||
- [Fluent templates](https://github.com/XAMPPRocky/fluent-templates), que incorpora [Fluent](https://projectfluent.org/) para internacionalizar los proyectos.
|
||||
- [SeaORM](https://github.com/SeaQL/sea-orm), que usa [SQLx](https://github.com/launchbadge/sqlx) para modelar el acceso a bases de datos.
|
||||
- Integra versiones *ad hoc* de [config-rs](https://github.com/mehcode/config-rs) y [Maud](https://github.com/lambda-fairy/maud) en su código.
|
||||
- Y usa otras librerías que puedes ver en el archivo [`Cargo.toml`](https://github.com/manuelcillero/pagetop/blob/latest/Cargo.toml) de PageTop.
|
||||
|
||||
|
||||
# SSR
|
||||
|
||||
El *Renderizado desde el Servidor* (SSR) es una técnica de desarrollo web en la que el contenido HTML se genera en el servidor antes de enviarlo al navegador del usuario, donde CSS y JavaScript añaden la interactividad necesaria. PageTop encapsula todos estos elementos en **componentes** unitarios que pueden mantenerse de forma independiente y ser extendidos o modificados por otras librerías.
|
||||
|
||||
Esto contrasta con la *Renderización desde el Cliente* (CSR), donde es el navegador el que genera el contenido HTML tras recibir el código WebAssembly o JavaScript necesario desde el servidor.
|
||||
|
||||
PageTop usa SSR como una solución robusta para la creación de soluciones web complejas. Pero también presenta desafíos, como ciclos de desarrollo más lentos por la necesidad de recompilar cada cambio en el código Rust. No obstante, ofrece excelentes tiempos de carga iniciales, mejora en el SEO, y unifica el desarrollo en cliente y servidor bajo un mismo lenguaje.
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
# Advertencia
|
||||
|
||||
PageTop está aún en las primeras etapas de desarrollo. Faltan características importantes y otras no funcionan como deberían. Y la documentación es escasa. Sólo se liberan versiones de desarrollo con cambios importantes en la API que desaconseja su uso en producción. Úsalo si estás interesado en conocerlo o quieres contribuir.
|
||||
|
||||
Si necesitas un entorno *fullstack* estable y robusto para tu próximo proyecto, puedes mirar [Perseus](https://github.com/framesurge/perseus) basado en la excelente librería [Sycamore](https://github.com/sycamore-rs/sycamore), también te entusiasmará [Rocket](https://github.com/rwf2/Rocket), sin descartar [MoonZoon](https://github.com/MoonZoon/MoonZoon) o [Percy](https://github.com/chinedufn/percy). Y puedes crear tu propio *framework* combinando soluciones como [Yew](https://yew.rs/), [Leptos](https://leptos.dev/) o [Dioxus](https://dioxuslabs.com/) con el servidor [Axum](https://github.com/tokio-rs/axum) y el ORM [Diesel](https://github.com/diesel-rs/diesel) para construir increíbles aplicaciones [SSR](https://en.wikipedia.org/wiki/Server-side_scripting).
|
||||
|
||||
Si aún sigues por aquí, ¡ha llegado el momento de empezar a aprender algo de PageTop!
|
||||
|
||||
La guía de [Inicio Rápido](getting-started.html) te enseñará a probar los ejemplos. También te ayudará con la [configuración](configuration.html) de tu entorno de desarrollo y te orientará con los próximos pasos a seguir.
|
||||
56
website/doc/v0.0/es/src/packages.md
Normal file
56
website/doc/v0.0/es/src/packages.md
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
# Paquetes
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Los paquetes 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:
|
||||
|
||||
```rust
|
||||
use pagetop::prelude::*;
|
||||
|
||||
struct HelloWorld;
|
||||
|
||||
impl PackageTrait 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(request)
|
||||
.with_component(Html::with(html! { h1 { "Hello World!" } }))
|
||||
.render()
|
||||
}
|
||||
|
||||
#[pagetop::main]
|
||||
async fn main() -> std::io::Result<()> {
|
||||
Application::prepare(&HelloWorld).run()?.await
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
`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!*.
|
||||
|
||||
Ahora si compilamos y ejecutamos nuestra aplicación con `cargo run` y en el navegador volvemos a cargar la dirección `http://localhost:8088`, veremos el saludo esperado.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
Cualquier sospecha sobre paquetes malintencionados debe ser reportado confidencialmente al administrador de PageTop para ser analizado por la comunidad.
|
||||
<!--
|
||||
## El registro de paquetes
|
||||
|
||||
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.
|
||||
-->
|
||||
1
website/doc/v0.0/es/src/themes.md
Normal file
1
website/doc/v0.0/es/src/themes.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
# Temas
|
||||
|
|
@ -0,0 +1,156 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue